How to Self-Host OpenSandbox
7:07Video coming soonOpenSandbox gives AI agents isolated, throwaway environments (sandboxes) where they can run commands and manage files, locally with Docker or later on Kubernetes. In this guide you start the OpenSandbox server on your own machine, use the Python SDK to create a sandbox, run commands and code in it, write and read files, then use the osb command line tool and clean up.
Tested with OpenSandbox 1.2.1 (opensandbox-server, opensandbox SDK and opensandbox-cli from PyPI) on 2026-11-16.
Video: coming soon
Requirements
- Docker installed and running (required for local use). Docker CE is recommended over the snap package.
- Python 3.10 or newer, with
venvandpip. uv(the official way to start the server usesuvx): https://docs.astral.sh/uv/- Internet access the first time, to download the server and pull container images.
- No account and no API key.
Optional: pre-pull the sandbox image so the first sandbox starts quickly: docker pull python:3.12-slim.
How it works
Your script (Python SDK) or the osb CLI talks to the sandbox server on port 8080. The server asks Docker to start a container from the image you pick. A small helper inside the container runs your commands and file operations and sends the results back.
Step 1: Create the config
In a first terminal, write the example Docker configuration to ~/.sandbox.toml and look inside.
uvx opensandbox-server init-config ~/.sandbox.toml --example docker
grep -A3 '^\[server\]' ~/.sandbox.toml
grep -A2 '^\[runtime\]' ~/.sandbox.tomlExpected output: the server section shows host = "127.0.0.1" and port = 8080; the runtime section shows type = "docker".
Step 2: Start the server
uvx opensandbox-serverBecause no API key is set, the server asks you to confirm running without one. For a local test on your own machine, type YES (capitals) and press Enter. A few log lines later it reports that it is running on http://127.0.0.1:8080. Leave this terminal open.
(Non-interactive alternative from the docs: OPENSANDBOX_INSECURE_SERVER=YES uvx opensandbox-server.)
Step 3: The built-in API page
Open http://localhost:8080/docs in your browser. It lists every endpoint (create, list, renew, pause, delete...). Open List Sandboxes, click Try it out, then Execute. The response comes back right away with an empty list: no sandboxes yet.
Step 4: Install the Python SDK
In a second terminal, make a project folder and copy the three small scripts from this guide's sample-data/ folder into it (hello_sandbox.py, files_and_code.py, keep_alive.py). Then create a virtual environment and install the official SDK.
mkdir -p ~/sandbox-demo
cp sample-data/*.py ~/sandbox-demo/ # run this from this guide's folder
cd ~/sandbox-demo && ls
python3 -m venv .venv
source .venv/bin/activate
pip install opensandboxExpected output: pip ends with Successfully installed .... The scripts need no settings: the SDK talks to localhost:8080 by default.
Step 5: Your first script
cat hello_sandbox.pyIt creates a sandbox from the python:3.12-slim image, runs three commands inside it (system name, Python version, current user), and destroys the sandbox in a finally block so nothing is left running even if something fails.
Step 6: Create a sandbox and run commands
python hello_sandbox.pyExpected output (the ID and exact versions will differ):
Sandbox ready: <sandbox-id>
[sandbox] head -n 1 /etc/os-release -> PRETTY_NAME="Debian GNU/Linux ..."
[sandbox] python3 --version -> Python 3.12.x
[sandbox] whoami -> root
Sandbox destroyedThe system is Debian (the image, not your machine), and you are root only inside the sandbox. The server terminal logs each request.
Step 7: Write a file, run code, read the result
files_and_code.py holds a few lines of made-up Python as a text block (seven temperatures and a summary file). The script writes that code into a file inside the sandbox, runs it there, and reads the summary back.
python files_and_code.pyExpected output:
[sandbox] summary written
Days: 7
Warmest: 24 C
Average: 21.0 CStep 8: Keep a sandbox running
keep_alive.py creates a sandbox with a 15-minute timeout, prints its ID and closes only the local connection. Keep the ID in a variable and look at Docker:
cat keep_alive.py
SB=$(python keep_alive.py); echo $SB
docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Status}}"docker ps shows a real container running from the python:3.12-slim image. If you forget it, the timeout removes it (the default is 10 minutes).
Step 9: The command line tool (osb)
pip install opensandbox-cli
osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb sandbox list
osb command run $SB -o raw -- python -c "print(6 * 7)"
osb file write $SB /tmp/note.txt -c "hello from the CLI" -o json
osb file cat $SB /tmp/note.txt -o rawExpected: osb sandbox list shows your sandbox, the command prints 42, and file cat prints hello from the CLI.
Step 10: Clean up
osb sandbox kill $SB -o json
osb sandbox list
docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Status}}"The list is empty and docker ps no longer shows the sandbox container. Finally, go back to the server terminal and press Ctrl+C to stop the server.
Troubleshooting and tips
- Running without an API key is for local tests only. The docs say to always set
api_keyunder[server]in production; clients then send it in theOPEN-SANDBOX-API-KEYheader. Generate one withopenssl rand -hex 32and put it in place ofCHANGE_ME_long_random_string. - Sandboxes expire after 10 minutes by default: pass a
timeoutwhen creating them, or renew them. - On a cloud VM, if the sandbox health check times out, set
eipunder[server]in~/.sandbox.tomlto the public IP or hostname clients use, then restart the server. - If Docker came from a snap package and sandboxes fail to start, the troubleshooting guide suggests Docker CE instead.
- The first sandbox can be slow while Docker pulls images; pre-pull
python:3.12-slim. - To pin the tested versions:
uvx opensandbox-server@1.2.1,pip install opensandbox==1.2.1 opensandbox-cli==1.2.1. - Run only code you are allowed to run, on machines you control.
Limits and costs
- Free and open source; no account needed.
- It is the box, not the brain: no AI agent is included, you bring your own.
- You run and secure the server yourself.
- By default sandboxes are normal Docker containers; stronger isolation (gVisor, Kata, Firecracker) needs extra setup.
- Young project with frequent releases; 1.2.1 was released in November 2026.
Clean up
Covered in Step 10. To remove everything this guide created:
rm ~/.sandbox.toml
rm -rf ~/sandbox-demoOfficial links
- Docs and website: https://open-sandbox.ai
- Getting started: https://github.com/opensandbox-group/OpenSandbox#getting-started
- Server configuration: https://github.com/opensandbox-group/OpenSandbox/blob/main/docs/getting-started/configuration.md
- Python SDK: https://github.com/opensandbox-group/OpenSandbox/blob/main/sdks/sandbox/python/README.md
- CLI guide: https://github.com/opensandbox-group/OpenSandbox/blob/main/cli/README.md
- Troubleshooting: https://github.com/opensandbox-group/OpenSandbox/blob/main/server/TROUBLESHOOTING.md
- Source code: https://github.com/opensandbox-group/OpenSandbox
- Licence: Apache-2.0 (https://github.com/opensandbox-group/OpenSandbox/blob/main/LICENSE)
- Releases: https://github.com/opensandbox-group/OpenSandbox/releases
--- Not affiliated with or endorsed by the OpenSandbox authors. "OpenSandbox" is used only to describe the software.
Liked this guide?
Subscribe on YouTube so you don't miss the next tutorial.