Secrets management

1. Create account secrets

Create scoped secrets on the control plane. Secrets are write-only — once created, their raw values cannot be read back through the API (only list and delete operations are supported).

Use the CLI or REST API to manage account secrets:

# Create a secret
boxkite secrets create github_token --value "ghp_..." --allowed-hosts "api.github.com"

# List all secrets on your account (each row includes its id)
boxkite secrets ls

# Delete a secret by id (from the ls output above)
boxkite secrets rm <secret-id>

allowed_hosts is a security guardrail. The secrets-broker proxy will reject any HTTP request targeting a host that does not match this list.

2. Map secrets to a sandbox session

To give a sandbox session access to specific secrets, specify them by name when creating the sandbox. A sandbox can only access secrets that were explicitly granted to it at startup.

sb = client.create_sandbox(
    label="deployment",
    secret_names=["github_token", "aws_credentials"]
)

The standalone boxkite-mcp package's create_sandbox tool doesn't take secret_names yet — use the Python or JS SDK to create a secret-scoped session today.

3. Server-side substitution (http_request tool)

When you enable the secrets-broker HTTP request tool (enable_http_request_tool=true), the agent gets anhttp_request tool. The agent can write request templates containing placeholders like{{secret:name}}. The sidecar substitutes the real credential values server-side just before forwarding the request:

# The agent invokes the tool with placeholders:
result = await http_request(
    method="POST",
    url="https://api.github.com/repos/owner/repo/releases",
    headers={"Authorization": "token {{secret:github_token}}"},
    body='{"tag_name": "v1.0.0"}'
)
# The sidecar sends the real ghp_... value, but the agent only sees the response.

4. Env injection (secret_env)

For programs that require credentials in their execution environment (e.g. running git push or aws s3 sync), enable environment injection (enable_secret_env=true). This allows the agent to request secret mapping inside thebash_tool:

# The agent runs a command with environment variables mapped to secret names:
result = await bash_tool(
    command="git push origin main",
    secret_env={"GITHUB_TOKEN": "github_token"}
)
# The sidecar injects GITHUB_TOKEN=ghp_... into the command execution environment.