You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 78effef
Browse filesBrowse the repository at this point in the historyBrowse files
The OpenClaw container needs access to the Docker daemon on the host to manage devbox containers. Start your OpenClaw container with these additional flags:
49
+
50
+
```bash
51
+
-v /var/run/docker.sock:/var/run/docker.sock
52
+
-v /usr/bin/docker:/usr/bin/docker:ro
53
+
```
54
+
55
+
On the host, set the correct permissions to make the Docker socket accessible:
56
+
57
+
```bash
58
+
chmod 666 /var/run/docker.sock
59
+
```
60
+
61
+
> **Note:** This must be done on the host machine before starting the OpenClaw container. If the container is already running, restart it after adding the volume mounts (e.g. docker-compose.yml)
46
62
47
-
This skill requires **Traefik**as a reverse proxy. Everything — including OpenClaw itself — must be routed through Traefik so that all services are available on the same domain.
63
+
> **Important:**The host path mapped to `/home/node/.openclaw` inside the OpenClaw container must **not**be a system directory (e.g. `/etc`, `/proc`, `/sys`, `/dev`, `/root`, `/boot`, `/run`, `/var/run`). Use a dedicated path like `/home/openclaw` or `/opt/openclaw` instead.
48
64
49
-
Devbox containers automatically register Traefik routes on startup by writing config files to the Traefik dynamic directory. This is why Traefik is essential — it allows containers to make themselves reachable without any manual configuration.
65
+
### 2. Routing: Traefik or Cloudflare Tunnels
50
66
51
-
> **If you haven't set up Traefik yet**, follow the [OpenClaw + Traefik Setup Guide](https://gist.github.com/adshrc/3cd9e8a714098f414635b7fe1ab5e573#file-openclaw_traefik-md). It covers creating the Traefik network, configuration, and routing OpenClaw through Traefik.
67
+
Devboxes need a way to expose services via URLs. Choose one:
Your OpenClaw container needs the Traefik dynamic config directory mounted so devbox containers can write route configs:
71
+
Best for: servers with an existing Traefik setup.
72
+
73
+
> **If you haven't set up Traefik yet**, follow the [OpenClaw + Traefik Setup Guide](https://gist.github.com/adshrc/3cd9e8a714098f414635b7fe1ab5e573#file-openclaw_traefik-md).
74
+
75
+
Devbox containers automatically register Traefik routes on startup by writing config files to the Traefik config directory.
76
+
77
+
Your OpenClaw container needs the Traefik config directory mounted. Start your OpenClaw container with this additional flag (if not within /home/openclaw):
node openclaw.mjs gateway --allow-unconfigured --bind lan
80
+
-v path_to_traefik:/home/node/.openclaw/traefik
68
81
```
69
82
70
-
Compared to the [base Traefik setup](https://gist.github.com/adshrc/3cd9e8a714098f414635b7fe1ab5e573#file-openclaw_traefik-md), one mount is added:
71
-
-**`$HOME/traefik/dynamic:/etc/traefik/dynamic`** — so the agent and devbox containers can write Traefik route configs
83
+
Make sure that you have a wildcard DNS record (`*.example.com`) pointing to your server.
84
+
85
+
#### Option B: Cloudflare Tunnels (zero open ports)
86
+
87
+
Best for: environments without a reverse proxy, behind NAT, or where you don't want to expose any ports.
72
88
73
-
### Wildcard DNS
89
+
Each devbox starts `cloudflared` internally and registers DNS records via the Cloudflare API. All traffic is routed through Cloudflare's network — no open ports or Traefik needed.
74
90
75
-
You need a wildcard DNS record (`*.your-domain.com`) pointing to your server so that devbox subdomains (e.g. `vscode-1.your-domain.com`, `api-1.your-domain.com`) resolve automatically.
91
+
Requirements:
76
92
77
-
## Quick Start
93
+
- A **Cloudflare account** with a domain managed by Cloudflare
94
+
- A **Cloudflare API token** with Zone:DNS:Edit and Account:Tunnel:Edit permissions
95
+
96
+
During onboarding, the agent will:
97
+
98
+
1. Validate your Cloudflare API token
99
+
2. Look up the Zone ID for your domain
100
+
3. Create a named tunnel (`openclaw-devboxes`)
101
+
4. Store `CF_API_TOKEN`, `CF_ZONE_ID`, `CF_ACCOUNT_ID`, `CF_TUNNEL_ID`, and `CF_TUNNEL_TOKEN` in the agent config
102
+
103
+
## How to install and use
78
104
79
105
### 1. Install the skill
80
106
81
-
Copy the `SKILL.md`, `scripts/`, and `references/` directories into your OpenClaw workspace:
> **Important:** Both paths must be writable by sandbox containers (UID 1000). The counter file needs `chmod 666`, and the Traefik devboxes dir should be owned by `1000:1000`.
157
+
114
158
## Self-Registration
115
159
116
160
Each container's entrypoint automatically:
117
161
118
162
1. Reads and increments the shared counter → assigns `DEVBOX_ID`
119
163
2. Builds `APP_URL_1..5`, `VSCODE_URL`, `NOVNC_URL` from tags + domain + ID
120
-
3. Writes env vars to `/etc/profile.d/devbox.sh` (available in all shells)
121
-
4. Writes Traefik config to `/traefik/devbox-{id}.yml`
164
+
3. Writes env vars to `/etc/devbox.env` and `/etc/profile.d/devbox.sh` (available in all shells)
165
+
4. Routes based on `ROUTING_MODE`:
166
+
-**Traefik** (default): Writes config to `/traefik/devbox-{id}.yml`
167
+
-**Cloudflare Tunnel**: Generates cloudflared ingress config, registers DNS CNAME records via CF API, starts `cloudflared tunnel run`
122
168
123
169
No manual routing or ID assignment needed.
124
170
171
+
The devbox working directory is `/workspace`. Cloned repos should live under `/workspace/<repo>`.
172
+
173
+
## Cleanup
174
+
175
+
OpenClaw manages the container lifecycle — containers are removed when sessions end. Traefik route configs left behind are harmless.
176
+
125
177
## Project Setup Scripts
126
178
127
179
Projects can include `.openclaw/setup.sh` for automated setup inside a devbox:
@@ -145,22 +197,48 @@ See [setup-script-guide.md](references/setup-script-guide.md) for full conventio
145
197
146
198
## Environment Variables
147
199
148
-
| Variable | Source | Description |
149
-
|----------|--------|-------------|
150
-
|`DEVBOX_ID`| entrypoint | Auto-assigned sequential ID |
151
-
|`APP_URL_1..5`| entrypoint | Full external URLs |
The devbox agent has browser access via Chromium CDP on port 9222. The subagent can use the `browser` tool to navigate, screenshot, and interact with apps running inside the container (use `http://localhost:{port}`).
158
237
159
238
## Important Notes
160
239
161
240
- Sandbox containers run with **all Linux capabilities dropped** (`CapDrop: ALL`). Bind-mounted files/dirs must be world-writable.
162
-
- Wildcard DNS (`*.your-domain.com`) must point to your server.
163
-
- Traefik must be configured with a file provider watching the dynamic config directory.
241
+
- The devbox working directory is always `/workspace`.
0 commit comments