Use secrets

Secret values are one of the boundaries you should handle yourself. Give your coding agent the secret name and environment-variable binding, never the value. Do not paste a secret value into a coding-agent conversation, prompt, manifest, input JSON, repository, or packaged source file.

Understand the binding

An account secret has a logical name such as simulator. A binding such as SIM_TOKEN=simulator exposes its value to the Recurse agent's tools through the SIM_TOKEN environment variable. This lets the coding agent configure the tool without receiving the credential.

Runtime secrets are separate from the device credential created by recurse login. The device credential authenticates the CLI and MCP bridge. Runtime secrets authenticate external services called by your tools.

Store the value yourself

From an authenticated terminal, run:

recurse secret set simulator

The CLI prompts twice for a hidden value. Secret names contain 1–63 characters, begin with a lowercase letter, and continue with lowercase letters, digits, or hyphens. Values must contain non-empty UTF-8 text no larger than 32 KiB.

For non-interactive use, pass the value from a trusted source through standard input. For example, if SIM_TOKEN is already set in your shell:

printf %s "$SIM_TOKEN" | recurse secret set simulator --from-stdin

There is no --value flag. Do not place the value in shell history, logs, or process arguments.

Inspect stored metadata without revealing values:

recurse secret list

The CLI and API do not provide an operation to read a stored value back.

Give the coding agent the binding, not the value

Tell your coding agent that the tool expects the environment variable SIM_TOKEN and should bind it to the logical secret simulator.

For a direct run, the resulting command is:

recurse run ./my-agent --inputs inputs.json --secret SIM_TOKEN=simulator

For a deployment:

recurse deploy ./my-agent --as mcp --secret SIM_TOKEN=simulator

Inside a tool, the coding agent reads the value from the environment:

import os

token = os.environ["SIM_TOKEN"]

Ask the coding agent to verify that the tool does not print the value, return it, write it to an artifact, or include it in an exception. Recurse supplies bound secrets to tool execution, not to model calls or package preparation.

Native run traces expose original tool arguments, results, and errors without redaction. A secret emitted into those values can also reach the model. For a published app, the caller owns the run and can read its trace, including any publisher-owned credential the tool emits. Secret storage does not prevent application code from disclosing the value.

Rotate a credential

Set the same logical name again and enter the replacement value:

recurse secret set simulator

Future direct runs and deployment calls bound to that logical name use the new active version. An active run retains the version selected when it started. Rotation under the same name does not require repackaging the Recurse agent.

Recurse does not create or revoke the credential at its external provider. Coordinate both sides of the rotation, especially while runs using the previous value may still be active.

Delete a secret deliberately

Check its binding count before deletion:

recurse secret list
recurse secret delete simulator

Deletion destroys the stored value, disables affected MCP deployments, and prevents future runs from using it. An active run that has not yet obtained the required value can end with secret_unavailable.

Because deletion is destructive, do not ask a coding agent to perform it without reviewing the exact target and consequences. Recreating the same name is not proof that a disabled deployment has recovered; create and verify a deployment with the intended binding.