Org Secrets

Org Secrets are encrypted key=value pairs owned by an org. A machine sees each one as an environment variable whose value is an opaque placeholder (ibsec_...). Your app sends that placeholder in its usual header, to its usual HTTPS URL, and the outbound proxy swaps in the real value for the hosts the Secret allows. The real key never lands on the machine’s disk or in its snapshots.

Save a Secret and give it to a machine

Save a Secret

To save a Secret, you need to be an org owner or admin.

instabox secrets set SERVICE_API_KEY --org team --host api.example.com

The CLI reads the value from stdin, or from a prompt without echo.

Give it to a machine

instabox create --name app --org team --secrets all
instabox secrets show app

Use it as usual

The app reads SERVICE_API_KEY and sends it as it always would, such as Authorization: Bearer $SERVICE_API_KEY or X-Api-Key: $SERVICE_API_KEY. There is no separate retrieval API.

New machines made in the dashboard receive all current and future proxy Secrets of their workspace, once Secrets is enabled for your account and on the server. Existing machines keep their selections. To change those, use the CLI or the HTTP API, below. A machine uses Secrets from its own org only.

Scope a model provider key to its API

--ai scopes a model provider key to its API. The proxy puts the key into x-api-key or Authorization only for that host.

instabox secrets set ANTHROPIC_API_KEY --ai anthropic
instabox secrets select app --secrets ANTHROPIC_API_KEY

`--ai`	Host
`anthropic`	`api.anthropic.com`
`openai`	`api.openai.com`
`gemini`	`generativelanguage.googleapis.com`
`openrouter`	`openrouter.ai`

You can repeat --ai and combine it with --host.

Choose the hosts a Secret may go to

Each Secret lists the exact hosts it may be sent to. Without --host, it may go to every public HTTPS destination (*). Partial wildcards such as *.example.com are not supported.

With *, any process in the machine can send the Secret to any public HTTPS host, including one it controls. When the credential must stay with one service, use exact hosts.

Change a running machine’s Secrets

instabox secrets select app --secrets SERVICE_API_KEY   # replaces the previous selection
instabox secrets push app
instabox secrets show app

--secrets all includes Secrets created later. --secrets none blocks the machine from all Secrets.
Rotating a value keeps its placeholder, so apps need no restart.
If you remove a Secret and recreate it with the same name, an explicit grant to the old one is not restored.

Use a Secret for git over HTTPS

Git sends its token as Basic auth, which the proxy handles, so git clone and git push to private repos work with a placeholder. Add github.com (for git) to the Secret’s hosts next to api.github.com (for gh). Then give git a credential helper that returns the placeholder, such as gh auth setup-git for GH_TOKEN.

Import a .env file

instabox secrets import .env --org team --host api.example.com

The whole file is validated and written at once, and every entry shares that host scope. Importing does not give any machine the Secrets. Select them with instabox secrets select, as above.

Turn off QUIC in browsers

The proxy sees HTTPS over TCP port 443 only. HTTP/3 (QUIC, on UDP 443) bypasses it, so the API receives the placeholder and usually refuses it, for example with 401. curl and most HTTP libraries use TCP, but Chromium may still pick HTTP/3. In a Chromium-based browser that sends Secrets, turn QUIC off:

chromium --disable-quic

In Playwright or Puppeteer, pass the same flag: chromium.launch({ args: ['--disable-quic'] }) or puppeteer.launch({ args: ['--disable-quic'] }). The browser must also trust the sandbox CA with normal certificate checks. Do not turn verification off.

Put the real value in the machine with a direct Secret

A direct Secret (--direct in the CLI, delivery: "env" in the API) puts the real value in the machine, as a variable or a file. Use one when the proxy cannot carry the credential.

Any code in the machine, including an agent or a package it installs, can read and copy a direct Secret. Prefer the proxy for HTTPS API keys. To revoke a direct credential, rotate it at its service, because copies already read stay.

Use	Delivery
API keys and tokens in HTTPS headers, git over HTTPS	proxy (default)
Login files (`~/.local/share/opencode/auth.json`, `~/.config/gh/hosts.yml`), SSH keys	direct, as a file
Database, Redis, or SMTP URLs. Request signing (AWS SigV4, service-account JWTs, HMAC). Keys in bodies or query strings. Pinned clients.	direct, as a variable or a file

As an owner or admin, save the Secret as direct. Then reference it from a machine as a variable, a home file, or both:

--secret-env VAR=SECRET, or --secret-env SECRET for the same name
--secret-file PATH=SECRET

instabox secrets set OPENCODE_AUTH --direct < ~/.local/share/opencode/auth.json
instabox secrets set PROD_PG --direct
instabox create --name agent --secret-file .local/share/opencode/auth.json=OPENCODE_AUTH --secret-env DATABASE_URL=PROD_PG
instabox secrets select agent --secret-env none          # remove every direct reference
instabox exec agent --secret-env DATABASE_URL=PROD_PG -- psql -c 'select 1'   # this command only

