Deliver per-claim secrets

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#

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.

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).