OpenClaw Docker Sandbox for Ollama qwen2.5:32b

This project runs the OpenClaw TUI on your host machine while isolating the agent's code execution inside a Docker Sandbox microVM. The agent connects back to the host Gateway over an HTTP proxy bridge through the sandbox proxy.

The default model is qwen2.5:32b.

Architecture

Host:    TUI -> Gateway:18789 -> Ollama:11434
                    ^
                    | WebSocket (tunneled through proxy)
                    |
Sandbox: openclaw node -> gateway-bridge:18789 -> proxy:3128 -> host:18789

• The host runs the OpenClaw Gateway (port 18789) and TUI, connecting directly to Ollama at 127.0.0.1:11434.
• The sandbox runs an OpenClaw Node that pairs with the host Gateway. An HTTP proxy bridge inside the sandbox forwards HTTP and WebSocket traffic through the Docker proxy to the host Gateway.
• Ollama is accessed directly by the host Gateway — no proxy bridge needed.

Prerequisites

• Docker Desktop 4.58+ installed.
• Ollama installed and running on the host (ollama serve).
• The desired model pulled into Ollama (e.g. ollama pull qwen2.5:32b).
• OpenClaw CLI installed on the host (~/.openclaw/openclaw.json configured with Gateway on port 18789).

Quick start

From the repository root:

make setup
make run

If you already have the warm template baked:

make run

For a noninteractive validation run:

make doctor

Or directly:

./scripts/run-openclaw.sh /absolute/path/to/your/project

If you want a different model:

OPENCLAW_MODEL=qwen2.5-coder:32b make run

What happens on make run

1. Verify the OpenClaw CLI is on the host.
2. Verify Ollama is running and the model is available.
3. Start the host Gateway if it is not already running.
4. Create or reuse the Docker sandbox, configure proxy policy, and provision it.
5. Launch start-node.sh inside the sandbox (background, no TTY). This starts the gateway bridge and runs openclaw node run.
6. Auto-approve the node pairing request if not already paired.
7. Run openclaw tui --deliver on the host (foreground, blocks).
8. On exit: stop the sandbox and kill the host Gateway if this script started it.

Common operations

make setup          # Full setup: checks, template, doctor
make run            # Launch host TUI + sandbox agent
make doctor         # Validate Ollama + Gateway + sandbox + bridge connectivity
make shell          # Interactive shell inside sandbox
make logs           # Tail host Gateway + sandbox logs
make stop           # Stop sandbox
make clean          # Remove sandbox
make template       # Bake warm template
make template-clean # Remove warm template

What gets created

• A sandbox named openclaw-<workspace>-<hash> unless you override OPENCLAW_SANDBOX_NAME.
• An OpenClaw install inside the sandbox at /opt/openclaw.
• A gateway bridge at /usr/local/lib/openclaw-docker/gateway-bridge.js inside the sandbox.
• Host Gateway logs at ~/.openclaw/logs/gateway-host.log.

Useful environment overrides

• OPENCLAW_MODEL: choose a different Ollama model.
• OPENCLAW_GATEWAY_PORT: change the Gateway port (default 18789).
• OPENCLAW_SANDBOX_NAME: choose the sandbox name.
• OLLAMA_HOST_PORT: change the host port where Ollama is listening (default 11434).
• OPENCLAW_TEMPLATE_TAG: change the warm template image tag.
• OPENCLAW_VERSION: pin the OpenClaw CLI version during sandbox provisioning.
• OPENCLAW_KEEP_SANDBOX_RUNNING=1: leave the sandbox running after the TUI exits.

Node pairing flow

1. The sandbox Node starts and connects to the host Gateway (authenticated via OPENCLAW_GATEWAY_TOKEN).
2. The host script waits up to 60s for either the node to connect (existing pairing) or a pending pairing request.
3. If a pending request appears, it extracts the requestId and runs openclaw nodes approve <id>.
4. The Node is paired; credentials are stored in the sandbox at ~/.openclaw/node.json.
5. On subsequent runs with the same sandbox, the node reconnects automatically using its stored credentials.

Troubleshooting

OpenClaw CLI not found

Install the OpenClaw CLI on the host: https://openclaw.ai/install-cli.sh

Host Gateway not starting

• Check ~/.openclaw/logs/gateway-host.log.
• Verify ~/.openclaw/openclaw.json exists and configures the Gateway on port 18789.
• Try manually: openclaw gateway and check openclaw gateway call health.

Node not pairing or connecting

• Check sandbox logs: make logs.
• Verify the gateway bridge can reach the host: make doctor.
• Ensure the proxy policy allows localhost:18789: the scripts do this automatically.
• If you ran make clean and recreated the sandbox, the old node entry may be stale on the gateway. The new sandbox will send a fresh pairing request that gets auto-approved.
• To manually clear stale nodes: check openclaw nodes status and remove disconnected entries.

Ollama not reachable

• Confirm Ollama is running: ollama serve.
• Confirm curl http://127.0.0.1:11434/api/tags works on the host.
• If you use a non-default port, set OLLAMA_HOST_PORT accordingly.

Model not found

• Pull the model on the host: ollama pull qwen2.5:32b.

Docker Desktop or sandbox plugin missing

• Install Docker Desktop 4.58+.
• Verify with docker desktop version and docker sandbox version.