# 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](sandboxes) with [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) 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](sandboxes), and 3. Copies the resulting output files to the user's machine. For details, see [How the agent runs](#how-the-agent-runs). ## Prerequisites Before you start, make sure you have all of the following: *Render* - A Render [API key](https://dashboard.render.com/u/settings?add-api-key) - Your Render workspace ID - Obtain this from the top of your workspace's *Settings* page in the [Render Dashboard](https://dashboard.render.com). *Anthropic* - An [Anthropic API key](https://platform.claude.com/settings/keys) - Access to the [Claude Managed Agents beta](https://platform.claude.com/docs/en/managed-agents/overview#beta-access) - 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](https://github.com/render-examples/claude-managed-agents-sandbox).* Clone the template and install its dependencies: ```shell git clone https://github.com/render-examples/claude-managed-agents-sandbox cd claude-managed-agents-sandbox npm ci ``` ### 2. Configure credentials 1. Copy the example environment file to `.env`: ```shell cp .env.example .env ``` The file looks like this: ```bash # Render RENDER_API_KEY= RENDER_WORKSPACE_ID= # Anthropic ANTHROPIC_API_KEY= ANTHROPIC_AGENT_ID= ANTHROPIC_ENVIRONMENT_ID= ANTHROPIC_ENVIRONMENT_KEY= ``` 2. Populate the values for these environment variables according to the table below: | Environment variable | Description | | --- | --- | | `RENDER_API_KEY` | Your Render [API key](https://dashboard.render.com/u/settings?add-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](https://dashboard.render.com). Starts with `tea-` | | `ANTHROPIC_API_KEY` | Your [Anthropic API key](https://platform.claude.com/settings/keys). 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: ```shell npm run agent -- "Create a hello world HTTP server in /workspace/output. Test it before you finish." ``` Claude's activity streams to your terminal, resembling the following: ``` preflight passed policy default-deny allow-list: api.anthropic.com and pinned ant release download hosts credential materialized restricted Anthropic Environment key; application API key excluded provision sbx-... worker polling session sesn_... session submitted session running tool write tool bash agent I created /workspace/output/server.js and confirmed it responds with "Hello, world!". result task completed outputs copied 1 file to runs/run_.../output cleanup session deleted; sandbox terminated ``` 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](sandboxes-creating#configuring-sandbox-behavior). | Customization | Description | | --- | --- | | *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](sandboxes-creating#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 ` (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 ` to specify a local destination directory. The default is `runs//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](https://platform.claude.com/docs/en/managed-agents/agent-setup). 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`](https://github.com/render-examples/claude-managed-agents-sandbox/blob/main/src/agent.ts) coordinates each run through the following stages: ------ ##### 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`](https://github.com/render-examples/claude-managed-agents-sandbox/blob/main/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`](https://github.com/render-examples/claude-managed-agents-sandbox/blob/main/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//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](#troubleshooting). Each run also saves the following files under `runs//`: - `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](sandboxes#beta-limitations).* 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](sandboxes-creating#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//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: ```shell set -a && source .env && set +a ``` The command that terminates a sandbox requires version 2.33.0 or later of the [Render CLI](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.