Secrets

A secret is a key, token or password that a tool needs, such as an API key. Whorl stores it encrypted. Tools read it by name, and nobody can see the value again after it is saved, including you.

Never paste a key into a Thread, an instruction or a file. Agents are told never to ask for a secret value in chat. If an agent needs one, it tells you the name to use, and you enter the value yourself.

Add a secret⁠

  1. Open the Agents card for the layer that should have it. See Agents and setup.
  2. On the Tools can read line, choose Add secret.
  3. In the dialog, which reads "Save value as name for hosts", fill in:
    • Secret value: the key. The field is hidden as you type.
    • Secret name: capital letters, numbers and underscores, such as API_KEY or LINEAR_API_KEY.
    • Hosts that may receive it: the websites the secret may be sent to, such as api.linear.app. Separate several with commas.
  4. Choose Save secret.

Whorl refuses a host that is not a plain HTTPS address, and a secret can name up to 16 hosts.

How tools use a secret⁠

A tool never sees the value. When it needs to call a service, it asks Whorl to make the request, and Whorl adds the secret to the request as a header. The secret goes only to a host you listed. Requests to any other address are refused.

By default the secret is sent as an Authorization header with the prefix Bearer.

An MCP server that needs a key keeps its own saved key. See Tools, MCP servers and connectors.

Which layer⁠

A secret belongs to a layer: the company, a Space, you or a Captain. The same name at a closer layer replaces the outer one. Tools in a Space read the Space's secrets. A Captain's tools read the Captain's. Choose the narrowest layer that reaches everyone who needs it. See Agents and setup.

Replace a secret⁠

To change a value, add the secret again with the same name at the same layer and enter the new value. The old value is replaced, and nobody sees either one.

View as Markdown