Sandboxed agents scale across replicas with S3 checkpoints

Agno's S3CheckpointStore(bucket, prefix=..., endpoint_url=...) stores each sandbox turn as one object named <prefix>/<sha256>.tar.gz, with the digest and size saved in the object's metadata. FileCheckpointStore was the only store in core before this, and the queue worker refuses its default path because another replica cannot read it.

Hand the store to the sandbox the same way you would a file store. Install agno[s3] for boto3.

from agno.agents.claude import ClaudeAgent
from agno.db.postgres import PostgresDb
from agno.sandbox.docker import DockerSandbox
from agno.sandbox.s3 import S3CheckpointStore
 
checkpoints = S3CheckpointStore("my-agno-checkpoints", prefix="sandbox/checkpoints")
 
agent = ClaudeAgent(
    id="coder",
    db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
    sandbox=DockerSandbox("agno-sandbox:local", checkpoints=checkpoints, network="isolated"),
)

put hashes the archive first and skips the upload when that object already exists. Archives above part_size (64 MiB by default) go up in parts, and a failed multipart upload is aborted. The archive limit of 1 GiB still applies. On the way back, open_archive downloads to a temporary file and hashes the bytes before handing over the path.

We ran the store against moto's local S3 server, with two store instances playing two replicas that share nothing but the bucket. Replica A captured a small workspace and replica B restored it:

put -> CheckpointRef(sha256='0a9686a94759f8f9dfbb5ad10bb46dc0a942e7a8b5be962cd760967faee18937', size=406)
put again -> True
object: sandbox/checkpoints/0a9686a94759f8f9dfbb5ad10bb46dc0a942e7a8b5be962cd760967faee18937.tar.gz 406 bytes {'sha256': '0a9686a94759f8f9dfbb5ad10bb46dc0a942e7a8b5be962cd760967faee18937', 'size': '406'}
restore on B -> {'turn': 1}
restored hello.py: print("hello")

Damaging the object three ways made replica B's verify fail each time:

# same size, different bytes, no digest in the metadata
verify -> SandboxError: Checkpoint checksum mismatch
# first 100 bytes only, digest metadata kept
verify -> SandboxError: Checkpoint size mismatch
# object deleted
verify -> CheckpointObjectNotFound: Checkpoint object is missing

Credentials come from the AWS environment or the deployment's role, so no secret goes into your code. For MinIO, R2 or a local test server, set endpoint_url.

See the cookbook, and learn more about deploying Claude and Codex services in the documentation.