kosa8 docs

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}

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

What the broker does and does not stop