Guides / kosa8 Cloud / Secrets
Secrets
Store an API key or token once for your organization, then name it when you create a sandbox. The real value never enters the sandbox. The sandbox gets a placeholder and a URL. A broker on the host, outside the sandbox's VM, sends each request on to that secret's upstream with the real value swapped in.
Store a secret
curl -s -X PUT https://api.kosa8.com/v1/secrets/openai \
-H "Authorization: Bearer $KOSA8_ADMIN_KEY" -H 'Content-Type: application/json' \
-d '{"value":"'"$OPENAI_API_KEY"'","upstream":"https://api.openai.com",
"env":{"OPENAI_API_KEY":"{{placeholder}}","OPENAI_BASE_URL":"{{url}}/v1"}}'
# {"secret":{"name":"openai","upstream":"https://api.openai.com","header":"Authorization","scheme":"Bearer ",…},"replaced":false}
- name: 1 to 32 characters from a-z, 0-9 and
-. An organization has up to 50 secrets. - upstream:
https://hostorhttps://host:port, with no path. This is the only place the value is ever sent. - header and scheme: how the value travels. The default is
Authorization: Bearer …; use{"header":"x-api-key"}for Anthropic. - methods and paths (optional): limit the secret to those HTTP
methods and to upstream path prefixes such as
/v1/. - env: what the sandbox is given.
{{placeholder}}becomes a random stand-in for the value, and{{url}}becomes the broker's address for this secret. The default isNAME_API_KEYandNAME_BASE_URL.
The value is encrypted at rest (AES-256-GCM). No route returns it, and it is never written to
the audit log. GET /v1/secrets lists names and upstreams. Writing or deleting a secret
needs an admin key.
Create a sandbox with it
curl -s -X POST https://api.kosa8.com/v1/sandboxes \
-H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
-d '{"size":"2x4","persistent":true,"secrets":["openai"],"egress":{"presets":["pypi"]}}'
# 202 {"sandbox":{"id":"sbx_…","state":"creating",…,"secrets":["openai"],
# "env":["OPENAI_API_KEY","OPENAI_BASE_URL"],"egress":{…,"enforced":"allow:pypi.org,files.pythonhosted.org"}}}
Every command the sandbox runs gets the variables. In this example, OPENAI_BASE_URL is
something like http://10.0.2.3:40123/openai/v1 and OPENAI_API_KEY is a
placeholder. The OpenAI SDK reads both, so code inside the sandbox runs unchanged:
python -c 'from openai import OpenAI; print(OpenAI().models.list().data[0].id)'
A variable you pass on an exec env wins over a secret's, so you can override one.
GET /v1/sandboxes/{id}/secrets shows which secrets a sandbox was created with.
Rules that come with it
- A sandbox booted for you. The broker's address is wired into the VM's network
when the VM is created. Pool VMs are started before anyone claims them, so they cannot have one. A
create with secrets must name a size (
size, orcpusandmem_mb), animageor adisk_gb, and it boots cold (202, then running). - It never sleeps. The values live only in the host daemon's memory, never on
disk and never in a snapshot. So
sleep_after_sis 0, and sleep, checkpoint, rewind and fork answer409 {"code":"secrets"}. Delete the sandbox when you are done; it is billed while it runs. - No open internet. Without
egress, the sandbox reaches nothing but its secrets' upstreams, through the broker. An allow list or presets work as usual.internet: trueand deny-only policies are refused, because the broker would be optional beside an open network. The policy is set at boot and cannot be changed later. - Changes apply to new sandboxes only. Replacing or deleting a secret does not
touch running sandboxes; they keep the value they started with until you delete them. The answer
to
DELETE /v1/secrets/{name}lists them instill_held_by.
What the broker does and does not stop
- The sandbox can use the secret, but only for requests to its upstream, and only within its methods and paths. It cannot read the value: not from its environment, not from a response header that echoes it (the broker drops those), and not by redirecting the request somewhere else (the broker never follows redirects).
- The placeholder is a capability. Anything in the sandbox that can reach the broker can spend
the key on the requests the secret allows. Scope the key at its provider, and narrow it here with
methodsandpaths. - Response bodies are not filtered. An upstream that echoes the key in a body leaks it.
- Every credentialed request is recorded in the host's audit chain: host, method, path and status, never the body or the query string.