Secrets

Declare secrets by name and host. The VM only ever sees a placeholder.

A workspace declares the secrets it wants exposed to its VMs. The values are entered separately in the UI, under Settings → Workspaces → select a workspace, and stored in the host OS credential store (Keychain or libsecret). Values never touch config.toml, the database, the logs, or any API response.

Declaring a secret

[[secrets]]
env   = "GH_TOKEN"
hosts = ["github.com", "*.github.com", "*.githubusercontent.com"]

[[secrets]]
env   = "OPENAI_API_KEY"
hosts = ["api.openai.com"]

• env: the environment variable name set inside the VM. Must be a valid POSIX env var name, unique within the workspace.
• hosts: one or more hosts the secret may be sent to. Exact match (github.com) or a *-wildcard pattern (*.example.com).

How it works

The guest only ever sees a placeholder in the env var. The real value never enters the VM.

When the VM makes an outgoing TLS request, microsandbox’s egress proxy substitutes the real value into it, but only for the listed hosts (by default into the request headers or basic-auth). A request that carries the placeholder to any other host is blocked.

So the agent can run git push or call an API that needs the token, while the token itself stays on the host. A rogue agent that reads the env var gets a worthless string, and one that tries to send the placeholder somewhere off the allowlist gets nothing.

Unset secrets are skipped

A declared secret with no value entered is simply not registered with the VM. No env var is set, and nothing breaks. The Settings UI shows each declared secret as Set, or as Not set (in which case it won’t be injected).

GitHub gets wired up for you

Declaring a GH_TOKEN secret also configures git’s github.com credential helper to use gh inside the VM. So git and gh authenticate through the same domain-scoped secret, with no extra setup.