Who may reference direct Secrets, and the rules for names and paths, are under Reference below.

Select Secrets over the HTTP API

Select Secrets when you create a machine with POST /v1/machines:

{
  "name": "app",
  "templateId": "agent-browser",
  "orgId": "org_...",
  "secrets": ["SERVICE_API_KEY"],
  "directSecrets": [
    { "secret": "PROD_PG", "env": "DATABASE_URL" },
    { "secret": "OPENCODE_AUTH", "file": ".local/share/opencode/auth.json" }
  ]
}

After that, use /v1/machines/{id}/secrets:

PATCH sets a new selection. Explicit null selections are rejected.
GET returns metadata and status.
POST refreshes delivery now.

directSecrets replaces the machine’s direct references. "envSecrets": ["DATABASE_URL"] is the same-name shorthand. Send one or the other, not both. "secrets": "all" never includes env (direct) Secrets, which reach a machine only through envSecrets or directSecrets. For one command, POST /v1/machines/{id}/exec takes "secretEnvs": {"DATABASE_URL": "PROD_PG"}. To save a Secret over HTTP, see “Save a Secret” under Reference. Full schemas are in the API reference.

How it works

The proxy carries proxy Secrets, and files and variables carry direct ones. The details below say what the proxy changes in a request, when a change reaches a machine, and which processes see the values.

What the proxy replaces, and what it does not

The proxy checks the machine’s authorization, the host scope, and the upstream TLS certificate. Then it replaces the placeholder inside a header value. It supports HTTPS on port 443 only, and it does not substitute URL parameters or request bodies.

For HTTP Basic auth in Authorization, the proxy decodes the credential, replaces the placeholder inside user:password, and re-encodes it. Any other encoding or signing of the placeholder prevents replacement.
The proxy intercepts all supported HTTPS hosts, even without a placeholder. Clients must trust the sandbox CA and cannot pin certificates.
The proxy closes intercepted connections to private addresses.
WebSockets work. The proxy replaces placeholders in the handshake headers, not in messages.
The proxy drops Alt-Svc from the responses it relays. Chromium may still choose HTTP/3 from DNS, or from an earlier visit saved in its profile.

Delivery status and timing

instabox secrets show reports proxy authorization and placeholder setup separately. A proxy update is pending until acknowledged, and an acknowledged lease expires within at most 60 seconds without renewal. Requests already admitted, streams included, may finish.Servers with per-sandbox usage show each Secret’s proxied and denied request counts in secrets show and GET /v1/machines/{id}/secrets.

Which processes see the variables

Secrets are written to /run/instabox/secrets/env (tmpfs, mode 0600, owned by the machine’s user) and loaded by /etc/profile.d/zz-instabox-secrets.sh. Login shells get them: SSH, instabox exec, and the exec API.Processes that skip the profile do not get them, such as systemd units, cron, and bash -c without -l. Running processes keep their old environment until restarted.

Where a direct value lives

Variables go to /run/instabox/secrets/env. A file’s value is written to /run/instabox/secrets/files/ (tmpfs, mode 0600, owned by the machine’s user), and the home path becomes a symlink to it. So the disk, disk snapshots, and forks never hold the value.If the path already holds a file of the machine’s, the file is left alone and secrets show reports the error. Move the file and run secrets push. A tool that rewrites its login file replaces the link with a real file on the disk, which is then the machine’s own.

Rotation, removal and forks

A new value reaches running machines within about 10 seconds. Files change in place and new shells get the new variable, but running processes keep the old one until restarted. Stopped and paused machines get the current value when they start or resume. Deleting the Secret or the reference removes the variable and the file at the next delivery.Forks copy the source’s Secret selection, both proxy and direct, and resolve the values again. A machine created from a snapshot takes only its own selection.

Reference

Save a Secret: PUT /v1/orgs/{id}/secrets/{name}

Field	Required	Meaning
`value`	yes	The credential, up to 64 KiB of UTF-8. Proxy values must fit in an HTTP header.
`delivery`	yes	`"proxy"` or `"env"`, on every write, including a rotation. Without it: `400 delivery is required`.
`hosts`	proxy only	Up to 32 exact hostnames, with no scheme, port, path, or wildcard. `""` allows every public HTTPS destination. Omitted or `[]` means `[""]`. An env Secret with non-empty `hosts` is rejected.

A new Secret answers 201 Created, and a replacement 200 OK. Both carry metadata and never the value: id, orgId, name, delivery, hosts, version, size, createdAt, and updatedAt.POST /v1/orgs/{id}/secrets/import takes {"values":{...},"delivery":...,"hosts":[...]}, with the same rules for every entry. A missing delivery there answers 400 delivery must be proxy or env. The CLI saves proxy unless you pass --direct.This example saves a proxy Secret in your personal org. It keeps the token header in a mode 0600 file and sends the body on stdin, so neither appears in the process list:

