Skip to content

Secrets

Code in a sandbox, such as an agent's, should never hold your API keys: anything it can read, it can leak. A secret keeps the key outside the sandbox. The sandbox holds a placeholder, and Runtime puts the real value in the request as it leaves for the hosts you name, over HTTPS.

Updated .md

Store a secret#

PUT /v2/secrets/{name} takes a SecretSet:

Field
value Its value, never answered. Hidden: 1 to 8192 visible ASCII characters and spaces, one line, since it goes into an HTTP header. Visible: 1 byte to 64 KiB of UTF-8 text with no NUL, newlines included (a PEM file, an SSH key, a service account's JSON). With it, the set stores the secret whole, as its fields say. Without it, the set changes only the hosts, policies.rules and scope it names, and keeps the rest: hosts and rules only narrow, since widening needs the value, and so does a visible secret's scope, whose machines hold its value; any other field is refused 400.
hosts The hosts its value goes to on HTTPS: a name, or *. and a name for every name under it. Required unless visible; refused when visible.
header The header it is set in on every request to its hosts; when omitted, its placeholder is replaced in the credential headers (Authorization, x-api-key and the like). Hidden secrets only.
format The header's value, {value} replaced by the secret; {value} when omitted. Hidden secrets only.
envName The environment variable that holds its placeholder (or, when visible, its value) in each machine it reaches; its name when omitted. When two secrets that reach one machine name the same variable, it holds the one first by name.
scope The machines that may use it; every machine of the organization when omitted.

The answer, a Secret, never holds the value: placeholder is what a sandbox holds in its place.

Terminalcurl -X PUT https://api.withruntime.com/v2/secrets/OPENAI_API_KEY \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/json" \  -d '{"value": "sk-...", "hosts": ["api.openai.com"], "scope": {"labelsAny": [{"team": "agents"}]}}'

Which sandboxes get it#

  • Scope every secret. When scope is left out, The machines that may use it; every machine of the organization when omitted. Scope a secret to the labels of the sandboxes that need it: Machines with every label of any one of these sets.
  • A sandbox can narrow what it gets further at create: secrets: The secrets it may get, by name, at most 64: only those of them whose scope admits it; [] none; every one whose scope admits it when omitted. A name with no secret yet takes effect once that secret is created. Fixed for its life: a fork or a copy of a snapshot keeps it.
  • PUT /v2/secrets/{name} without the value changes a stored secret's hosts, rules or scope and keeps the rest: hosts and rules only narrow, since widening needs the value.
  • DELETE /v2/secrets/{name} removes it. Sandboxes that held its placeholder can no longer use it.

Give this to your agent#

Paste this into your coding agent:

Read https://withruntime.com/docs/secrets.md. Store each API key this project's sandboxed code uses as a Runtime secret for the hosts it calls, scope each to the sandboxes that need it, and remove the keys from the sandboxes' environment and files.

This page as Markdown: https://withruntime.com/docs/secrets.md

Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial