ParallelSandbox
Open app

Secrets

A box needs credentials now and then: a token to clone a private repo, a write key for the log SDK, an API key for a service your tests call. Secrets are how you hand those to a box without putting them in a repo, a prompt or a tool call.

How they work

  • A secret is a name and a value stored in the control plane, per tenant. Names are environment variable names: PSBX_LOG_WRITE_KEY, GITHUB_TOKEN, STRIPE_TEST_KEY.
  • Nothing reaches a box by default. sandbox_start takes secrets, a list of names; only those are injected, as environment variables of every sandbox_exec command, at the moment the box is claimed.
  • A spare box waiting in the pool holds no tenant data. It receives the tenant's settings and secrets only when claimed, and everything on it is destroyed when it stops.
  • Values never appear in tool results, in sandbox_status, in usage events or in platform logs. sandbox_secrets returns names only.
  • Boxes hold no cloud credentials of their own and cannot reach other boxes.

Create and manage

With the REST API, using your tenant API key:

curl -fsS -X PUT https://api.parallelsandbox.com/v1/secrets/GITHUB_TOKEN \
  -H "Authorization: Bearer psbx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "ghp_..." }'

A PUT to an existing name replaces the value; boxes claimed afterwards get the new one. Delete with DELETE /v1/secrets/{name}; GET /v1/secrets lists the names.

The agent lists what exists:

sandbox_secrets {}

Use in a box

sandbox_start { "services": [{ "name": "web", "port": 8080 }], "secrets": ["GITHUB_TOKEN", "PSBX_LOG_WRITE_KEY"] }
sandbox_exec  { "id": "<id>", "cmd": "git clone https://x-access-token:$GITHUB_TOKEN@github.com/your-org/private-repo.git && cd private-repo && git remote set-url origin https://github.com/your-org/private-repo.git" }

docker compose passes environment variables through with ${GITHUB_TOKEN} in the compose file or an environment: entry without a value. Do not bake secrets into images with ARG; images can be published as versions and pulled by other boxes.

What to store

  • Short-lived tokens whenever the provider offers them: a GitHub App installation token, an STS session, a scoped deploy key. They expire on their own.
  • Public write keys such as the log SDK's pw_... can live in a page, but keeping them as secrets means the repo stays free of anything tenant-specific.
  • Never store your ParallelSandbox API key as a secret. The agent already has it; a box does not need it.