instabox whoami >/dev/null
AUTH=$(mktemp)
jq -r '"Authorization: Bearer " + .accessToken' "${XDG_CONFIG_HOME:-$HOME/.config}/instabox/credentials.json" >"$AUTH"
ORG=$(curl -sS "https://api.instabox.sh/v1/orgs" -H @"$AUTH" | jq -r '.orgs[] | select(.personal) | .id')
curl -sS -X PUT "https://api.instabox.sh/v1/orgs/$ORG/secrets/SERVICE_API_KEY" -H @"$AUTH" -H 'Content-Type: application/json' --data-binary @- <<'EOF'
{"value":"example-api-key","delivery":"proxy","hosts":["api.example.com"]}
EOF
rm -f "$AUTH"

A heredoc you type still lands in shell history. For a real credential, build the body from a file with jq -Rs '{value: rtrimstr("\n"), delivery: "proxy", hosts: ["api.example.com"]}' <key.txt, and pipe it into the same curl. For an env Secret, send {"value":"postgresql://...","delivery":"env"} to .../secrets/DATABASE_URL.

Who can do what

Manage values (create, import, change, delete): an org owner or admin, signed in, or the workspace’s own workspace:admin API key sent as X-API-Key. After instabox login, the CLI’s access token works, and instabox whoami refreshes it. A personal org’s key and narrower keys get 403 missing_scope. Management reads never return values.
Read Secret metadata and machine selections: keys with machines:read.
Change selections and refresh delivery: keys with machines:write.

To work headless, put the workspace:admin key in INSTABOX_API_KEY. Org commands then default to the key’s org, and secrets rm needs --yes without a terminal.

Who can reference direct Secrets

Only an org owner or admin can save a Secret as direct. Anyone who can change a machine (machines:write) in the org can reference the org’s direct Secrets. A proxy Secret can never be referenced as direct, and a Secret of another org cannot be referenced at all.

Reserved names

The name is the variable the machine exports, so it follows the rule for Environment variables. A name that env refuses is refused here too (400 bad_request), including BASH_ENV, ENV, and IFS.A Secret saved under a name before the name was reserved is not delivered. The rest of the selection is delivered, secrets show reports not delivered: <names>, and secrets push answers 400. To fix it, save the value under another name, select it, delete the old Secret, and run secrets push.

Direct Secrets: names, paths and limits

Variable names follow the Secret name rule. They cannot be PATH, HOME, BASH_ENV, IFS, or the CA variables, and they cannot start with INSTABOX_ or SSH_.Paths are relative to the machine’s home directory: write .ssh/id_ed25519, not ~/.ssh/id_ed25519. The shell turns an unquoted ~/ into your own home, and the CLI takes that back as home-relative. A machine has at most 64 direct references.No API returns a value. secrets show and GET /v1/machines/{id}/secrets list directSecrets as names and paths. Each reference (create, select, fork, exec) is audited by name.

Vault, and opting out

Vault (per-user) and Org Secrets are independent stores, with no automatic migration. Existing Vault env values, file delivery, and metadata selectors keep working, and a machine can use both. For a same-named variable, an explicitly selected Secret wins.

Omitting secrets on create keeps the Vault behavior without enrolling the machine in Secrets.
--no-vault --secrets none disables delivery from both stores on a new machine.
--no-vault, and the SDK option vault: false, affect only Vault. Clearing Secret selections affects only Secrets. Where an SDK does not expose Secret selection fields, use the CLI or HTTP API.
instabox vault export NAME --out recovered.json remains for items kept by an earlier explicit migration. Its output contains the real value.

Environment variables

Plain variables, and the names a machine refuses.

API keys

Scopes, including workspace:admin.

Get started

Use cases

Machines

Access

Security

Account

Reference

Save a Secret and give it to a machine

Scope a model provider key to its API

Choose the hosts a Secret may go to

Change a running machine’s Secrets

Use a Secret for git over HTTPS

Import a .env file

Turn off QUIC in browsers

Put the real value in the machine with a direct Secret

Select Secrets over the HTTP API

How it works

Reference

Environment variables

API keys

​Save a Secret and give it to a machine

​Scope a model provider key to its API

​Choose the hosts a Secret may go to

​Change a running machine’s Secrets

​Use a Secret for git over HTTPS

​Import a .env file

​Turn off QUIC in browsers

​Put the real value in the machine with a direct Secret

​Select Secrets over the HTTP API

​How it works

​Reference

Environment variables

API keys

Save a Secret and give it to a machine

Scope a model provider key to its API

Choose the hosts a Secret may go to

Change a running machine’s Secrets

Use a Secret for git over HTTPS

Import a .env file

Turn off QUIC in browsers

Put the real value in the machine with a direct Secret

Select Secrets over the HTTP API

How it works

Reference