devboxes
Manage development environment containers (devboxes) with web-accessible VSCode, VNC, and app routing via Traefik or Cloudflare Tunnels. Use when the user asks to create, start, stop, list, or manage devboxes/dev environments, spin up a development container, set up a coding sandbox, or configure the devbox infrastructure for the first time (onboarding).
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/adshrc/devboxesDevbox 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:
- Reads and increments
/home/node/.openclaw/.devbox-counterbefore spawning - Includes the
DEVBOX_IDin the task, instructing the devbox agent to rundevbox-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):
- Builds
APP_URL_1..5,VSCODE_URL,NOVNC_URLfrom tags + domain + ID - Writes
/etc/devbox.envand/etc/profile.d/devbox.sh(available in all shells) - Routes based on
ROUTING_MODE:traefik(default): Writes Traefik config to/traefik/devbox-{id}.ymlcloudflared: Generates cloudflared ingress config, registers DNS CNAME records via CF API, startscloudflared 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:
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-adshrc-devboxes": {
"enabled": true,
"auto_update": true
}
}
}