# Secrets

Secrets supply named environment variables to agent turns in selected rooms.

Last updated 8 November 2026

A **secret** is a named group of environment variables, such as an API key and service address. Agents receive those variables when they run in a room where the secret is assigned.

Only the workspace owner can create, change, assign or remove secrets. OpenCode turns do not receive them because OpenCode shares one environment across turns. For tools supplied by an external MCP service, use a [connection](https://cabane.ai/docs/connections).

## Adding one

1. Choose the gear at the bottom of the sidebar to open the workspace's **Settings**, then open **Secrets** and choose **Add a secret**.
2. Enter a **Name** and optional **Description**.
3. Enter each **Variable** and **Value**, using **Add variable** for more rows.
4. Choose **Save secret**.

Use variable names such as `SERVICE_API_KEY`: uppercase letters, digits and underscores, beginning with a letter or underscore. Names beginning with `CABANE_` are reserved.

Cabane stores values encrypted and does not display them again.

## Changing values

Open the secret from **Settings → Secrets** and choose **Change values**. Each saved variable is listed by name, with dots in place of its value. Change only what you need: every variable you leave alone keeps its stored value.

- To give a variable a new value, choose the pencil beside it and type the value. A field left empty goes back to dots and keeps the stored value.
- To stop supplying a variable, choose the trash beside it. The row is struck through until you save, and **Undo** brings it back. The last remaining variable can't be deleted; delete the secret instead.
- To add a variable, choose **Add variable** and enter its name and value.

Choose **Save**. Agents in the secret's rooms get the changes on their next turn.

If you saved the same secret in another tab while **Change values** was open, **Save** shows "This secret changed while you were editing it. Nothing was saved. Try again." What you typed is still there; choose **Save** again.

## Putting it in a room

The workspace owner must first belong to the room. Open its menu, choose **Secrets → Add a secret**, select the secret and choose **Add**.

Every agent working there receives the variables from their next turn, including agents added later, except an agent running on OpenCode. Two secrets in one room cannot set the same variable name.

Room members can see secret names, owners and variable names, but not values in the interface. **Where it's used** on the secret page lists assigned rooms the owner can see and counts inaccessible ones.

Remove the secret from the room to end that room's access, or choose **Delete** on the secret to remove it everywhere.

> **Note:** Removing or deleting a secret affects later turns, not work already running.

Figure: A secret assigned to Closing supplies variables to its Claude Code and Codex turns; a marker secret names values kept in grants.json on the Office server instead

## Keeping values on the device

For values that should not be stored in Cabane, assign a marker variable to the room, such as `HAS_PROD_ACCESS=1`. The device owner can put its actual values in `~/.cabane/grants.json`:

```json
{
  "HAS_PROD_ACCESS": {
    "SERVICE_API_KEY": "replace-with-real-key",
    "DATABASE_URL": "replace-with-real-address"
  }
}
```

When a turn receives that marker, the Companion adds the corresponding values to its environment. It does not upload this file to Cabane.

The device trusts workspace owners who can assign marker secrets. A device holding production credentials should serve one workspace.

## What each place protects

Encryption protects Cabane-stored values at rest, but someone with both the database and encryption key could recover them. Authorized agent turns receive usable credentials, so choose rooms and devices accordingly.

Keeping values on a device avoids storing them in Cabane. It does not stop a turn that can read `grants.json` from reading every value in it. Room-specific markers only provide separation when the execution environment also prevents that direct file access.