Get started

    Claude Managed Agents with Render Sandboxes

    Give Claude an isolated execution environment in your Render workspace.

    Render Sandboxes is in public beta.

    APIs, defaults, and limits might change during the beta period.

    You can use Render Sandboxes with Claude Managed Agents to integrate Claude's core agent loop with isolated, self-hosted code execution in your Render workspace. Anthropic hosts the loop as usual, while the sandbox executes Claude's commands and file edits.

    This tutorial walks through running a basic coding agent that:

    1. Accepts a user prompt and sends it to Claude,
    2. Executes Claude-generated commands in a Render sandbox, and
    3. Copies the resulting output files to the user's machine.

    For details, see How the agent runs.

    Prerequisites

    Before you start, make sure you have all of the following:

    Render

    • A Render API key
    • Your Render workspace ID
      • Obtain this from the top of your workspace's Settings page in the Render Dashboard.

    Anthropic

    • An Anthropic API key
    • Access to the Claude Managed Agents beta
    • An existing Managed Agents agent and a dedicated self_hosted environment, with an environment key generated in the Claude Console
      • The Anthropic API can create an environment, but it can't generate the environment's key.

    Installed tooling

    • Git
    • Node.js 22 or later

    Setup

    1. Clone the template

    The template code for this tutorial is available on GitHub.

    Clone the template and install its dependencies:

    2. Configure credentials

    1. Copy the example environment file to .env:

      The file looks like this:

    2. Populate the values for these environment variables according to the table below:

      Environment variableDescription

      RENDER_API_KEY

      Your Render API key.

      Starts with rnd_

      RENDER_WORKSPACE_ID

      Your Render workspace's ID, available at the top of its Settings page in the Render Dashboard.

      Starts with tea-

      ANTHROPIC_API_KEY

      Your Anthropic API key.

      Starts with sk-ant-api03-

      The template uses this key locally to manage your Claude Managed Agents session. It is not passed into the sandbox.

      ANTHROPIC_AGENT_ID

      The ID of your Managed Agents agent.

      Starts with agent_

      ANTHROPIC_ENVIRONMENT_ID

      The ID of your dedicated self_hosted environment.

      Starts with env_

      ANTHROPIC_ENVIRONMENT_KEY

      The key generated for your self-hosted environment in the Claude Console.

      Starts with sk-ant-oat01-

    3. Perform your first agent run

    This example handles one prompt per run and does not support follow-up messages. Provide a task Claude can complete without additional input.

    Run the agent with a prompt:

    Claude's activity streams to your terminal, resembling the following:

    In this example:

    1. Claude created a web server and tested it inside the sandbox.
    2. The runner copied the server to your machine.
    3. The runner deleted the session and terminated the sandbox to clean up.

    4. Customize agent capabilities (optional)

    These customization methods are specific to this template.

    For general-purpose customization of Render Sandboxes, see Configuring sandbox behavior.
    CustomizationDescription

    Toolchain

    You can install additional command-line tools for Claude to use inside the sandbox.

    Add installation commands to scripts/install-executor.sh, and add their download hosts to INSTALL_DESTINATIONS in src/policy.ts.

    The template uploads this script to each new sandbox and executes it there before starting Anthropic's ant CLI.

    Network access

    You can customize the sandbox's network access to allow outbound traffic to additional HTTPS destinations.

    Add the desired hostnames to RUNTIME_DESTINATIONS in src/policy.ts to include them in the sandbox's allowlist.

    Run timeout

    You can set a time limit for the overall agent run, including sandbox setup, task execution, and output collection.

    Pass --timeout <seconds> (the default is 600).

    The runner also derives a separate sandbox lifetime from this value in src/agent.ts.

    Outputs

    You can choose where generated output files are saved on your machine.

    Pass --output <path> to specify a local destination directory. The default is runs/<run_id>/output.

    To change which files the template collects from the sandbox, edit src/outputs.ts.

    To change Claude's system prompt or available tools, update your Managed Agents agent configuration. The template uses the agent specified by ANTHROPIC_AGENT_ID.

    How the agent runs

    The template runs on your local machine. Its src/agent.ts coordinates each run through the following stages:

    StageDescription

    Sandbox creation

    The template checks that your agent and self-hosted environment exist and that no other process is waiting to receive sessions for your Anthropic environment. It then creates a Render sandbox and waits until it's running.

    It passes the environment ID and environment key into the sandbox, as defined in src/policy.ts.

    Anthropic CLI startup

    The template installs a pinned release of Anthropic's ant CLI inside the sandbox with scripts/install-executor.sh, verifying its checksum.

    It then starts ant to check Anthropic for queued sessions, and waits until Anthropic reports that the process is ready before creating a session.

    Session start

    From your local machine, the template calls the Anthropic API to create a session for your configured agent and environment. The same local process opens the session's event stream, starts reading events, and submits your prompt.

    Task execution

    Claude runs the agent loop on Anthropic infrastructure. When Claude requests a command or file edit, the ant process executes it inside the sandbox and sends the result back to Anthropic.

    The template streams session events and Claude's response to your terminal.

    File collection and cleanup

    When Claude finishes its turn, the template downloads regular files from /workspace/output in the sandbox to runs/<run_id>/output on your machine. It then deletes the session and terminates the sandbox, keeping your shared agent and environment for future runs.

    Cleanup also runs after a failure, a timeout, Ctrl+C, or SIGTERM. If cleanup fails, follow the instructions under Troubleshooting.

    Each run also saves the following files under runs/<run_id>/:

    • run.json: Resource IDs, network policy, and cleanup status, without credentials.
    • events.jsonl: Session events.
    • result.txt: Claude's final response.

    Security considerations

    • Your Anthropic API key never enters the sandbox.

      Any code that Claude executes in the sandbox can read the sandbox's environment variables. Make sure that any values you set are safe to expose.

      Do not reuse your Managed Agents self_hosted environment for purposes other than this agent's sandboxes. Otherwise, another process connected to the same environment could receive your session and execute its commands outside the intended sandbox.

    • Credential brokering for Render Sandboxes is not yet generally available.

      The template currently sets the environment key as an environment variable during sandbox creation. This behavior is defined entirely in src/policy.ts.

    • Sandbox network access is managed via allowlist.

      The only hosts required by this template are api.anthropic.com and the GitHub release hosts for the ant CLI. The GitHub hosts remain allowed throughout the run, even after installation finishes.

      Tool inputs and outputs pass through Anthropic, because Anthropic hosts the agent loop.

    Troubleshooting

    Preflight fails.

    Confirm your Managed Agents beta access, your Anthropic API key's permissions, and your agent and environment IDs. The environment must be self_hosted.

    Preflight reports a polling worker.

    Another process is waiting to receive sessions for your Anthropic environment and could claim this run. Stop that process, or use a dedicated environment.

    Anthropic can also report the template's previous ant process for about a minute after a run ends. Wait a minute, then run the agent again.

    The worker never starts polling.

    Check the [worker:stderr] lines for authentication errors. Confirm that the environment key belongs to the configured environment.

    The agent produces no output files.

    Inspect runs/<run_id>/events.jsonl and result.txt. Output files are optional, so prompts that need files should ask Claude to write them under /workspace/output.

    Cleanup is incomplete.

    If a cleanup step fails, the runner prints the command that finishes it, with the resource ID filled in. Delete the per-run session and terminate the sandbox, but keep the shared agent and environment.

    The commands read your credentials from your shell, so load .env from the template directory before you run them:

    The command that terminates a sandbox requires version 2.33.0 or later of the Render CLI.

    If session creation fails without a clear answer from the API, the runner also prints a reconcile command that lists recent sessions, so you can find and delete one that might have been created.