Documentation Index
Fetch the complete documentation index at: https://mintlify.com/opensandbox-group/OpenSandbox/llms.txt
Use this file to discover all available pages before exploring further.
The All-in-One (AIO) Sandbox bundles a complete agent runtime — shell, file system, and browser — into a single container image. OpenSandbox creates and manages the sandbox lifecycle while the agent-sandbox client SDK connects to the running instance to issue shell commands, read files, and take browser screenshots, all through a unified HTTP API.
Prerequisites
Start a Docker daemon
The server defaults to runtime.type = "docker" and must reach a running Docker daemon.
- Docker Desktop: ensure it is running, then verify with
docker version.
- Colima (macOS): run
colima start, then export the socket before starting the server:
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
Pull the AIO image
docker pull ghcr.io/agent-infra/sandbox:latest
Start the OpenSandbox server
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server
opensandbox-server runs in the foreground. Clone this repository and open a new terminal tab to run the example code below.
Install Python dependencies
uv pip install opensandbox agent-sandbox==0.0.18
Full Example
The script creates an AIO sandbox via SandboxSync.create(), waits until the internal process is healthy, then uses the agent-sandbox client to list files, read .bashrc, capture a browser screenshot, and save it locally.
import time
from datetime import timedelta
import requests
from agent_sandbox import Sandbox as AioSandboxClient
from opensandbox import SandboxSync
from opensandbox.config import ConnectionConfigSync
def check_aio_process(sbx: SandboxSync) -> bool:
"""
Health check: poll the AIO process at /v1/shell/sessions until it returns 200.
Returns:
True when ready
False on timeout or any exception
"""
try:
endpoint = sbx.get_endpoint(8080)
start = time.perf_counter()
url = f"http://{endpoint.endpoint}/v1/shell/sessions"
for _ in range(150): # max ~30s
try:
resp = requests.get(url, timeout=1)
if resp.status_code == 200:
elapsed = time.perf_counter() - start
print(f"[check] sandbox ready after {elapsed:.1f}s")
return True
except Exception:
pass
time.sleep(0.2)
return False
except Exception as exc:
print(f"[check] failed: {exc}")
return False
def main() -> None:
server = "http://localhost:8080"
image = "ghcr.io/agent-infra/sandbox:latest"
timeout_seconds = 300
print(f"Creating AIO sandbox with image={image} on OpenSandbox server {server}...")
sandbox = SandboxSync.create(
image=image,
timeout=timedelta(seconds=timeout_seconds),
metadata={"example": "aio-sandbox"},
entrypoint=["/opt/gem/run.sh"],
connection_config=ConnectionConfigSync(domain=server),
health_check=check_aio_process,
)
with sandbox:
endpoint = sandbox.get_endpoint(8080)
print(f"AIO portal endpoint: {endpoint.endpoint}")
client = AioSandboxClient(base_url=f"http://{endpoint.endpoint}")
home_dir = client.sandbox.get_context().home_dir
result = client.shell.exec_command(command="ls -la", timeout=10)
print(result.data.output)
content = client.file.read_file(file=f"{home_dir}/.bashrc")
print(content.data.content)
screenshot_path = "sandbox_screenshot.png"
with open(screenshot_path, "wb") as f:
for chunk in client.browser.screenshot():
f.write(chunk)
print(f"Screenshot saved to {screenshot_path}")
# kill sandbox finally
sandbox.kill()
if __name__ == "__main__":
main()
uv run python examples/aio-sandbox/main.py
Expected Output
Creating AIO sandbox with image=ghcr.io/agent-infra/sandbox:latest on OpenSandbox server http://localhost:8080...
[check] sandbox ready after 7.1s
AIO portal endpoint: 127.0.0.1:56123
...
Screenshot saved to sandbox_screenshot.png
If you see FileNotFoundError from docker/transport/unixconn.py, the Docker unix socket is missing or the Docker daemon is not running.
More Examples
For additional AIO Sandbox workflows (multi-tab browsing, file uploads, terminal multiplexing), see the agent-infra/sandbox examples.
References
