devboxes

通过 Traefik 或 Cloudflare Tunnels 使用可通过 Web 访问的 VSCode、VNC 和应用程序路由来管理开发环境容器 (devboxes)。当用户要求创建、启动、停止、列出或管理 devbox/dev 环境、启动开发容器、设置编码沙箱或首次配置 devbox 基础设施（入门）时使用。

## 概述（中文）

通过 Traefik 或 Cloudflare Tunnels 使用可通过 Web 访问的 VSCode、VNC 和应用程序路由来管理开发环境容器 (devboxes)。当用户要求创建、启动、停止、列出或管理 devbox/dev 环境、启动开发容器、设置编码沙箱或首次配置 devbox 基础设施（入门）时使用。

## 原文

# Devbox Skill

Devboxes are OpenClaw sandbox containers running a custom image with VSCode Web, noVNC, Chromium (CDP), and up to 5 app ports routed via **Traefik** or **Cloudflare Tunnels**.

OpenClaw manages the full container lifecycle. The **main agent** assigns each devbox a sequential ID by maintaining a local counter file, then passes `DEVBOX_ID` to the subagent task. The devbox agent runs `devbox-init` as its first action, which builds URL env vars, writes env files, and sets up routing.

## File Locations

Resolve paths relative to this SKILL.md's parent directory.

Key files:

- `references/setup-script-guide.md` — conventions for project setup scripts (`.openclaw/setup.sh`)

## Architecture

- **Agent id:** `devbox` (configured in openclaw.json)
- **Sandbox mode:** `all` / `scope: session` — one container per session
- **Image:** `ghcr.io/adshrc/openclaw-devbox:latest` (pulled from GHCR)
- **Network:** `traefik` (for Traefik routing) or default Docker network (for Cloudflare Tunnel routing)
- **Browser:** `sandbox.browser.enabled: true`, CDP on port 9222

### ID Assignment

The **main agent** manages the devbox counter:

1. Reads and increments `/home/node/.openclaw/.devbox-counter` before spawning
2. Includes the `DEVBOX_ID` in the task, instructing the devbox agent to run `devbox-init {id}` as its very first action

### Two-Phase Startup

**Phase 1 — Entrypoint** (runs automatically at container start):

- Starts core services: Xvfb, Chromium (CDP), VNC, VSCode Web
- Does NOT require `DEVBOX_ID` — services are available immediately

**Phase 2 — `devbox-init <id>`** (run by the sub-agent/devbox agent):

1. Builds `APP_URL_1..5`, `VSCODE_URL`, `NOVNC_URL` from tags + domain + ID
2. Writes `/etc/devbox.env` and `/etc/profile.d/devbox.sh` (available in all shells)
3. Routes based on `ROUTING_MODE`:
   - **`traefik`** (default): Writes Traefik config to `/traefik/devbox-{id}.yml`
   - **`cloudflared`**: Generates cloudflared ingress config, registers DNS CNAME records via CF API, starts `cloudflared tunnel run`

The `devbox-init` script is installed at `/usr/local/bin/devbox-init` in the Docker image.

### Bind Mounts (configured in openclaw.json)

| Agent path                     | Devbox container path | Purpose                                       |
| ------------------------------ | --------------------- | --------------------------------------------- |
| `/home/node/.openclaw/traefik` | `/traefik`            | Route configs (only if using Traefik routing) |

**Important:** Due to OpenClaw Security measures, all user capabilites are dropped by default. So even root (in the devbox) has no write access to bind mounts, and can only read from them. The only solution currently is `chmod 777` on the host path that is mapped to `/home/node/.openclaw/traefik`.

### Known Paths

These paths are always the same inside the OpenClaw container:

- **OpenClaw data:** `/home/node/.openclaw`
- **Traefik dynamic config:** `/home/node/.openclaw/traefik` (must be mounted into the OpenClaw container; only if using Traefik routing)

## Onboarding Flow

**Important:** After this skill is installed, the next step MUST be this onboarding flow. The user CANNOT use the devboxes skill until the onboarding flow is completed and the infrastructure is set up.

**Important:** This runs on the MAIN agent, NOT in a sandbox. The main agent has access to `exec`, `gateway`, and the file system.

When the user asks to set up the devbox skill, do the following:

### Step 1: Verify Docker Access

Verify that you have access to the Docker socket and Docker binary:

```bash
which docker
docker version
```

If not, abort here and tell the user they need to run the OpenClaw container with:

```
-v /usr/bin/docker:/usr/bin/docker:ro
-v /var/run/docker.sock:/var/run/docker.sock
```

and that they need to set `chmod 666 /var/run/docker.sock` manually on the host, so that the OpenClaw container can work with it.

The OpenClaw container needs to be restarted then. After that, they can ask to set up the devbox skill again.

### Step 2: Gather configuration info

Ask the user for:

- **Routing mode**: Traefik or Cloudflare Tunnel?
- **Domain**: with wildcard A-Record pointing to the server (e.g. `*.example.com`)
- **GitHub token** (optional): for cloning private repos inside devboxes

If **Cloudflare Tunnel** is chosen, also ask for:

- **Cloudflare API token**: must have permissions for the zone (DNS edit + Tunnel edit)

### Step 3: Validate the Host Mapping Path (ONLY if using Traefik routing, skip otherwise!)

Find out what the host path/mapping is for `/home/node/.openclaw` inside the container:

```bash
# Returns the host path that is mapped to /home/node/.openclaw inside the container
docker inspect --format='{{range .Mounts}}{{if eq .Destination "/home/node/.openclaw"}}{{.Source}}{{end}}{{end}}' $(hostname)
```

Store the value as `HOST_OPENCLAW_PATH`. If `HOST_OPENCLAW_PATH` is a "system directory", OpenClaw will not be able to spawn a devbox.

System directories are: /etc, /private/etc, /proc, /sys, /dev, /root, /boot, /run, /var/run, /private/var/run, /var/run/docker.sock, /private/var/run/docker.sock and /run/docker.sock.

If the `HOST_OPENCLAW_PATH` is such a "system directory", abort here and tell the user they need to change their OpenClaw container setup to use a host path for OpenClaw data that is not a system directory. For example, they can create a directory like `/home/openclaw` or `/opt/openclaw` on the host.

### Step 4: Verify Routing prerequisites

#### If routing mode is Traefik:

Check that /home/node/.openclaw/traefik is mounted:

```bash
ls /home/node/.openclaw/traefik
```

If `/home/node/.openclaw/traefik` doesn't exist, abort here and tell the user they need to add e.g. `-v path_to_traefik:/home/node/.openclaw/traefik` to their OpenClaw container and restart it. Remind the user that they cannot use system directories for the host path (OpenClaw Sandboxes restriction). After that, a container restart is needed, and then they can ask to set up the devbox skill again.

#### If routing mode is Cloudflare Tunnel:

Validate the CF API token and domain:

```bash
# 1. Get zone ID for the domain (extract root domain from the provided domain)
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=${ROOT_DOMAIN}" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" | jq .

# 2. Get account ID from the zone response
# account_id = .result[0].account.id
# zone_id = .result[0].id
```

Then create the tunnel:

```bash
# 4. Create a named tunnel
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/cfd_tunnel" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "devboxes@'"$(hostname)"'", "config_src": "local", "tunnel_secret": "'$(openssl rand -base64 32)'"}' | jq .

# Extract tunnel_id and tunnel_token from the response
# tunnel_id = .result.id
# tunnel_token = .result.token
```

Store the values: `CF_API_TOKEN`, `CF_ZONE_ID`, `CF_ACCOUNT_ID`, `CF_TUNNEL_ID`, `CF_TUNNEL_TOKEN`.

### Step 5: Create counter file

```bash
echo "0" > /home/node/.openclaw/.devbox-counter
```

**Important:** The counter file is managed by the main agent only. The counter CANNOT be reset, or decremented, only increment is allowed!

### Step 6: Configure OpenClaw

First, check the current agents config:

```bash
node /app/openclaw.mjs config get agents
```

Then, decide what needs to be adjusted based on the existing config:

#### Main Agent

If there is an agent with `default: true`, note its index and add `subagents.allowAgents` to it:

```bash
node /app/openclaw.mjs config set agents.list[{index}].subagents.allowAgents '["devbox"]' --json
```

then (if needed), set sandbox mode to `off` (since the main agent doesn't need a sandbox):

```