Run Claude Managed Agents sandboxes on a VPS
Run the ant worker for a Claude Managed Agents self-hosted sandbox on Ubuntu under systemd, and learn which data still leaves your VPS and why.
What a Claude Managed Agents self-hosted sandbox is
A Claude Managed Agents self-hosted sandbox keeps the agent's tool calls on your own server. Anthropic still runs the agent loop and the model. You run one process on a VPS, called the environment worker. It claims queued sessions and runs their tool calls locally. The results go back over outbound HTTPS.
The docs compare three ways to deploy Managed Agents. Each one moves a different part onto your hardware:
- Cloud sandboxes (the default): Anthropic hosts the sandboxes and the service, and Anthropic runs the model.
- Self-hosted sandboxes: you host the sandboxes. Anthropic hosts the service and runs the model.
- Self-hosted Managed Agents: you host the sandboxes and the service. The model is Anthropic's, or comes from a provider you choose.
This guide builds the middle option on Ubuntu 24.04. The docs give one rule for picking it: "Choose a self-hosted sandbox only if tools must run on infrastructure you control." If you are new to Managed Agents, start with a cloud environment. If you have never called the API from a server at all, build a first Claude API app on a VPS before this one. Self-hosted sandboxes are in beta on every model, and every request needs the managed-agents-2026-04-01 beta header. The SDKs and the ant CLI set that header for you.
What stays on the VPS, and what still goes to Anthropic
"Self-hosted" sounds like more privacy than this option gives, so be exact before you build. The sandbox's files and processes stay on your worker. Tool inputs and tool outputs do not stay. They flow back to Managed Agents on Anthropic's side, because the model needs each result to decide its next step. The docs list what reaches Anthropic: the conversation history, tool results, skills and memory stores.
This has a direct consequence. If a tool call prints a file, the contents of that file are now a tool result, and tool results go to Anthropic. The web search and web fetch tools also run on Anthropic's side, not in your sandbox. The docs say that neither environment option changes the compliance coverage of Managed Agents or how long it keeps conversation history. What the middle option buys you is location: tool calls run from your server's network position, so they can reach services on your private network.
Files and repositories must be staged by you
Self-hosted sandboxes accept only memory_store session resources. A session on a self-hosted environment that includes a file or github_repository resource is rejected with a 400 error:
Environment env_... is a self-hosted environment. `resources` are not supported with self-hosted environments.Scheduled deployments that target a self-hosted environment follow the same rule. The documented workaround puts a file reference, such as an S3 path or a commit SHA, in the session's metadata. A spawn script or --on-work handler then reads the session with GET /v1/sessions/{session_id} and copies the files into the working directory before any tool runs. The script must fetch the session itself because the claimed work item carries the session ID but not the metadata. The docs describe this step for the per-session pattern later in this guide, not for the plain always-on worker.
You also lose the preinstalled runtimes and packages of a cloud sandbox. Install the interpreters and tools your agent needs on the VPS before the first session. The same docs page lists repository skill discovery and environment-variable credentials in vaults as further things a self-hosted sandbox does not get.
Step 1: create the self_hosted environment
In the Claude Console, open the Environments page, click Create environment, and under Hosting select Self-hosted. Or create it through the API. Run this on your own machine, not on the VPS, because it uses your Claude API key:
curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "self-hosted",
"config": {"type": "self_hosted"}
}'The response holds the environment ID, which starts with env_. Write it down. The model is set on the agent, not on the environment, so any model your agent already uses works here.
Step 2: generate the environment key in the Console
Open the environment in the Console and click Generate environment key. This step is Console-only. The docs say: "You can generate one only in the Console, even for an environment you created through the API." The key starts with sk-ant-oat01-.
You now handle two different credentials. Keep them apart:
- The Claude API key is scoped to your whole organization. It creates sessions and reads queue stats. It belongs on your own machine. The docs say to "Keep it off the worker host, where agent tool calls could read it."
- The environment key lets a worker poll one environment's work queue and submit results back to its sessions. It has to live on the worker host.
Revocation is checked on every request, so a revoked environment key stops working on the worker's next call. Rotate it at once if you think it leaked. This guide uses the Claude API directly. On Claude Platform on AWS, and on Claude Models on Google Cloud (Anthropic managed), Console environment keys do not work, and the worker authenticates with cloud credentials instead.
Step 3: install the ant CLI, pinned to 2.9.0
The worker ships inside the ant CLI. On 15 November 2026 the docs pin version 2.9.0, and the project's GitHub releases list v2.9.0, published 10 November 2026, as the newest stable release. Versions 2.8.0 and 2.7.1 shipped in the days before it, so the pin moves often. Check the docs' install step before you copy this. Run it on the VPS:
VERSION=2.9.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
x86_64) ARCH=amd64 ;;
aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
| sudo tar -xz -C /usr/local/bin ant
ant --versionant --version should report version 2.9.0. If uname -m prints something other than x86_64 or aarch64, ARCH stays empty. The URL then points at a file that does not exist, and curl stops with curl: (22) The requested URL returned error: 404. Install the same CLI on your own machine too, because the stats and session commands in Step 7 run there.
The worker host must have /bin/bash at that exact path, because the worker's bash tool runs it directly and does not search PATH. Ubuntu has it. The docs list Linux or macOS as the supported hosts.
The security model: the worker does not isolate the shell
This section is the reason the rest of the setup looks the way it does. The self-hosted docs carry this warning:
The agent's bash tool is a real shell with the worker process's permissions and network access. The worker doesn't isolate that shell.
The warning goes on to say that isolation comes from what the worker runs in, and that "If you start a worker yourself, run it in a disposable container or VM that holds nothing you need to protect." A systemd service on your VPS is exactly a worker you start yourself. So the VPS itself must be that disposable machine. Do not run this worker on the box that holds your database or your backups. The same reasoning is behind running coding agents in a disposable VM: assume the agent can do anything its user can do, then make that user able to do very little.
The worker has a path setting for its file tools, but the reference page says plainly: "The confinement is a guardrail for the file tools only, not a sandbox. It does not constrain bash." The security page adds the practical rules. Apply least privilege to the process user, mount only the directories tools need, run as a non-root user, and restrict outbound traffic. Without egress controls, a compromised tool call can reach any host on the internet. Anthropic does not inspect your sandbox, so all of this is your job.
Step 4: a dedicated user and a working directory
Create a system user that owns nothing except the working directory. It has no sudo rights and is not in the docker group.
sudo useradd --system --home-dir /var/lib/ant-worker --shell /usr/sbin/nologin ant-worker
sudo install -d -o ant-worker -g ant-worker -m 750 /workspace
id ant-worker
ls -ld /workspaceid ant-worker should list only the ant-worker group. ls -ld /workspace should show drwxr-x--- owned by ant-worker. The /workspace path matches the docs' quickstart, which calls it the system default working directory. For why each service deserves its own user, and how to check what a user can still reach, see least-privilege users on a VPS.
Step 5: the key file, and where this guide departs from the docs
The docs' security page is clear about the environment key: "Store it in a secrets manager, not in environment files or sandbox images." A single VPS often has no secrets manager. This guide uses a root-owned file with mode 600, which systemd reads before it starts the worker as ant-worker. That is a compromise against the docs' advice, and you should know exactly what it protects.
It protects the key at rest. The ant-worker user cannot read the file, so a tool call cannot cat it. It does not protect the key at run time. The worker process holds the key in its environment, and the agent's shell runs as that same user. Plan as if a tool call can read the key. If you have Vault or a cloud secrets manager, fetch the key from there at service start instead.
sudo install -d -m 700 /etc/ant-worker
sudo install -m 600 /dev/null /etc/ant-worker/worker.env
sudoedit /etc/ant-worker/worker.envPut two lines in the file, with your real values:
ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-...
ANTHROPIC_ENVIRONMENT_ID=env_...Never add ANTHROPIC_API_KEY here. The operations page warns that setting it on the worker host "exposes an organization-scoped credential to agent tool calls." Using sudoedit instead of the quickstart's export lines also keeps the key out of your shell history. Check the permissions:
sudo ls -l /etc/ant-worker/worker.env
sudo -u ant-worker cat /etc/ant-worker/worker.envThe first command should show -rw------- and root root. The second must fail with cat: /etc/ant-worker/worker.env: Permission denied. If it prints the key, the mode is wrong. More patterns for keeping credentials away from tool calls are in keeping secrets out of AI agents.
Step 6: run ant beta:worker poll as a systemd service
The docs contain no systemd unit. The unit below is this guide's own design, built from the docs' rules. Save it as /etc/systemd/system/ant-worker.service:
[Unit]
Description=Claude Managed Agents self-hosted sandbox worker
Wants=network-online.target
After=network-online.target
[Service]
Type=simple
User=ant-worker
Group=ant-worker
EnvironmentFile=/etc/ant-worker/worker.env
Environment=HOME=/var/lib/ant-worker
StateDirectory=ant-worker
WorkingDirectory=/workspace
ExecStart=/usr/local/bin/ant beta:worker poll --workdir /workspace
Restart=on-failure
RestartSec=5
KillSignal=SIGTERM
TimeoutStopSec=60
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/workspace
[Install]
WantedBy=multi-user.targetEach choice has a reason:
KillSignal=SIGTERMwithTimeoutStopSec=60: the docs say the CLI handles SIGTERM itself. It cancels any in-flight tool call and posts its error result. Then it marks the work itemstopped. The docs ask for at least 30 seconds before any hard kill, and 60 leaves room.ProtectSystem=strictmakes the whole file system read-only for this unit and for every process it starts, which includes the agent's shell. Only/workspaceand the state directory under/var/lib/ant-workerstay writable.ProtectHome=yeshides/homeand/root, so the agent cannot read other users' files.PrivateTmp=yesgives the unit its own/tmp.NoNewPrivileges=yesstops any program the agent runs from gaining privileges through setuid binaries such assudo.
A tool call that writes outside /workspace now fails with Read-only file system. That is the unit doing its job. Add a path to ReadWritePaths only when a tool really needs it. The details of these directives are in systemd sandboxing with ProtectSystem and PrivateTmp. Start the service:
sudo systemctl daemon-reload
sudo systemctl enable --now ant-worker
systemctl status ant-worker --no-pager
journalctl -u ant-worker -n 50 --no-pagersystemctl status should show active (running). If you attach memory stores later, the memory docs require a writable /mnt/memory owned by the worker's user. Create it, chown it to ant-worker, and add it to ReadWritePaths. A worker that is killed rather than stopped loses unsynced memory edits, which is one more reason to keep the stop timeout.
Step 7: confirm the worker is connected
On your own machine, set the API key and the environment ID, then read the queue stats:
export ANTHROPIC_API_KEY="..."
export ANTHROPIC_ENVIRONMENT_ID="env_..."
ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"The response has the type work_queue_stats, with the fields depth, pending, oldest_queued_at and workers_polling. workers_polling counts workers that polled in the last 30 seconds, so it should be at least 1. Then send a test session. Set AGENT_ID to your agent's ID:
ant beta:sessions create \
--agent "$AGENT_ID" \
--environment-id "$ANTHROPIC_ENVIRONMENT_ID"
ant beta:sessions:events send --session-id "$SESSION_ID" <<'YAML'
events:
- type: user.message
content:
- type: text
text: Write the output of "uname -a" to hello.txt in your working directory.
YAMLSESSION_ID is the ID from the create response. On the VPS, read the file:
sudo cat /workspace/hello.txtIt should describe the VPS kernel, which proves the tool call ran on your server.
Why is the session stuck in the queue?
A session sent to an environment with no connected worker waits in the queue. It does not fail, so nothing tells you it is stuck. Check workers_polling first. If it stays at 0, the worker is not reaching the queue. Work through these in order:
systemctl status ant-workershowsstatus=203/EXEC: systemd could not run the binary, becauseantis not at/usr/local/bin/ant. Runls -l /usr/local/bin/ant.- It shows
status=200/CHDIR: theWorkingDirectoryis missing. Create/workspaceagain with Step 4. - The service runs but
workers_pollingis 0: check that bothANTHROPIC_ENVIRONMENT_KEYandANTHROPIC_ENVIRONMENT_IDare in the env file, then readjournalctl -u ant-worker -n 50for the error. - Your firewall filters outbound traffic: the worker needs outbound HTTPS to the API. It needs no inbound port at all.
The stronger pattern: one fresh container per session
The service above runs every session in one process, in one shared working directory, as one user. Files that session A leaves in /workspace are visible to session B. The docs describe a stronger option: "Sandbox per session: A poller launches a fresh sandbox for each claimed session. Choose this for stronger isolation: a fresh filesystem, resource limits, or per-session network controls."
It works in two parts. A poller on the host runs ant beta:worker poll --on-work with a script. For each claimed work item, the poller calls the script with the work item as JSON on standard input. The script starts a container whose entrypoint is ant beta:worker run, which handles that one session and exits. The poller sets the ANTHROPIC_* variables for the script, except the per-session secret, which the script reads from the JSON.
This needs Docker on the host, and Docker's own docs say: "The docker group grants root-level privileges to the user." So the account that runs the poller is effectively root. The isolation here is between the agent and the host, and the container provides it. Install the tools and create the directories:
sudo apt install -y docker.io jq
sudo install -d -m 700 /opt/ant-poller
sudo install -d -m 755 /srv/agent-outputsThe docs' Dockerfile starts FROM your-base-image. This version fills in Ubuntu 24.04 and reads the architecture from uname -m, so it builds the same way on amd64 and arm64. Save it as /opt/ant-poller/Dockerfile:
FROM ubuntu:24.04
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates curl \
&& rm -rf /var/lib/apt/lists/*
ARG ANT_VERSION=2.9.0
RUN case "$(uname -m)" in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac \
&& curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
| tar -xz -C /usr/local/bin ant
WORKDIR /workspace
VOLUME /workspace
ENTRYPOINT ["ant", "beta:worker", "run"]sudo docker build -t ant-sandbox:2.9.0 /opt/ant-pollerSave the spawn script as /opt/ant-poller/spawn.sh and make it executable with sudo chmod 700 /opt/ant-poller/spawn.sh. The first lines and the -e flags come from the docs. The --user, --read-only, --cap-drop, --security-opt and resource flags are this guide's additions. They follow the security page's advice on running as a non-root user and dropping capabilities, and --read-only follows its advice on a read-only root file system:
#!/bin/bash
# spawn.sh: called once for each claimed work item
# The claimed work item arrives as JSON on stdin.
ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
export ANTHROPIC_WORK_SECRET
OUT="/srv/agent-outputs/$ANTHROPIC_SESSION_ID"
mkdir -p "$OUT"
chown 10001:10001 "$OUT"
exec docker run --rm \
--user 10001:10001 \
--read-only --tmpfs /tmp -e HOME=/tmp \
--cap-drop ALL --security-opt no-new-privileges \
--memory 2g --cpus 1 --pids-limit 256 \
-e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
-e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
-e ANTHROPIC_WORK_SECRET \
-v "$OUT":/workspace \
ant-sandbox:2.9.0The output directory under /srv/agent-outputs keeps each session's deliverables after the container is gone. The docs note that this mount also picks up the downloaded skills/ tree and intermediate files. If a session's log shows Read-only file system for some path, add a --tmpfs for that path rather than removing --read-only. The script still forwards the environment key into each container, as the docs' own example does. The docs' rule is to forward the environment key and never your API key. Pass the work secret only into the container that serves that session, and never log it.
Run the poller as a root systemd service. Save this as /etc/systemd/system/ant-poller.service. Stop the in-process ant-worker service first, so that only one worker claims sessions:
[Unit]
Description=Claude Managed Agents per-session sandbox poller
Wants=network-online.target docker.service
After=network-online.target docker.service
[Service]
EnvironmentFile=/etc/ant-worker/worker.env
WorkingDirectory=/opt/ant-poller
ExecStart=/usr/local/bin/ant beta:worker poll --on-work /opt/ant-poller/spawn.sh
Restart=on-failure
TimeoutStopSec=60
[Install]
WantedBy=multi-user.targetsudo systemctl disable --now ant-worker
sudo systemctl daemon-reload
sudo systemctl enable --now ant-poller
journalctl -u ant-poller -fSend the Step 7 test session again. The hello.txt file now appears under /srv/agent-outputs/<session ID>/. Two limits remain. First, the containers sit on Docker's default bridge network, so they can reach any host. Per-session network controls are the next thing to add, but --network none would break the session, because the worker inside needs outbound HTTPS. Second, with --on-work the poller ignores --max-idle. If you need that flag, pass it to the ant beta:worker run that the script starts.
What it costs
Managed Agents bills tokens at standard model prices plus session runtime. On 15 November 2026, the official pricing page does not say how the runtime charge applies to self-hosted sandbox environments, so read the current Claude pricing page before you budget for it. For pricing of the full self-hosted service, the page tells you to contact your Anthropic account team.
Full self-hosted Managed Agents, for context
The third option runs the whole service on your own infrastructure. The server is cma-server, and it needs PostgreSQL 16 or later. Without a database the server keeps its data in memory, and a restart erases it. Workers are the same ant beta:worker or SDK workers used above. Access is by request through your Anthropic account team.
Even then, data does not stay on your hardware by default. The docs say that for each model call the server sends the conversation so far, including tool inputs and tool results, to your inference provider. By default, that provider is the Claude API. Zero data retention is available for the full self-hosted service, but not for self-hosted sandboxes.
FAQ
Does a self-hosted sandbox keep my data off Anthropic's servers?
No. The sandbox's files and processes stay on your worker, but tool inputs, tool results, the conversation history, skills and memory stores reach Anthropic, because the model runs there and needs each result. Web search and web fetch also run on Anthropic's side. A self-hosted sandbox changes where tools execute. It does not change the compliance coverage of Managed Agents or how long conversation history is kept.
Why does my self-hosted session stay queued and never start?
A session sent to an environment with no connected worker waits instead of failing. Run ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID" from your own machine. If workers_polling stays at 0, the worker is not polling. Check that both ANTHROPIC_ENVIRONMENT_KEY and ANTHROPIC_ENVIRONMENT_ID are set on the worker host and that outbound HTTPS is allowed. Then read the service log with journalctl -u ant-worker -n 50.
Can I attach a file or a GitHub repository to a self-hosted session?
No. Self-hosted environments accept only memory_store resources, and a session with a file or github_repository resource is rejected with a 400 error saying resources are not supported with self-hosted environments. Put a reference such as an S3 path or commit SHA in the session's metadata. Then have your spawn script fetch the session and copy the files into the working directory before any tool runs.
Can I put my Claude API key on the worker host?
No. The docs say to keep it off the worker host, because agent tool calls could read it, and the key is scoped to your whole organization. The worker needs only the environment key and the environment ID. Create sessions and read queue stats from your own machine with the API key.
Do I need Docker to run a self-hosted sandbox on a VPS?
Not for the basic setup. ant beta:worker poll --workdir /workspace runs every session in one process, and a systemd service with a dedicated user is enough. You need Docker, or another sandbox launcher, for the stronger pattern. There, ant beta:worker poll --on-work starts a fresh container running ant beta:worker run for each session.