Add sandboxes and checkpoints

Run Claude and Codex engineers in a separate AgentCore environment, with S3 storing their workspace and native-session checkpoints. Your API stays on Render and uses PostgreSQL for conversations and platform records.

Complete the Render deployment first. You'll also need an AWS account, permissions to create an ECR repository, an AgentCore runtime and execution role, and a private S3 bucket. These resources incur AWS charges.

Understand what is saved

A saved conversation does not recreate an engineer's working directory. Recovery starts from the last successfully saved checkpoint. Unfinished edits, live processes, and external actions are outside that checkpoint.

Build the sandbox image

From your template checkout, build its sandbox target for ARM64. Replace the image URL with your ECR repository URI and a tag you will retain:

SANDBOX_ECR_IMAGE=YOUR-ECR-URI:YOUR-TAG
docker build --target sandbox --platform linux/arm64 --load -t "${SANDBOX_ECR_IMAGE}" .

Authenticate Docker to your ECR registry and push the image using ECR's push instructions.

Create an AgentCore Runtime from this image with its execution role. Use the image's existing entrypoint, which serves Agno's sandbox protocol on port 8080. Configure the runtime for HTTP and IAM-authenticated invocation, and wait for it to become ready. See AgentCore Runtime deployment for AWS provisioning.

Keep the runtime ARN and image tag with your deployment configuration. The template does not create these AWS resources for you.

Configure the repository and checkpoint store

Create a private S3 bucket for checkpoints. Choose a prefix for this platform, such as my-platform/checkpoints/.

In app/sandbox.py, set the repository and branch to your own code:

REPOSITORY = Repository("https://github.com/YOUR-ORG/YOUR-REPO", branch="my-agent-platform")

Replace sandbox_provider() with:

def sandbox_provider() -> Sandbox | None:
    return agentcore_sandbox(
        "arn:aws:bedrock-agentcore:REGION:ACCOUNT:runtime/YOUR-RUNTIME",
        "your-checkpoint-bucket",
        checkpoint_prefix="my-platform/checkpoints/",
    )

The template's agentcore_sandbox() helper constructs AgentCoreSandbox with S3CheckpointStore. Both engineers use the selected provider. Keep the existing imports and helper functions.

Use the same bucket and prefix across this platform's API replicas, and distinct prefixes for separate platforms.

Give the API and sandbox their credentials

Configure the Render API service's AWS credentials through its environment settings or your credential provider. Set AWS_DEFAULT_REGION to the S3 bucket's region. The runtime ARN supplies the AgentCore region.

The API identity needs permission to invoke and stop the configured runtime, and to read, write, delete, and abort multipart uploads under the checkpoint prefix. Configure bucket-list permissions as needed for missing-object handling. Customer-managed KMS encryption also requires key permissions. Keep active checkpoint objects out of expiration rules.

Agno forwards the configured engineer model credentials into the sandbox. The API's AWS credentials are not automatically forwarded. Code in the sandbox can use the AgentCore execution role; grant that role the access required for the engineering work.

For a private Git repository, supply GITHUB_READ_TOKEN in the provider's env mapping. For example, add this argument to AgentCoreSandbox(...) inside agentcore_sandbox(), after importing getenv from os:

env={"GITHUB_READ_TOKEN": getenv("GITHUB_READ_TOKEN", "")},

Read the value from your environment or secret store. Configure push or pull-request permissions separately if the engineer will publish changes. The template's sandbox guide also covers Claude through Bedrock and local Docker sandboxes.

Redeploy and check recovery

Commit and push the provider configuration to the branch Render deploys. Apply any changed production environment settings with ./scripts/render/env-sync.sh.

Use a disposable repository or branch for the recovery check:

1. Start a conversation with one engineer and ask it to create a small file in its workspace containing a unique marker.
2. Wait for the turn to complete. Inspect logs and S3 to confirm a checkpoint was saved.
3. Replace the API instance and stop that test sandbox session using your provider tooling.
4. Continue the same AgentOS conversation as the same user with the same engineer. Ask it to read the marker file and continue the prior task.
5. Inspect the restored file, native-session continuity, and run outcome. Repeat for the other engineer.

Investigate missing or inaccessible checkpoints before treating a fresh workspace as successful recovery. No persistent disk is attached to the Render API; it uses temporary files while transferring checkpoint archives.

Before using the sandbox for Company Tasks, verify the Product's saved Git Source matches REPOSITORY.url and keep the local source so Company can read the files. Test a Task through its final persisted result as well as a direct engineer run.

Continue to Scale across replicas.