devboxes

# 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 CNA...

# Devboxes Skill for OpenClaw

Spin up a full development environment in seconds — just by asking your agent.

Each devbox is an isolated container with **VSCode in your browser**, a **visual desktop via VNC**, **headless Chromium** for testing, and **up to 5 routable app ports** — all accessible via clean URLs on your domain. No SSH tunnels, no port forwarding, no "works on my machine".

Need to prototype something? Clone a repo and start coding? Debug a frontend on a real browser? Spin up a devbox. It self-registers with Traefik, assigns itself a unique ID, and hands you ready-to-use URLs. When you're done, tear it down. Zero cleanup.

Whether you're working from your laptop, a tablet, or someone else's machine — your full dev environment is one URL away.

## Features

- **Self-registering containers** — auto-assigns ID, configures routing, builds `APP_URL_*` env vars
- **Flexible routing** — choose between Traefik (self-managed) or Cloudflare Tunnels (zero open ports)
- **VSCode Web** — browser-based IDE on port 8000
- **noVNC** — visual desktop access on port 8002
- **Chromium CDP** — headless browser automation on port 9222
- **5 app slots** — routed via Traefik with configurable tags (e.g. `api`, `app`, `dashboard`)
- **Project setup scripts** — `.openclaw/setup.sh` convention for automated repo setup
- **nvm** — Node version management, reads `.nvmrc` automatically

## Architecture

```
+-----------------------------------------------------------+
|  Devbox Container (ghcr.io/adshrc/openclaw-devbox:latest) |
|                                                           |
|  +----------+  +----------+  +-------------------+        |
|  |  VSCode  |  |  noVNC   |  |  Chromium (CDP)   |        |
|  |  :8000   |  |  :8002   |  |  :9222            |        |
|  +----------+  +----------+  +-------------------+        |
|                                                           |
|       App 1 :8003   App 2 :8004   App 3 :8005             |
|       App 4 :8006   App...