Sandbox Guide

xbot supports three sandbox modes, managed by a SandboxRouter that selects the appropriate backend on a per-user basis:

All three modes can coexist simultaneously. The router decides which backend to use for each user according to the following priority:

1. If the user has set active_runner to the built-in Docker name (__docker__) → Docker
2. If the user has a connected remote runner matching their active_runner name → Remote
3. If the user has any connected remote runner → Remote
4. Fallback → Docker (if enabled), then None

Note: Web users (web-* IDs) are blocked from all sandbox access unless WEB_USER_SERVER_RUNNER=true is set. They must connect their own remote runner.

Docker mode provides per-user container isolation on the server. Each user gets their own container with a persistent filesystem.

# Install Docker
sudo apt-get update && sudo apt-get install -y docker.io
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER  # re-login required

# .env file

# Sandbox mode: none / docker
SANDBOX_MODE=docker

# Docker image (optional, default: ubuntu:22.04)
SANDBOX_DOCKER_IMAGE=ubuntu:22.04

# Host working directory (optional)
HOST_WORK_DIR=/tmp/xbot-work

# Container idle timeout before commit (optional, in minutes)
SANDBOX_IDLE_TIMEOUT_MINUTES=30

Each user’s container follows this lifecycle:

┌─────────────────────────────────────────────────────────────┐
│  1. First use                                                │
│     Base image (e.g. ubuntu:22.04)                           │
│              │                                                │
│              ▼                                                │
│     Create container xbot-{user_id}                           │
│              │                                                │
│              ▼                                                │
│     User operations (apt install, pip install, etc.)         │
│                                                              │
│  2. On close / idle timeout                                  │
│     docker export | docker import → xbot-{user_id}:latest    │
│     stop + rm container                                       │
│                                                              │
│  3. Next use                                                  │
│     Detect user image xbot-{user_id}:latest                   │
│              │                                                │
│              ▼                                                │
│     Create new container from user image — env fully restored│
└─────────────────────────────────────────────────────────────┘

The server uses docker export | docker import (piped, no intermediate tar file) to persist the container’s filesystem as a user-specific image:

• All filesystem changes are saved: system packages (apt-get install), language packages (pip install, npm install -g), compiled software, config file edits
• Transparent restore: the next container is created from the committed image automatically
• Startup cleanup: stale export temp files and dangling Docker images are pruned on server start

# Remove a specific user's container and image
docker rm -f xbot-{user_id}
docker rmi xbot-{user_id}:latest

# List all xbot containers
docker ps -a --filter "name=xbot-"

# Bulk cleanup
docker rm -f $(docker ps -aq --filter "name=xbot-")
docker rmi $(docker images --format '{{.Repository}}:{{.Tag}}' | grep '^xbot-')

# Check Docker service
sudo systemctl status docker

# Check permissions
docker ps

# View container logs
docker logs xbot-{user_id}

# List images
docker images

Remote runner mode lets users connect their own machine as an execution environment via WebSocket. The server manages runners and routes commands to them.

┌──────────────┐         WebSocket          ┌──────────────────┐
│  xbot server │◄──────────────────────────►│  xbot-runner     │
│              │   /ws/{user_id}            │  (user's machine)│
│  RemoteSandbox                            │                  │
│  (router)    │  commands, file ops, LLM   │  native / docker │
└──────────────┘                            └──────────────────┘

The xbot-runner binary connects to the server’s WebSocket endpoint and executes commands locally or inside a local Docker container.

Each xbot-runner instance can operate in one of two modes:

1. Create a runner via the runner management API (see below). This generates a token and a connect command.
2. Run the connect command on the user’s machine:

   ./xbot-runner --server <server-url>/ws/<user-id> --token <token>
   

3. The runner auto-detects its user ID from the server URL path, or set it explicitly with --user-id.

Each user can register multiple runners with different names. The server tracks which runner is active per user via user_settings.active_runner. The SandboxRouter routes commands to the user’s active runner.

When a runner connects, the server automatically syncs global skills and agent definitions from the server to the runner’s workspace, ensuring the runner has the same tools available.

The server exposes these management functions (used by the web UI and agent tools):

When creating a runner, the returned command includes all necessary flags (mode, workspace, LLM config if specified).

The runner uses exponential backoff (1s → 60s max) with infinite retries on connection failure.

Runners can optionally serve as LLM proxies — when a runner has local LLM configuration, the server transparently forwards LLM API calls through the runner instead of calling the LLM provider directly.

1. A runner is created with LLM settings (--llm-provider, --llm-model, --llm-api-key, --llm-base-url), or LLM settings are configured later via the web UI.
2. When the runner connects, the server detects its LLM capability and stores the configuration.
3. When the agent processes a request for that user, injectProxyLLM checks if the user’s active runner has LLM configured.
4. If so, a ProxyLLM wrapper is injected into the agent’s LLM factory:
   • GenerateFunc: LLM generate requests are forwarded to the runner via WebSocket (LLMGenerate)
   • ListModelsFunc: Model listing is forwarded to the runner (LLMModels)
5. If the runner disconnects or has no LLM config, the proxy is cleared and the server’s own LLM is used.

• Users who want to use their own API keys without sharing them with the server
• Runners behind firewalls that can access private LLM endpoints
• Per-user LLM provider/model customization

• Cold start: First execution requires pulling the image and creating a container (~10–30 seconds)
• Hot execution: Once running, command execution has negligible overhead
• Export/import: Typically completes in 1–2 seconds (only filesystem diff layers)
• Resource usage: Each active user occupies one container; user images consume disk space (incremental storage)
• Stale cleanup: On server start, temp export files older than 10 minutes and dangling Docker images are automatically pruned