Secrets

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, 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:

  cURLCopy code

  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.
• 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.