Workspace secrets

An agent with a sandbox has a shell and network access, so it can already run any command line tool. A workspace secret is how you give it something to authenticate with, without putting the credential in a prompt or a file in your repository.

What this protects, and what it does not​

A stored value is encrypted at rest and no route returns it. There is no read-back endpoint, so nothing has to guard one.

The value does not appear in a response, an event, a log line, a stored record, or anything sent to the model provider. Pantheon never puts it anywhere the model reads.

Store a credential​

Names are unique within your workspace. Two workspaces may each hold a ZOHO_OAUTH_TOKEN and they are different entries that never meet.

curl -sS -X POST "$PANTHEON_BASE_URL/v1/secrets" \
  -H "Authorization: Bearer $PANTHEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ZOHO_OAUTH_TOKEN",
    "value": "1000.the-access-token",
    "description": "Zoho Mail, read only, expires in one hour"
  }'

{
  "id": "0f2c1a5e-9f1d-4a0a-9b1c-2f3e4d5a6b7c",
  "name": "ZOHO_OAUTH_TOKEN",
  "description": "Zoho Mail, read only, expires in one hour",
  "fingerprint": "3b9f1c77ad0e42a1",
  "created_by": "key:8f1d2c3b",
  "updated_by": "key:8f1d2c3b",
  "created_at": "2026-09-12T09:14:02Z",
  "updated_at": "2026-09-12T09:14:02Z"
}

Rotating with PUT keeps the id and the name, so a session that already names this secret picks up the new value the next time its sandbox is provisioned.

Deliver it to a sandbox​

A session names which secrets its sandbox receives. They arrive in that sandbox and in no other, and a name your workspace does not hold is refused when the session is created rather than discovered missing at run time.

curl -sS -X POST "$PANTHEON_BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $PANTHEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "mail-reader",
    "secrets": [{"name": "ZOHO_OAUTH_TOKEN"}]
  }'

import { PantheonClient } from "@alethi/pantheon-chat";


const pantheon = new PantheonClient({
  baseUrl: process.env.PANTHEON_BASE_URL!,
  apiKey: process.env.PANTHEON_API_KEY!,
});


await pantheon.createSecret({
  name: "ZOHO_OAUTH_TOKEN",
  value: process.env.ZOHO_OAUTH_TOKEN!,
  description: "Zoho Mail, read only, expires in one hour",
});


const session = await pantheon.createSession({
  agentSlug: "mail-reader",
  secrets: [{ name: "ZOHO_OAUTH_TOKEN" }],
});

from pantheon_chat import SyncPantheonClient, SecretBinding


pantheon = SyncPantheonClient(base_url, api_key)


pantheon.create_secret(
    name="ZOHO_OAUTH_TOKEN",
    value=zoho_oauth_token,
    description="Zoho Mail, read only, expires in one hour",
)


session = pantheon.create_session(
    agent_slug="mail-reader",
    secrets=[SecretBinding(name="ZOHO_OAUTH_TOKEN")],
)

By default the secret becomes an environment variable of the same name. The agent's shell sees $ZOHO_OAUTH_TOKEN and nothing else changes.

Tools that read a file instead​

Plenty of command line tools do not read a credential from the environment. They read a file, often under a directory named by an environment variable. Both are supported, and a binding can do either or both.

curl -sS -X POST "$PANTHEON_BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $PANTHEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "mail-reader",
    "secrets": [{
      "name": "ZOHO_OAUTH_TOKEN",
      "env_var": null,
      "file_path": "/home/daytona/.config/zog/token.json"
    }],
    "env": {"ZOG_CONFIG_DIR": "/home/daytona/.config/zog"}
  }'

const session = await pantheon.createSession({
  agentSlug: "mail-reader",
  secrets: [{
    name: "ZOHO_OAUTH_TOKEN",
    envVar: null,
    filePath: "/home/daytona/.config/zog/token.json",
  }],
  env: { ZOG_CONFIG_DIR: "/home/daytona/.config/zog" },
});

from pantheon_chat import file_secret


session = pantheon.create_session(
    agent_slug="mail-reader",
    secrets=[file_secret("ZOHO_OAUTH_TOKEN", "/home/daytona/.config/zog/token.json")],
    env={"ZOG_CONFIG_DIR": "/home/daytona/.config/zog"},
)

Two rules keep this unambiguous. Two secrets may not set the same variable or write the same file, and a plain env entry may not shadow a secret. Either is refused with HTTP 422 rather than resolved by list order.

The file is written with mode 600 before the first run, so only the sandbox user can read it. The path must be absolute and may not contain ...

What is recorded​

Every mutation writes an audit row in the same transaction as the change, readable at /v1/audit/records: secret.created, secret.updated, secret.deleted, and secret.attached when a session names one.

Each row carries the name and the fingerprint. None of them carries the value. The sandbox record shows which secrets a sandbox received, by name, for the same reason.

Scopes​

secrets:read lists and reads metadata. secrets:write creates, rotates and deletes. Neither can read a stored value, because no route returns one.

A write scope does not imply the matching read, as everywhere else in this API. Naming secrets on a session needs sessions:write and secrets:read together.

Pitfalls​