# Secrets

Let commands on a box use your API keys without your AI ever seeing them.

> For agents: if a task needs an API key, don't ask the person to paste it into the chat. Use the environment variable they added at https://box.simular.ai/secrets, such as `$OPENAI_API_KEY`, in the box's `shell`. It holds a stand-in, and box swaps in the real key only on requests to the sites the person listed. Raw Markdown: https://box.simular.ai/docs/secrets.md

A secret is an API key that commands on your box can use while your AI never sees it. You paste the key once, and box stores it encrypted. Nobody can read it back: not the page, not your AI.

## Add a secret

On [https://box.simular.ai/secrets](https://box.simular.ai/secrets), pick a service, or **Other** for any site (once you have secrets, **Add secret** opens the same choice), and fill in:

- **The key**, pasted once.
- **Name in your boxes:** the environment variable programs read, like `OPENAI_API_KEY`.
- **Sites it goes to:** up to 8 hosts, such as `api.openai.com`, or `*.example.com` for every site under a domain.
- **How the site expects it:** in a header (for example `Authorization: Bearer <key>`) or in the URL.

## How it works

1. On the box, the variable holds a stand-in that looks like a key but isn't one (it contains `cbv_`).
2. When a command sends the stand-in to one of the key's sites, box puts the real key in its place on the way out.
3. Sent to any other site, the stand-in stays a stand-in, and is useless there.
4. Replace the key and the stand-in stays the same, so nothing on the box changes. Delete it and the swap stops, and the variable goes away.

## Using a secret (for agents)

- Reference the variable in the command, the way the site expects the key:

  ```bash
  curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
  ```

  Programs that read the variable themselves (for example a Python or Node script using `os.environ` or `process.env`) work as they are.
- `echo $OPENAI_API_KEY` shows only the stand-in. That is expected; never ask the person for the real key.
- If the variable is empty:
  - On a box you created with `box_create`, secrets never arrive. Use one of the person's own boxes instead.
  - Otherwise, ask the person to add the key at https://box.simular.ai/secrets, then run the command again.
- If the site rejects the key, check, in this order:
  1. The site's host is one of the key's sites; the person can check at https://box.simular.ai/secrets.
  2. The command sends the key the way the secret says, for example `Authorization: Bearer`.
  3. The box's system is current: `box_status` says whether an upgrade is available. Ask the person before you run `box_upgrade`, since running programs restart.

## Limits

- **Commands only:** commands run with the `shell` tool and in the box's terminal get your secrets. Scripts run with `script_run` don't; from a script, run the command through `bash -lc`, which does. A terminal that was already open when a key was added doesn't have it; open a new one. The `shell` tool picks it up on its next command.
- **Boxes on the latest system:** older boxes send the stand-in as it is. Update a box from its Settings at [https://box.simular.ai/box](https://box.simular.ai/box).
- **Not in boxes an agent created:** a box your AI created itself (with `box_create`) gets none of your secrets.
- **One format per key:** a site that takes the same key in two ways (for example `Bearer` and `token`) needs two secrets.