Service secrets in cloud sessions
Claude Code cloud sessions load service tokens (Sentry today) from AWS SSM through the AWS connector. The connector returns each value encrypted to a one-time key that the session's own container generated, so the plaintext never enters the conversation, the transcript, or the cloud environment's settings. Claude does the loading with the sandbox-secrets skill.
Naming
Each secret is a SecureString at /onramp/tools/sandbox/SERVICE/ENV_VAR, encrypted with alias/claude-code-sandbox-secrets. ENV_VAR is the exact variable name a session exports, so the Sentry token lives at /onramp/tools/sandbox/sentry/SENTRY_AUTH_TOKEN. Only parameters listed in infra/ci-identity/sandbox-secrets.ts are loaded; anything else under the path is ignored.
The tools stack creates the parameters from values committed as Pulumi config in infra/app/Pulumi.tools.yaml, and deploys on every merge to main. The key and its policy, which decides who can decrypt, live in the identity stack, where no deploy role can edit them.
Add a secret
- Add a row to
SANDBOX_SECRETSininfra/ci-identity/sandbox-secrets.ts. The tools stack reads its value from config keysandboxplus the variable name in PascalCase:SENTRY_AUTH_TOKENisapp:sandboxSentryAuthToken. - Open the PR. Its Committed Secrets check fails until the value is committed.
- An administrator checks out the PR's branch and runs
bun secret. It preselects thetoolsenvironment and the missing key, and takes the value at a hidden prompt or from the clipboard, never through Claude. Push the commit it makes; the merge's tools deploy writes the parameter.
Rotate
Commit the new value the same way and merge. SSM keeps every version and a load always reads the latest, so the next load after the tools deploy picks it up. A session that already loaded keeps the old value until it loads again. Nothing revokes a value a session already holds. A value written to SSM by hand is overwritten with the committed one on the next tools deploy.
How a session loads
A startup hook, active in cloud sessions only, makes every shell command source ~/.claude-sandbox-secrets/env once that file exists. Once secrets are loaded, it also puts a never-print reminder back into Claude's context after a compaction, which can drop the skill's own instructions while the values stay in the environment. The first time a task needs a secret, Claude runs the skill:
- The container generates a one-time RSA key pair and prints a connector script with the public key built in.
- Claude sends the script to the AWS connector (one approval). The connector reads the registered parameters and seals each value to that key.
- The container decrypts the result, writes the env file, deletes the private key, and reports the variable names it loaded.
This works whether the connector is bound to the read-only agent role, which the key policy lets decrypt, or to an administrator role.
Audit
Every load appears in CloudTrail as an SSM GetParameters call and a KMS Decrypt, attributed to the Identity Center role and user the connector was bound with. The Decrypt record's encryption context names the parameter. The account trail already records read events, so there is nothing to enable. That trail is not managed in this repo; if it is removed, CloudTrail's 90-day event history still records these reads.
Trade-off
Anything running in the session can read a loaded secret: it is in the environment of every later command and in a private file in the home directory.
The seal protects the load, not the parameter. Every principal the key policy lets decrypt can also read a value directly, and that includes the read-only agent role, which is also the default local agent identity. A direct read, such as aws ssm get-parameter --with-decryption or a connector script that returns the value, puts the plaintext wherever its output goes, a transcript included. That is the same exposure the role already has to nearly every other SecureString in the account. The tools deploy role can decrypt them too, since it owns the parameters, but the key policy stops it from doing anything else with the key.
So register only tokens a cloud session should hold, scoped as narrowly as the service allows (for Sentry, a token with read-only scopes). Each value can be at most 318 bytes.