# Deliver per-claim secrets

Give each claim of a warm pool its own cua-spacesd token, delivered into the sandbox when the claim binds.

> Agent discovery: use [the Cua documentation index](https://cua.ai/docs/llms.txt) to find related pages and their Markdown URLs.



A warm replica boots before anyone claims it, so it cannot be built with a
secret meant for one claimant. Claim secrets close that gap: when a claim
binds, Fleet delivers a Secret into the already-running sandbox, and the guest
reads it at `/run/cua/env-token`. cua-spacesd uses that file as its env token,
so each claim gets its own token, which never crosses the network to the guest.

## Enable it on the pool

Set `claim_secrets=True` in the pool's `SandboxSpec` (Terraform:
`claim_secrets = true` on `fleets_pool`). The image must run cua-spacesd, which
waits for the token file before it accepts calls.

## Claim with a token

```python test="docs" id="claim-token" session="claim-token" prelude="fakefleet,pool-name"
import os

from cua_sandbox import Image, Pool, PoolOptions, SandboxSpec, generate_claim_token

pool = await Pool.apply(
    os.environ["CUA_POOL_NAME"],
    SandboxSpec(image=Image.linux(), services={"env": 3211}, claim_secrets=True),
    PoolOptions(replicas=1),
)
token = generate_claim_token()          # 64 hex characters from the OS RNG
async with pool.claim(claim_token=token) as sb:
    print((await sb.shell.run("uname -a")).stdout.strip())
await pool.delete()
```

The SDK writes the Secret `cua-claim-<claim>` (key `env-token`), creates the
claim against it, and waits until spacesd answers with the token.

| Language | Call |
| --- | --- |
| Python | `generate_claim_token()`, `pool.claim(claim_token=...)` |
| TypeScript | `fleetGenerateClaimToken()`, `fleet.acquireWith(pool, options)` with `claimToken` set |
| Rust | `fleet_generate_claim_token()`, `Fleet::acquire_with(pool, options)` with `claim_token` set |

A token is 16 to 4096 characters of the bearer-token alphabet
(`A-Z a-z 0-9 - . _ ~ + / =`); the SDK rejects one spacesd would refuse.

## When the token does not arrive

Delivery is asynchronous (about 40 seconds on gVisor). The
claim waits at most 90 seconds after it binds. If spacesd still reports
`awaiting token`, the SDK releases the claim and raises
`ClaimSecretsNotDelivered` (`CuaError.ClaimSecretsNotDelivered` in the other
bindings). Check that the pool has `claim_secrets` enabled and that the image's
cua-spacesd reads `/run/cua/env-token`.

The Secret belongs to the claim: releasing the claim deletes it. Other
credentials your workload needs still go in at runtime
([Pass secrets into a sandbox](</docs/cua-sdk/guides/secrets>)).