Guide 23 of 61 · Protecting secrets and data
Give agents short-lived AWS, GCP and SSH credentials
Seal AWS, GCP and SSH credentials in agentgarmd; each task started with agentgarm run gets short-lived ones, and the sealed ones never reach the agent.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Seal your AWS key, GCP bearer token and SSH CA in agentgarmd, name a role, a service account and SSH principals in policy, and every task you start with agentgarm run gets its own short-lived role session, access token and SSH certificate, revoked when the task ends (what the provider already issued stays valid until it expires); the sealed credentials never enter the agent's environment or files.
1. Seal the upstream credentials in agentgarmd
The credential broker is Phase 3 work: built, but not yet claimed. It issues credentials only to tasks started with agentgarm run, and it starts from upstream credentials you seal in agentgarmd's secret store with agentgarmd broker secret set, which reads the secret from stdin until end of input, never from an argument. On a root install run it with sudo; on a no-root install add --user.
For aws, give an access key as <access_key_id>:<secret_access_key> (with :<session_token> when it is temporary) or as JSON, which also takes region, endpoint and external_id. For gcp, give a bearer token the broker sends to IAM Credentials' generateAccessToken; the broker never refreshes it, so seal a new one before it expires. For ssh, give your CA's Ed25519 seed: 32 raw bytes or 64 hex digits. Each is sealed under the id default unless you pass --id (letters, digits, ., _, : and - only, at most 128 characters; a provider name is at most 64), and a policy rule picks another id with secret_id. The exceptions: for vault and secrets_manager a secret_id may instead be the secret's path in Vault or Secrets Manager, and the SSH CA is always read from default. agentgarmd broker secret list prints each provider and id, never a value.
sudo agentgarmd broker secret set aws # paste the key, then Ctrl-D
sudo agentgarmd broker secret set gcp
sudo agentgarmd broker secret set ssh
sudo agentgarmd broker secret listagentgarmd broker secret set aws --user
agentgarmd broker secret list --user2. Turn the broker on in policy
Under security_boundaries.credentials, set broker: true and list a rule per provider: an AWS rule names the role_arn the broker assumes, a GCP rule the service_account it mints tokens for and their scopes, and ssh the principals the certificate carries. Each rule's ttl_seconds sets how long what it issues lasts (3600 when unset). An AWS rule's delivery defaults to credential_process and a GCP rule's to metadata_shim; SSH is always served through an agent socket.
In brokered mode agentgarm run also strips your exported model provider keys, such as ANTHROPIC_API_KEY and OPENAI_API_KEY, from the agent's environment, on top of the cloud and SSH variables it always removes. strip_ambient: false keeps those provider keys (for a policy that brokers only cloud credentials while the agent uses your own model key); strip_ambient: true strips them without the broker. Restart agentgarmd so it loads the policy.
security_boundaries:
credentials:
broker: true
providers:
- provider: aws
role_arn: "arn:aws:iam::123456789012:role/agent-task"
ttl_seconds: 900
delivery: credential_process
- provider: gcp
service_account: "agent-task@example-project.iam.gserviceaccount.com"
scopes: ["https://www.googleapis.com/auth/cloud-platform.read-only"]
ttl_seconds: 3600
delivery: metadata_shim
ssh:
ca: sealed
principals: [deploy]
ttl_seconds: 1800sudo systemctl restart agentgarmd # root install, Linux
sudo launchctl kickstart -k system/com.agentgarm.agentgarmd # root install, macOS
systemctl --user restart agentgarmd # no-root install, Linux
launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # no-root install, macOSSee also
Limit what an agent can read, write and reachDecide which files an agent may read and write and which hosts it may reach, know which layer holds each rule, and recognise a denial.
3. Let AWS tools fetch a role session
For an AWS rule, agentgarm run writes a per-task AWS config file whose credential_process is agentgarm credential aws, and points AWS_CONFIG_FILE at it. When the AWS CLI or an SDK needs credentials, it runs that command, which asks agentgarmd for an STS AssumeRole session for the task and prints it as credential_process JSON. On macOS the sandbox stops the agent rewriting the file.
A session lasts 900 to 43,200 seconds, and at most 3600 when the sealed key is itself temporary, which the broker detects; an inline session_policy of up to 2048 characters narrows it further. Outside a governed task, after the task ends or once the credential is revoked, the command exits 2, with its reason on stderr and nothing on stdout. Model calls on the bedrock route are signed by the proxy with a session leased the same way.
agentgarm run -- claudeagentgarm credential awsSee also
Give Claude Code a per-developer gateway keyGive each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed.
4. Let Google Cloud tools read a task token
For a GCP rule, agentgarm run asks agentgarmd for an access token for the rule's service account before the agent starts, writes it to a 0600 file in the task's cache directory, and sets CLOUDSDK_AUTH_ACCESS_TOKEN_FILE to it, which gcloud reads. It also sets GCE_METADATA_HOST to the proxy's loopback port, where a stand-in for the GCE metadata server answers Google Cloud client libraries with the task's token, only for processes in a task whose policy brokers GCP and only with Metadata-Flavor: Google. No service account key file is written.
A token lasts up to 3600 seconds by default; longer, up to 43,200, works only where your organisation allows extended service account lifetimes. agentgarm credential gcp prints the task's token as JSON, --raw prints the token alone, and --write-token-file writes it to a 0600 file you name, with --refresh-within-secs rewriting it only near its expiry. Nothing refreshes the token file agentgarm run wrote: once its token expires, gcloud stops working until the task is started again, and on macOS that file is write-denied to the agent, so it cannot be rewritten from inside the task. Client libraries get a fresh token from the metadata stand-in.
agentgarm credential gcp5. Sign in over SSH with a task certificate
With ssh in the policy, agentgarmd makes a fresh Ed25519 key for the task, has your CA sign an OpenSSH user certificate for it with the policy's principals and lifetime (60 to 86,400 seconds), and serves both through a read-only ssh-agent socket that agentgarm run sets as SSH_AUTH_SOCK. The CA is the sealed seed (ca: sealed), or HashiCorp Vault's SSH secrets engine with ca: vault and a vault_role. Your own agent socket is removed from the environment.
The private key never leaves agentgarmd. The socket answers only identity and signing requests, only from processes of that task, and only while the certificate is valid and unrevoked; it refuses adding, removing and locking keys, and is removed when the task ends. agentgarm credential ssh prints the certificate's details, and --raw just the socket path.
agentgarm credential ssh6. Give each task its own model provider key
The broker can also give each task a model provider key of its own. For openai, seal an OpenAI admin key and name the project in the rule's service_account: the broker creates a project service account for the task and deletes it when the task ends. Anthropic's Admin API cannot create keys, so for anthropic seal a pool of keys you made in its Console, as <admin_api_key>:<api_key_id>:<api_key_value> (more <api_key_id>:<api_key_value> pairs after commas) or as JSON: the broker activates one key for the task, holds it until the task ends or for max_ttl_seconds at most (43,200 by default), and deactivates it. A vault or secrets_manager rule can serve keys from a pool the same way, one task per entry; an exhausted pool denies rather than share a key.
By default (delivery: proxy_inject) the agent's OPENAI_API_KEY or ANTHROPIC_API_KEY holds only a placeholder, and the proxy puts the task's key on each model call, so the agent never holds it; if the broker refuses the key, the call gets 503 and nothing is forwarded. delivery: env puts the key in the agent's environment instead. Each call is recorded under the key's credential.
7. Know what the agent can and cannot see
The agent can see the short-lived credentials its tools fetch, and its environment holds the task's id and token, which is how agentgarm credential proves it is in the task. It never sees the sealed upstream credentials: agentgarmd releases one for a single call to an unprivileged helper, agentgarm-broker, which makes the request and exits. Before the agent starts, a canary inside the sandbox checks that credential files such as ~/.aws, ~/.ssh and ~/.config/gcloud, AgentGarm's own state, and credential variables are out of reach, and the launch is refused if any is not.
On Linux the sandbox cannot close a desktop session's sockets, such as your own ssh-agent, so such a session is rated C. When the task ends its credentials are revoked, and on a node enrolled in Central Lite garm-central identity credential revoke revokes one sooner, by the id garm-central node show lists it under. Revocation at the end of a task is immediate; one from Central Lite takes effect when the node applies Central Lite's signed revocation list. Either stops new issues and the SSH socket, but an AWS session or GCP token already handed out stays valid at the provider until it expires, so keep ttl_seconds short.
garm-central identity credential revoke <credential id> --reason "task misuse"See also
Check that protection is onSee whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.