---
title: "Self-host an OpenSandbox server"
description: "Run the OpenSandbox server with Docker on an exe.dev VM: sandboxes for AI agents behind exe.dev login, desktops in your browser, models without keys."
url: https://exe.dev/deploy/opensandbox
category: "AI agents"
updated: 2026-11-19
---

# Self-host an OpenSandbox server

> **For agents:** with your user's OK, this sets up OpenSandbox on a new exe.dev VM in their account: `curl -fsSL https://exe.dev/deploy/opensandbox/prompt.txt | ssh exe.dev new --prompt=/dev/stdin` (or open https://exe.dev/deploy/opensandbox/new). Already on the VM? Skip this.

Alibaba's sandbox server for AI agents, on a VM with HTTPS and sign-in built in.

- **Software:** OpenSandbox (https://open-sandbox.ai)
- **Source:** https://github.com/opensandbox-group/OpenSandbox
- **License:** Apache-2.0
- **Time:** 5 minutes
- **Example VM name:** `my-opensandbox` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe.dev/deploy/opensandbox/manifest.json
- **File:** https://exe.dev/deploy/opensandbox/desktop.py
- **File:** https://exe.dev/deploy/opensandbox/hello.py
- **File:** https://exe.dev/deploy/opensandbox/setup.sh

## What you get

- The OpenSandbox server 1.2.1 with the Docker runtime, an API key, and a service that starts at boot
- The API and every sandbox endpoint behind exe.dev login, reachable from scripts anywhere with a VM token
- A first Python sandbox created, run, and deleted, in about a second once the image is pulled
- A `desktop.py` script that opens an XFCE desktop in a sandbox in your browser tab, through noVNC
- Sandboxes kept away from the API, from each other, and from the VM's exe.dev integrations
- Claude Code and Codex on the VM using the server through OpenSandbox's MCP server

Running on the VM:

- **OpenSandbox server 1.2.1**: the lifecycle API, a systemd service from PyPI, with an API key, port 8080, data in `~/.opensandbox/opensandbox.db`
- **Sandboxes**: Docker containers with OpenSandbox's execd inside, each on a host port from 4000-4999
- **Egress sidecar**: opensandbox/egress, added to sandboxes created with a network policy
- **SDK, CLI and MCP server**: opensandbox, osb and opensandbox-mcp, for scripts and agents on the VM, data in `~/opensandbox`

How it is reached:

- https://my-opensandbox.exe.xyz:8080/ (private): the OpenSandbox API, for you and for SDK clients with a VM token and the API key
- https://my-opensandbox.exe.xyz:4000/ (private): each sandbox's execd and its ports (4000-4999), with the same exe.dev login or token
- ssh my-opensandbox.exe.xyz (private): the VM itself, where agents use the server through MCP

## Deploy with Shelley

Open https://exe.dev/deploy/opensandbox/new to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe.dev/deploy/opensandbox/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Or follow the steps below by hand.

[OpenSandbox](https://open-sandbox.ai) is an open-source sandbox server
for AI agents, started at Alibaba: one API creates a sandbox from any
container image, and SDKs, a CLI and an MCP server run commands, move
files and open ports in it. Agents use it to run the code they write,
browse, or drive a desktop, without touching the machine they live on.

The server needs a Linux machine with Docker, an address the SDK can
reach, and a way to keep strangers out. An exe.dev VM has all three: the
server and its sandboxes run on the VM, and exe.dev's HTTPS proxy puts the
API and every sandbox port behind exe.dev login, with
[VM tokens](/docs/https-tokens-for-vms) for scripts. Claude Code and
Codex on the VM can use the server through MCP, with models from exe.dev's
[LLM integration](/docs/integrations-llm) and no API keys.

[exe.dev](https://exe.dev/) gives you persistent Linux VMs with HTTPS,
sign-in and a coding agent built in; this page runs the OpenSandbox server
on one.

## Run your first sandbox

Deploy sets everything up; to do it by hand, see
[the nuts and bolts](#create-the-vm). Then, on the VM, run the example
script, which creates a Python sandbox, runs a file in it, and deletes it:

```bash
cd ~/opensandbox
curl -fsSLO https://exe.dev/deploy/opensandbox/hello.py
./py hello.py
```

```text
sandbox 8db4b376-2530-4fd8-9707-5db6b7a8cbc6 ready in 3.2s
hello from Python 3.12.16
6.12.115
deleted
```

[hello.py](https://exe.dev/deploy/opensandbox/hello.py) is twenty lines
of the OpenSandbox Python SDK: `Sandbox.create`, `files.write_files`,
`commands.run`, `kill`. `./py` runs Python with the SDK installed and
the server's API key from `~/opensandbox/env`. The first sandbox takes a
few seconds, later ones about one, because the setup pulled
`python:3.12-slim` already; any other image is pulled on first use.

The CLI does the same from the shell:

```bash
. ~/opensandbox/env
osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config set connection.api_key "$OPEN_SANDBOX_API_KEY"
osb sandbox create --image python:3.12-slim --timeout 30m -o json
osb sandbox list
```

## Use it from your computer

The API is at `https://my-opensandbox.exe.xyz:8080/`, private like every
port but 8000. A script on your computer, or on a server, gets in with
two things: a VM token, which gets it through exe.dev's proxy, and
OpenSandbox's API key, which the server checks.

On your computer, make a token that only opens this VM, and fetch the API
key:

```bash
export EXE_VM_TOKEN=$(ssh exe.dev ssh-key generate-api-key --vm=my-opensandbox \
  --label=opensandbox-sdk --exp=90d --json | jq -r .token)
export $(ssh my-opensandbox.exe.xyz cat opensandbox/env)
export OPEN_SANDBOX_DOMAIN=https://my-opensandbox.exe.xyz:8080
```

Then run the same script here, with [uv](https://docs.astral.sh/uv/):

```bash
curl -fsSLO https://exe.dev/deploy/opensandbox/hello.py
uv run --with opensandbox==1.2.1 hello.py
```

In your own code, it's the `ConnectionConfig` that matters:

```python
config = ConnectionConfig(
    domain="https://my-opensandbox.exe.xyz:8080",
    protocol="https",
    api_key=os.environ["OPEN_SANDBOX_API_KEY"],
    headers={"X-Exedev-Authorization": "Bearer " + os.environ["EXE_VM_TOKEN"]},
)
```

The SDK sends `headers` to the API and to each sandbox, which it reaches
directly at `https://my-opensandbox.exe.xyz:<port>` (a port from
4000-4999): the proxy checks the token on both and strips it before the
request reaches the VM. Without the token, the proxy answers 401;
without the API key, the server does.

> [!TIP]
> Keep the token and the API key in your secrets manager, not in code.
> List tokens with `ssh exe.dev ssh-key list` and remove one with
> `ssh exe.dev ssh-key remove <fingerprint>`.

## Open a desktop in a sandbox

OpenSandbox's `opensandbox/desktop` image has an XFCE desktop and noVNC,
for agents that click through apps or for watching them. The setup pulled
it. On the VM:

```bash
cd ~/opensandbox
curl -fsSLO https://exe.dev/deploy/opensandbox/desktop.py
./py desktop.py
```

```text
sandbox 0f1c…, deleted in 30 minutes
open https://my-opensandbox.exe.xyz:4135/proxy/6080/vnc.html?path=proxy/6080&autoconnect=1&resize=scale
VNC password: opensandbox
```

Open the link, sign in to exe.dev if asked, and type the VNC password.
[desktop.py](https://exe.dev/deploy/opensandbox/desktop.py) starts Xvfb,
XFCE, x11vnc and websockify in the sandbox, and asks the server for port
6080's endpoint: execd forwards it, and exe.dev's proxy adds HTTPS and the
login, WebSockets included.

<figure>
<img src="https://exe.dev/deploy/opensandbox/desktop.png" alt="An XFCE desktop from an OpenSandbox sandbox in a browser tab, with a terminal showing the sandbox's kernel, CPUs, memory and the OpenSandbox tools in /opt/opensandbox" width="1280" height="800" loading="lazy">
<figcaption>A desktop sandbox through noVNC: same kernel as the VM, its own processes and files.</figcaption>
</figure>

Set `VNC_PASSWORD` and `DESKTOP_MINUTES` to change the password and how
long the sandbox lives. Anyone you share the VM with can open the link
too. The image has no web browser; for a desktop with Chrome that an
agent drives, see [computer use](/deploy/computer-use).

## Let an agent use it

Claude Code on the VM can create sandboxes and run code in them through
[OpenSandbox's MCP server](https://open-sandbox.ai/sdks/mcp), which the
setup installed with a wrapper, `~/opensandbox/mcp`, that hands it the API
key. On the VM, connect Claude Code to the LLM integration and add the MCP
server:

```bash
exeuntu configure claude
claude mcp add opensandbox --scope user -- ~/opensandbox/mcp
claude mcp list
```

`opensandbox: /home/exedev/opensandbox/mcp - ✔ Connected` means it's
ready. Then ask for something that needs a sandbox:

```bash
claude -p 'Create an OpenSandbox sandbox from python:3.12-slim, run python --version in it, then kill it.' \
  --allowedTools mcp__opensandbox
```

Claude creates the sandbox, runs the command, reports `Python 3.12.16`,
and kills it. Codex works the same way:

```bash
exeuntu configure codex
codex mcp add opensandbox -- ~/opensandbox/mcp
codex exec 'Use the opensandbox MCP tools: create a sandbox from python:3.12-slim, run python --version in it, then kill it.'
```

Code inside a sandbox can't reach the VM's integrations, the LLM
integration included: sandboxes run code you didn't write, and the
integrations act as you. To let sandboxes call models anyway, set
`INTEGRATIONS=allow` in `~/opensandbox/firewall.sh`, run
`sudo systemctl restart opensandbox`, and give the sandbox the gateway's
address; OpenAI's and Anthropic's SDKs pick these up:

```python
sandbox = await Sandbox.create(
    "python:3.12-slim", connection_config=config,
    env={"ANTHROPIC_BASE_URL": "https://llm.int.exe.xyz", "ANTHROPIC_API_KEY": "exe.dev",
         "OPENAI_BASE_URL": "https://llm.int.exe.xyz/v1", "OPENAI_API_KEY": "exe.dev"},
)
```

That opens every integration on the VM to every sandbox, so attach only
the ones sandboxes may use.

## Limit where a sandbox connects

A sandbox reaches the internet by default. Pass a network policy and it
reaches only what you allow, enforced by OpenSandbox's egress sidecar
(DNS filtering plus nftables rules):

```python
from opensandbox.models.sandboxes import NetworkPolicy, NetworkRule

sandbox = await Sandbox.create(
    "python:3.12-slim", connection_config=config,
    network_policy=NetworkPolicy(
        default_action="deny",
        egress=[NetworkRule(action="allow", target="pypi.org")],
    ),
)
```

In that sandbox, `https://pypi.org/simple/` answers 200, `example.com`
doesn't resolve, and `https://1.1.1.1/` times out. A sandbox with a
policy starts in about three seconds instead of one, for the sidecar.
See [network security](https://open-sandbox.ai/guides/network-security)
for the rest: ports, wildcards, and changing a policy while the sandbox
runs.

## OpenSandbox or exe.dev sandboxes?

exe.dev has [sandboxes](/deploy/sandbox) of its own: each one a whole VM
with its own kernel, CPU and memory, billed by the second, that pauses
with its memory and resumes in seconds. They're created with
`ssh exe.dev new --sandbox` or the [Python](/deploy/python-sandboxes)
and [TypeScript](/deploy/typescript-sandboxes) SDKs. OpenSandbox can't
create them yet: its runtimes are Docker and Kubernetes, so here every
sandbox is a container on one VM.

Use OpenSandbox on a VM when:

- your code or agent framework already speaks OpenSandbox (its SDKs, MCP
  server, or an integration such as Google ADK or Pydantic AI);
- you want many small, short-lived sandboxes from any container image at
  no cost beyond one VM;
- you need its per-sandbox network policies or its desktop and browser
  images.

Use exe.dev sandboxes directly when:

- the code is untrusted enough that a shared kernel worries you;
- one sandbox needs more CPU or memory than a VM has to spare, or many
  need to run at once;
- a sandbox should pause for hours and come back with its processes
  running, at no cost while paused;
- you'd rather not run a server at all.

## The nuts and bolts

Deploy sets all this up. The commands are here to do it by hand, and for
later.

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Set up by hand</summary>

On your computer, create a VM and connect. Pick any free name; if you've
already clicked Deploy or have a VM, skip the first command and use its
name:

```bash
ssh exe.dev new --name=my-opensandbox
ssh my-opensandbox.exe.xyz
```

On the VM, read [setup.sh](https://exe.dev/deploy/opensandbox/setup.sh),
then run it:

```bash
curl -fsSL https://exe.dev/deploy/opensandbox/setup.sh | bash
```

It takes about a minute, most of it pulling images. It:

- turns off container-to-container traffic on Docker's bridge
  (`"icc": false` in `/etc/docker/daemon.json`) and starts Docker at boot;
- installs `opensandbox-server`, `opensandbox-cli` (`osb`) and
  `opensandbox-mcp` 1.2.1 from PyPI with `uv tool`;
- makes an API key in `~/opensandbox/env`, mode 600;
- writes `~/.sandbox.toml`: the Docker runtime in bridge mode, sandbox
  ports 4000-4999 (inside the range exe.dev's proxy forwards), endpoints
  as `my-opensandbox.exe.xyz`, dropped capabilities, and the 1.2.1 execd
  and egress images;
- writes `~/opensandbox/firewall.sh`, which keeps sandboxes away from
  the API, from each other's ports, and from the VM's integrations;
- writes the `opensandbox` systemd service, which runs the firewall,
  then the server, at boot;
- makes `~/opensandbox/.venv` with the Python SDK, `./py` to run scripts
  with it, and `./mcp`, the MCP server for agents on the VM;
- pulls the execd, egress, `python:3.12-slim` and desktop images, about
  2 GB.

It ends with `active`, the server's version, and the API's address. To
check it again later:

```bash
systemctl is-active opensandbox
curl -s localhost:8080/health
```

`active` and `{"status":"healthy"}` mean it's up. The API's own docs are
at `https://my-opensandbox.exe.xyz:8080/docs`. Running the script again
is safe: it keeps the API key and the `INTEGRATIONS` setting, and
restarts the server, which leaves running sandboxes alone.

</details>

<details id="back-up-and-restore" class="dp-details">
<summary>Back up and restore</summary>

Sandboxes are meant to be thrown away, so there's little to keep: the
API key, the config, and the server's database of sandboxes. On your
computer:

```bash
ssh my-opensandbox.exe.xyz 'tar czf - opensandbox/env opensandbox/firewall.sh .sandbox.toml .opensandbox' \
  > opensandbox-backup.tgz
```

To restore on a new VM, run the setup script first, then unpack the
backup over it and restart:

```bash
ssh my-opensandbox.exe.xyz 'tar xzf - && sudo systemctl restart opensandbox' < opensandbox-backup.tgz
```

If the new VM has another name, point the sandbox endpoints at it, on
the VM:

```bash
sed -i "s/^eip = .*/eip = \"$(hostname).exe.xyz\"/" ~/.sandbox.toml
sudo systemctl restart opensandbox
```

Clients keep working with the same API key, at the new VM's address.

</details>

<details id="update" class="dp-details">
<summary>Update</summary>

The script pins OpenSandbox 1.2.1 and its matching execd and egress
images. For a newer release, check the
[releases](https://github.com/opensandbox-group/OpenSandbox/releases),
then download the script, set `VERSION=` at the top to the new release,
and run it, on the VM:

```bash
curl -fsSLO https://exe.dev/deploy/opensandbox/setup.sh
nano setup.sh    # VERSION=1.2.1 -> the new version
bash setup.sh
```

Sandboxes that are running keep their old execd; new ones get the new
one. Update the SDK in your own projects to the same version.

</details>

<details id="troubleshooting" class="dp-details">
<summary>Troubleshooting</summary>

- **401 from `my-opensandbox.exe.xyz`, with an exe.dev page**: the
  proxy didn't get a valid VM token. Check `X-Exedev-Authorization` in
  `headers`, and that the token isn't expired.
- **401 `MISSING_API_KEY` or `INVALID_API_KEY`**: the token got through,
  the API key didn't. Compare with `cat ~/opensandbox/env` on the VM.
- **The server doesn't start**: `journalctl -u opensandbox -n 50`. A
  typo in `~/.sandbox.toml` shows up there.
- **A sandbox is stuck in `Pending` or fails to start**: usually a slow
  or failed image pull. `docker pull <image>` on the VM shows why; the
  server log has the container's error.
- **No ports left**: each sandbox takes one or two ports from 4000-4999.
  Delete old sandboxes with `osb sandbox kill <id>`, or give them a
  `timeout` so they delete themselves.
- **Code in a sandbox can't reach a model or GitHub**: that's the
  firewall; see [Let an agent use it](#let-an-agent-use-it).

</details>

## Frequently asked questions

### How much does it cost to self-host OpenSandbox on exe.dev?

OpenSandbox is free and open source (Apache-2.0). Its sandboxes are containers on your VM, so they cost nothing extra: you pay for the VM as part of your exe.dev plan. Model calls through the [LLM integration](/docs/integrations-llm) are billed to your exe.dev account.

### Who can reach the API and the sandboxes?

You, people you share the VM with, and programs holding a [VM token](/docs/https-tokens-for-vms). Ports 8080 and 4000-4999 go through exe.dev's [HTTPS proxy](/docs/proxy), which asks for an exe.dev login, and ports other than the main one are never public. The API also wants OpenSandbox's own API key.

### How isolated is a sandbox?

Each sandbox is a Docker container with dropped capabilities, no new privileges and a process limit, sharing the VM's kernel. The setup script also stops sandboxes from calling the API, each other, or the VM's exe.dev integrations. The VM is the hard boundary: nothing in a sandbox reaches your other VMs or your laptop. For a VM per sandbox, use [exe.dev sandboxes](/deploy/sandbox) directly.

### How many sandboxes fit on one VM?

An idle sandbox uses a few megabytes of memory, so what they run decides the number. Each gets at most 2 GiB of memory unless you set `resource` in `Sandbox.create`; give the VM more CPU and memory with a bigger plan. The port range in `~/.sandbox.toml` allows a few hundred at a time.

### Does OpenSandbox's Kubernetes runtime work here?

This page uses the Docker runtime, which is what a single machine needs. The Kubernetes runtime wants a cluster; a VM could run a small one with k3s, but you'd be running Kubernetes for the sake of it.

### What happens to sandboxes when the VM reboots?

The server and Docker come back on their own, and new sandboxes work at once. Sandboxes that were running are lost: their containers stop, and the API lists them as `Failed` until you delete them. Keep anything that must last on the VM, not in a sandbox.

### Can I use the E2B SDK with it?

Not today. OpenSandbox has its own SDKs (Python, TypeScript, Java, Go, C#), CLI and MCP server; E2B compatibility is a proposal upstream. Code written for E2B needs porting, which is mostly renaming.


## Related

- [Sandboxes on exe.dev](https://exe.dev/deploy/sandbox.md): A VM with its own CPU and memory, billed by the second while it runs.
- [Create sandboxes from Python](https://exe.dev/deploy/python-sandboxes.md): Full VMs as sandboxes. A with block creates one, runs your code, and deletes it.
- [Run AI-generated code safely](https://exe.dev/deploy/code-interpreter.md): The model writes Python. A VM of its own runs it, keeps its variables, draws the charts.
- [A Linux desktop in your browser](https://exe.dev/deploy/linux-desktop.md): Xfce, Chrome, and coding agents on a VM you open in a browser tab.
- [A desktop and browser for your AI agent](https://exe.dev/deploy/computer-use.md): A Linux desktop your agent drives and you can watch, from any browser.
- [Use exe.dev as a remote Docker host](https://exe.dev/deploy/docker-host.md): Keep the docker CLI. Send the builds, the containers, and the fan noise to a VM.
