Secrets

A secret is a credential you store in a workspace and let Spinup project into agent environments under a stable name. Secrets live above any one harness or runtime instance, so the same credential can flow into different harnesses on the same agent.

What you control

You create secrets in the workspace and bind them to the agents and capabilities that need them. A secret has a display name, a projection name the runtime sees (for example OPENROUTER_API_KEY), and a value you submit once.

You can manage workspace secrets from the dashboard, API, SDK, or CLI. The CLI accepts secret values from files or stdin so values do not need to appear in shell history:

spinup secrets create "OpenAI production" \
  --projection-name OPENAI_API_KEY \
  --value-file ./openai-key.txt

Use --value-stdin for automation that already has a secret in a secure pipe:

printf '%s' "$OPENAI_API_KEY" | spinup secrets create "OpenAI production" \
  --projection-name OPENAI_API_KEY \
  --value-stdin

Do not put raw secret values in command arguments, docs, support tickets, or screenshots.

Agent secret bindings

An agent secret binding links a workspace secret to one Spinup Agent under a projection name. The binding is durable agent state; the runtime sees only the projected value when Spinup prepares or reconciles the environment.

spinup agents secrets list --slug support-agent
spinup agents secrets set --slug support-agent \
  --secret orgsecret_01hxyz... \
  --projection-name OPENAI_API_KEY

The set command reads the current binding state and sends an optimistic state-version guard. If the dashboard or another client changed bindings first, refresh and retry instead of overwriting the other change.

What Spinup does

Spinup keeps the secret value in a workspace-scoped secrets store. When the environment needs it, Spinup projects the secret into the agent runtime under the stable projection name the capability declared.

API, SDK, CLI, and UI reads return masked metadata only. The display name, projection name, binding count, and a masked preview are visible. The full value is not returned through /v1, the SDK, CLI output, or the dashboard.

Deleting a workspace secret that is still bound to one or more agents fails with a conflict. Detach the agent secret bindings first; force-delete is not part of the public surface.

Where to go next

• See how secrets fit into the agent object in Spinup Agents.
• See how capabilities declare the secret bindings they need in Capabilities.