# 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://host` or `https://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 is `NAME_API_KEY` and `NAME_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`, or `cpus` and `mem_mb`), an `image` or a `disk_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_s` is 0, and sleep, checkpoint, rewind and fork answer `409 {"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: true` and 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 in `still_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 `methods` and `paths`.

- 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.

---
Source: https://docs.kosa8.com/guides/cloud-secrets/
