# Secrets

A Pane secret is a named value like `stripe/STRIPE_SECRET_KEY`. Claude Code, Codex, Cursor or a script runs a command with it in the environment. No Pane command or MCP tool returns the value, so it reaches chat only if that command prints it.

Without it, you paste the key into chat, where it sits in the transcript, or into a `.env` file in every worktree.

| You ask | The agent |
| --- | --- |
| "Run the webhook tests with my Stripe test key." | Runs the tests through `runpane secrets exec`. The key reaches the tests and stays out of chat. |
| "Ask me for the OpenAI key." | Calls `secrets_request`. You type the key on a masked card, and the agent only learns it was saved. |
| "Which secrets do I have?" | Runs `runpane secrets list`: project, name, and when and where each was set. Never a value. |
| "Delete the old Stripe key." | Deletes it here, and from your other computers as they sync. |

## Add a secret

A secret's address is `<project>/<NAME>`. The project is a group you pick, like `stripe` or a repo's name. The name follows environment variable rules, so it can be injected as is.

**In the app:**

1. Open **[Settings](/docs/settings) → Secrets** and click **Add secret**.
2. Type the project, the name and the value.
3. Click **Save securely**.

**When an agent asks.** An agent that needs a key calls the `secrets_request` [MCP](/docs/mcp) tool (or `runpane secrets request`). A [Notify](/docs/notify) card shows its title and reason with a masked field. Type the value and click **Save securely**, or click **Decline**. Secret cards have no Undo.

Answer it on the computer running the agent, on another Pane desktop connected to that computer, or in the [Pane app](/docs/phone), which uses a secure text field. A lock-screen alert only opens the app, since the phone's reply field isn't masked.

**From a script.** `runpane secrets set` reads the value from stdin, so it never lands in your shell history. `--yes` confirms the change without a prompt:

```bash
printf %s "$VALUE" | runpane secrets set --project stripe --name STRIPE_SECRET_KEY --yes
```

> **Note:** If Pane can't show the card, `secrets_request` returns `unavailable`. Save the secret yourself in **Settings → Secrets**, then tell the agent.

## Use a secret

`runpane secrets exec` starts a command with the secrets in its environment:

```bash
runpane secrets exec --project stripe -- npm test                          # every stripe/* secret, under its own name
runpane secrets exec --project stripe --only STRIPE_SECRET_KEY -- npm test   # just this one
runpane secrets exec --project stripe --env API_KEY=STRIPE_SECRET_KEY -- ./deploy.sh   # as API_KEY
runpane secrets exec --project gcp --file SERVICE_ACCOUNT -- ./upload.sh   # a path to a private temp file
```

Values are read when the command runs, so a secret saved a moment ago works in an agent that's already running. Injected names override the caller's environment. Injecting `PATH`, `WORKTREE_PATH` or `PANE_*` fails with `SECRET_RESERVED_NAME`, and nothing runs. A `--file` secret goes in a temp file only you can read, deleted when the command exits.

There's no `secrets get`.

**In every terminal of a project.** Add a [project environment variable](/docs/environment-variables#project-environment-variables) with the source **Pane secret**. The project stores only the address, and each new terminal and script reads the value when it starts. See also [AI providers](/docs/providers#keep-keys-in-pane-secrets) for the keys each agent reads.

## Where values are stored

| Computer | Store |
| --- | --- |
| macOS | Your login keychain, under the service `Pane` |
| Windows | `secrets.json` in the Pane data folder, each value encrypted with Windows (DPAPI) |
| Linux with a desktop keyring | The same file, each value encrypted with the keyring |
| Linux without a keyring, like a headless server | The same file, readable only by you, as **plain text** |

On a host without a keyring, **Settings → Secrets** says "Stored unencrypted on this host (no OS keyring)", and so does `runpane secrets list` there.

## Sync between your computers

Each of [your computers](/docs/your-computers) keeps its own copy, so secrets work offline. Two computers sync only through a Pane desktop or the phone app connected to both. It carries secrets between them when a secret changes and when a saved computer reconnects. The newest copy wins.

A secret is managed on the computer itself. `runpane workspace <machine> secrets …` fails with `SECRET_LOCAL_ONLY`, and nothing changes. Use `runpane workspace <machine> exec -- runpane secrets …` instead, through [Workspaces](/docs/runpane-workspaces).

> **Warning:** Secrets keep values out of chat and shell history. They aren't a sandbox: any agent or program running as you, on any of your computers, can use every secret. If any computer has **Settings → Remote Access → Tailscale → Who can connect** set to **Everyone on tailnet**, your teammates can too, since it holds a copy of every secret. Keep **Only me** ([who is trusted](/docs/runpane-workspaces#who-is-trusted)) unless you trust them with all your secrets.

## Delete a secret

Click **Delete** next to it in **Settings → Secrets**, or run:

```bash
runpane secrets delete --project stripe --name STRIPE_SECRET_KEY --yes
```

Each other computer deletes it the next time a desktop or the phone syncs with it. Removing a project variable that points at a secret leaves the secret in place.

## When it doesn't work

- **`SECRET_NOT_FOUND`.** The secret isn't on this computer. Ask for it with `secrets_request`, or open Pane on a desktop or the phone app connected to both this computer and one that has the secret, so they sync.
- **A `[Pane]` line in a new terminal.** A project variable couldn't read its secret. Save the secret in **Settings → Secrets**, then open a new terminal.
- **The macOS keychain is locked.** A delete fails and the secret stays listed. Unlock the keychain and delete again.
