Guides

Give a run a secret

Store a secret once in Vault, then let a sandbox reference it. The value goes to the sandbox only: not to your code, the API's answer, the audit log or a model.

Vault comes with every plan. See Vault for how it works.

1. Store the secret

sandscale vault kv put --mount secret app/db password=-

password=- reads the value from standard input without echoing it. FIELD=@FILE reads it from a file.

2. Reference it when you start a sandbox

const box = await sandscale.sandboxes.create({
  template: 'builtin:python',
  vaultEnv: [{ name: 'DB_PASSWORD', path: 'secret/data/app/db', field: 'password' }],
});
from sandscale import VaultEnvRef

box = sandscale.sandboxes.create(
    template="builtin:python",
    vault_env=[VaultEnvRef("DB_PASSWORD", "secret/data/app/db", "password")],
)
curl -X POST "$API/instances" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"template_id": "builtin:python", "vault_env": [{"name": "DB_PASSWORD", "path": "secret/data/app/db", "field": "password"}]}'

The sandbox gets DB_PASSWORD in its environment. The path is the mount, data, then the secret’s path.

What happens to the value

  • Sandscale reads it as you, with your Vault permissions. If you may not read it, the start is refused with vault_env_refused and nothing starts.
  • It goes to the sandbox only. It is never in the API’s answer, a log, the run’s record or the audit log; the audit entry names the variables, not the values.
  • A start can name up to 50 values.
  • Build host leases can carry secrets too. They end with the lease.