Agent Sandbox Secrets

Agent sandbox secrets are encrypted credentials — API keys, tokens, or whole config files — that Temps injects into every AI agent and workspace sandbox at startup. Define a secret once in the console and reference it from agent workflow YAML, MCP server configs, or custom tools without ever pasting the plaintext into a repo, a prompt, or a pull request.

How it works

Secrets are stored globally (one set per Temps instance) and applied to all agent sandboxes. When a sandbox is provisioned, Temps decrypts each secret and injects it according to its type:

• env secrets are written to /home/temps/.temps/secrets.env as shell export statements inside the sandbox.
• file secrets are written as a file at the path you configure.
• Any ${TEMPS_SECRET:NAME} placeholders that appear in the generated MCP / agent config files are replaced inline with the decrypted value.

All injected secret material stays under /home/temps/ — Temps never writes secrets under /workspace/, because that directory is bind-mounted from the cloned repo and anything written there would leak into the agent's pull-request diff.

Secret types

Every secret has a secret_type of either env or file. The type determines how the value is delivered into the sandbox.

A file secret without a mount_path is rejected with a validation error. Paths that target /workspace/... are rewritten to a safe location under /home/temps/.temps/secrets/ so secret files never end up in the repo working tree.

Referencing secrets

Reference a secret anywhere a config value is read by writing the placeholder ${TEMPS_SECRET:NAME}, where NAME matches the secret's name. Temps substitutes the decrypted value when it materializes the sandbox config.

A common use is a custom tool header in agent workflow YAML:

name: Weather Agent
on:
  manual: true
tools:
  - type: custom
    name: get_weather
    description: Get current weather for a location
    webhook_url: https://api.example.com/weather
    headers:
      Authorization: "Bearer ${TEMPS_SECRET:WEATHER_KEY}"

The same placeholder works inside MCP server env blocks. If a referenced secret does not exist, the placeholder is left untouched (it is not replaced with an empty string), so a missing secret surfaces as an authentication failure inside the tool rather than a silent blank value.

Manage secrets in the console

Open the agent sandbox settings and go to the Secrets tab at /agent-sandbox/secrets. The table lists each secret's name, type, mount path (for file secrets), description, and last-updated date — never the value.

Add a secret. Click Add Secret, then:

1. Enter a Name. The field is normalized to uppercase with non-alphanumeric characters replaced by underscores (for example ANTHROPIC_API_KEY), since the name is the environment-variable key.
2. Choose a Type — Environment Variable or File.
3. Enter the Value (encrypted before storage).
4. For a File secret, provide a Mount Path such as /home/temps/.config/credentials.json.
5. Optionally add a Description.

Edit a secret. Click the pencil action on a row to reopen the dialog in edit mode. The name is locked (it is the backend key — delete and recreate to rename) and the metadata is pre-filled. The stored value is encrypted and never returned, so the value field starts empty: type a new value to rotate the secret, or leave the rest of the row unchanged.

Delete a secret. Click the trash action to open a confirmation dialog that names the secret and warns that anything referencing it via ${TEMPS_SECRET:NAME} will fail to resolve. Confirm to permanently delete it.

API reference

The console actions map directly to three endpoints. All paths are served under the /api prefix, and all require a bearer token. Listing requires the SettingsRead permission; creating, updating, and deleting require SettingsWrite.

List secrets

GET /api/settings/secrets

Returns every secret as metadata only. The value field is always masked as *** — the plaintext is never returned by the API.

{
  "items": [
    {
      "id": 1,
      "name": "ANTHROPIC_API_KEY",
      "secret_type": "env",
      "value": "***",
      "mount_path": null,
      "description": "Claude API key for agents",
      "created_at": "2026-05-29T10:00:00Z",
      "updated_at": "2026-05-29T10:00:00Z"
    }
  ],
  "total": 1
}

Create or update a secret

POST /api/settings/secrets

Upsert by name: if a secret with the same name already exists, it is updated; otherwise it is created. Responds with 201 Created.

Example request body for a file secret:

{
  "name": "GCP_SERVICE_ACCOUNT",
  "secret_type": "file",
  "value": "{ ... service account JSON ... }",
  "mount_path": "/home/temps/.config/gcp.json",
  "description": "Service account for deploy tool"
}

Delete a secret

DELETE /api/settings/secrets/{name}

Deletes the secret by name and responds with 204 No Content. Returns 404 Not Found if no secret with that name exists.

Security

• Encrypted at rest. Values are encrypted with AES-256-GCM before they are written to the database.
• Never returned in plaintext. Both the list endpoint and individual responses mask the value as ***. Rotating a secret requires entering a new value — the old one cannot be read back.
• Kept out of the repo. Injected secrets live under /home/temps/ only. File secrets that target /workspace/... are rewritten to a safe path, and project-level config files that would land in a PR diff are not written with resolved secrets.
• Audit logged. Creating, updating, and deleting a secret are recorded as SECRET_UPSERTED and SECRET_DELETED audit events with the acting user, IP address, and secret name.