Skip to content

Commit c9f4ccd

Browse files
committed
fix: clarify devbox ID assignment and entrypoint behavior in SKILL documentation
1 parent 7733cca commit c9f4ccd

1 file changed

Lines changed: 73 additions & 67 deletions

File tree

‎SKILL.md‎

Lines changed: 73 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: Manage development environment containers (devboxes) with web-acces
77

88
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**.
99

10-
OpenClaw manages the full container lifecycle. Containers **self-register** — the entrypoint auto-assigns an ID, writes Traefik routes, and builds `APP_URL_*` env vars. The main agent just spawns and reports URLs.
10+
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 entrypoint uses this ID to write Traefik routes and build `APP_URL_*` env vars.
1111

1212
## File Locations
1313

@@ -25,25 +25,31 @@ Key files:
2525
- **Network:** `traefik` (for Traefik routing) or default Docker network (for Cloudflare Tunnel routing)
2626
- **Browser:** `sandbox.browser.enabled: true`, CDP on port 9222
2727

28-
### Self-Registration (entrypoint)
28+
### ID Assignment
2929

30-
The container's entrypoint automatically:
30+
The **main agent** manages the devbox counter:
3131

32-
1. Reads and increments `/shared/.devbox-counter` → assigns `DEVBOX_ID`
33-
2. Builds `APP_URL_1..5`, `VSCODE_URL`, `NOVNC_URL` from tags + domain + ID
34-
3. Writes `/etc/devbox.env` and `/etc/profile.d/devbox.sh` (available in all shells)
35-
4. Routes based on `ROUTING_MODE`:
32+
1. Reads and increments `/home/node/.openclaw/.devbox-counter` before spawning
33+
2. Passes the assigned `DEVBOX_ID` to the devbox agent via the task description
34+
3. The devbox agent must `export DEVBOX_ID={id}` as the very first action
35+
36+
### Entrypoint
37+
38+
The container's entrypoint expects `DEVBOX_ID` to already be set as an environment variable and then:
39+
40+
1. Builds `APP_URL_1..5`, `VSCODE_URL`, `NOVNC_URL` from tags + domain + ID
41+
2. Writes `/etc/devbox.env` and `/etc/profile.d/devbox.sh` (available in all shells)
42+
3. Routes based on `ROUTING_MODE`:
3643
- **`traefik`** (default): Writes Traefik config to `/traefik/devbox-{id}.yml`
3744
- **`cloudflared`**: Generates cloudflared ingress config, registers DNS CNAME records via CF API, starts `cloudflared tunnel run`
3845

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

41-
| Agent path | Devbox container path | Purpose |
42-
| -------------------------------------- | ------------------------- | ------------- |
43-
| `/home/node/.openclaw/.devbox-counter` | `/shared/.devbox-counter` | ID counter |
44-
| `/home/node/.openclaw/traefik` | `/traefik` | Route configs |
48+
| Agent path | Devbox container path | Purpose |
49+
| ------------------------------ | --------------------- | --------------------------------------------- |
50+
| `/home/node/.openclaw/traefik` | `/traefik` | Route configs (only if using Traefik routing) |
4551

46-
**Important:** Both paths must be writable by the sandbox containers (UID 1000). The counter file needs `chmod 666`, and the Traefik devboxes dir should be owned by `1000:1000` (set up during host provisioning).
52+
**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`.
4753

4854
### Known Paths
4955

@@ -54,13 +60,13 @@ These paths are always the same inside the OpenClaw container:
5460

5561
## Onboarding Flow
5662

57-
**Important:** After this skill is installed, the next step must be this onboarding flow. The user CANNOT use the devbox skill until the onboarding flow is completed and the infrastructure is set up.
63+
**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.
5864

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

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

63-
### Step 1: Verify Docker prerequisites
69+
### Step 1: Verify Docker Access
6470

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

@@ -80,7 +86,19 @@ and that they need to set `chmod 666 /var/run/docker.sock` manually on the host,
8086

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

83-
### Step 2: Validate the Host Mapping Path
89+
### Step 2: Gather configuration info
90+
91+
Ask the user for:
92+
93+
- **Routing mode**: Traefik or Cloudflare Tunnel?
94+
- **Domain**: with wildcard A-Record pointing to the server (e.g. `*.example.com`)
95+
- **GitHub token** (optional): for cloning private repos inside devboxes
96+
97+
If **Cloudflare Tunnel** is chosen, also ask for:
98+
99+
- **Cloudflare API token**: must have permissions for the zone (DNS edit + Tunnel edit)
100+
101+
### Step 3: Validate the Host Mapping Path (ONLY if using Traefik routing, skip otherwise!)
84102

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

@@ -95,43 +113,28 @@ System directories are: /etc, /private/etc, /proc, /sys, /dev, /root, /boot, /ru
95113

96114
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.
97115

98-
### Step 3: Gather info and detect paths
99-
100-
Ask the user for:
101-
102-
- **Routing mode**: Traefik or Cloudflare Tunnel?
103-
- **Domain**: with wildcard A-Record pointing to the server (e.g. `*.example.com`)
104-
- **GitHub token** (optional): for cloning private repos inside devboxes
105-
106-
If **Cloudflare Tunnel** is chosen, also ask for:
107-
108-
- **Cloudflare API token**: must have permissions for the zone (DNS edit + Tunnel edit)
109-
110-
### Step 4: Verify prerequisites
116+
### Step 4: Verify Routing prerequisites
111117

112118
#### If routing mode is Traefik:
113119

120+
Check that /home/node/.openclaw/traefik is mounted:
121+
114122
```bash
115-
# Check that /home/node/.openclaw/traefik is mounted
116123
ls /home/node/.openclaw/traefik
117124
```
118125

119-
If `/home/node/.openclaw/traefik` doesn't exist, tell the user they need to add e.g. `-v path_to_traefik:/home/node/.openclaw/traefik` to their OpenClaw container and restart it.
126+
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.
120127

121128
#### If routing mode is Cloudflare Tunnel:
122129

123130
Validate the CF API token and domain:
124131

125132
```bash
126-
# 1. Verify token is valid
127-
curl -s -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
128-
-H "Authorization: Bearer ${CF_API_TOKEN}" | jq .
129-
130-
# 2. Get zone ID for the domain (extract root domain from the provided domain)
133+
# 1. Get zone ID for the domain (extract root domain from the provided domain)
131134
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=${ROOT_DOMAIN}" \
132135
-H "Authorization: Bearer ${CF_API_TOKEN}" | jq .
133136

134-
# 3. Get account ID from the zone response
137+
# 2. Get account ID from the zone response
135138
# account_id = .result[0].account.id
136139
# zone_id = .result[0].id
137140
```
@@ -143,7 +146,7 @@ Then create the tunnel:
143146
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/cfd_tunnel" \
144147
-H "Authorization: Bearer ${CF_API_TOKEN}" \
145148
-H "Content-Type: application/json" \
146-
-d '{"name": "openclaw-devboxes", "tunnel_secret": "'$(openssl rand -base64 32)'"}' | jq .
149+
-d '{"name": "devboxes@'"$(hostname)"'", "config_src": "local", "tunnel_secret": "'$(openssl rand -base64 32)'"}' | jq .
147150

148151
# Extract tunnel_id and tunnel_token from the response
149152
# tunnel_id = .result.id
@@ -156,24 +159,23 @@ Store the values: `CF_API_TOKEN`, `CF_ZONE_ID`, `CF_ACCOUNT_ID`, `CF_TUNNEL_ID`,
156159

157160
```bash
158161
echo "0" > /home/node/.openclaw/.devbox-counter
159-
chmod 666 /home/node/.openclaw/.devbox-counter
160162
```
161163

162-
**Important:** The counter is never reset, it just keeps incrementing.
164+
**Important:** The counter file is managed by the main agent only. The counter CANNOT be reset, or decremented, only increment is allowed!
163165

164166
### Step 6: Configure OpenClaw
165167

166-
First, check the current "agents" config:
168+
First, check the current agents config:
167169

168170
```bash
169171
node /app/openclaw.mjs config get agents
170172
```
171173

172-
Then, decice what needs to be adjusted based on the existing config:
174+
Then, decide what needs to be adjusted based on the existing config:
173175

174176
#### Main Agent
175177

176-
IF there is an agent with `default: true`, note its index and add `subagents.allowAgents` to it:
178+
If there is an agent with `default: true`, note its index and add `subagents.allowAgents` to it:
177179

178180
```bash
179181
node /app/openclaw.mjs config set agents.list[{index}].subagents.allowAgents '["devbox"]' --json
@@ -185,7 +187,7 @@ then (if needed), set sandbox mode to `off` (since the main agent doesn't need a
185187
node /app/openclaw.mjs config set agents.list[{index}].sandbox.mode "off"
186188
```
187189

188-
ELSE there's no agent with `default: true`, create one at the next index with the necessary structure:
190+
else, if there's no agent with `default: true`, create one at the next index with the necessary structure:
189191

190192
```bash
191193
node /app/openclaw.mjs config set agents.list[{index}] '{
@@ -242,7 +244,6 @@ node /app/openclaw.mjs config set agents.list[{index}] '{
242244
"CF_TUNNEL_ID": "{cf_tunnel_id}",
243245
},
244246
"binds": [
245-
"{host_openclaw_path}/.devbox-counter:/shared/.devbox-counter:rw",
246247
"{host_openclaw_path}/traefik:/traefik:rw" # Only needed for Traefik routing mode, exclude otherwise
247248
]
248249
},
@@ -270,29 +271,34 @@ After this is done, restart the gateway to apply the changes. If this is not wor
270271

271272
## Workflow: Spawn a Devbox
272273

273-
### Step 1: Spawn subagent (main agent)
274+
### Step 1: Assign ID (main agent)
275+
276+
Read and increment the counter file:
277+
278+
```bash
279+
DEVBOX_ID=$(( $(cat /home/node/.openclaw/.devbox-counter) + 1 ))
280+
echo "$DEVBOX_ID" > /home/node/.openclaw/.devbox-counter
281+
```
282+
283+
### Step 2: Spawn subagent (main agent)
284+
285+
Use `devbox-<id>` as the label and include the `DEVBOX_ID` in the task:
274286

275287
```python
276288
sessions_spawn(
277289
agentId="devbox",
278-
label="devbox-{task_name}",
279-
task="Your task description. GitHub token is in $GITHUB_TOKEN. Env vars (DEVBOX_ID, APP_URL_*, etc.) are in your shell via `source /etc/profile.d/devbox.sh`. ALWAYS use /workspace as the working directory! When cloning, the structure must be /workspace/<repo>."
290+
label=f"devbox-{DEVBOX_ID}",
291+
task=f"Your task description. Your DEVBOX_ID is {DEVBOX_ID} — run `export DEVBOX_ID={DEVBOX_ID}` as your very first action before doing anything else. GitHub token is in $GITHUB_TOKEN. After exporting DEVBOX_ID, env vars (APP_URL_*, etc.) are in your shell via `source /etc/profile.d/devbox.sh`. ALWAYS use /workspace as the working directory! When cloning, the structure must be /workspace/<repo>."
280292
)
281293
```
282294

283-
That's it! The container self-registers. No manual ID assignment or Traefik setup needed.
295+
### Step 3: Report URLs to user (main agent)
284296

285-
### Step 2: Report URLs to user (main agent)
286-
287-
Read the counter to know the assigned ID, then report:
288-
289-
```bash
290-
DEVBOX_ID=$(cat .devbox-counter)
291-
```
297+
The main agent already knows the assigned ID from Step 1. Report:
292298

293-
- VSCode: `https://vscode-{id}.{domain}`
294-
- noVNC: `https://novnc-{id}.{domain}/vnc.html`
295-
- App URLs: `https://{tag}-{id}.{domain}`
299+
- VSCode: `https://vscode-{DEVBOX_ID}.{domain}`
300+
- noVNC: `https://novnc-{DEVBOX_ID}.{domain}/vnc.html`
301+
- App URLs: `https://{tag}-{DEVBOX_ID}.{domain}`
296302

297303
### Cleanup
298304

@@ -306,7 +312,7 @@ OpenClaw manages container lifecycle — containers are removed when sessions en
306312
| ----------------- | -------------------------- | ---------------------------------------------------- |
307313
| `ROUTING_MODE` | `traefik` or `cloudflared` | Routing backend (default: `traefik`) |
308314
| `GITHUB_TOKEN` | `ghp_...` | GitHub PAT for cloning |
309-
| `DEVBOX_DOMAIN` | `oc.example.com` | Base domain |
315+
| `DEVBOX_DOMAIN` | `example.com` | Base domain |
310316
| `APP_TAG_1..5` | `app1`, `app2`, ... | Route tags |
311317
| `ENABLE_VNC` | `true` | Enable noVNC |
312318
| `ENABLE_VSCODE` | `true` | Enable VSCode Web |
@@ -317,13 +323,13 @@ OpenClaw manages container lifecycle — containers are removed when sessions en
317323

318324
### Dynamic (built by entrypoint, available in all shells)
319325

320-
| Variable | Example | Description |
321-
| --------------- | ----------------------------------------- | --------------------------- |
322-
| `DEVBOX_ID` | `1` | Auto-assigned sequential ID |
323-
| `APP_URL_1..5` | `https://app1-1.oc.example.com` | Full URLs per app slot |
324-
| `APP_PORT_1..5` | `8003..8007` | Internal ports |
325-
| `VSCODE_URL` | `https://vscode-1.oc.example.com` | VSCode Web URL |
326-
| `NOVNC_URL` | `https://novnc-1.oc.example.com/vnc.html` | noVNC URL |
326+
| Variable | Example | Description |
327+
| --------------- | -------------------------------------- | --------------------------- |
328+
| `DEVBOX_ID` | `1` | Auto-assigned sequential ID |
329+
| `APP_URL_1..5` | `https://app1-1.example.com` | Full URLs per app slot |
330+
| `APP_PORT_1..5` | `8003..8007` | Internal ports |
331+
| `VSCODE_URL` | `https://vscode-1.example.com` | VSCode Web URL |
332+
| `NOVNC_URL` | `https://novnc-1.example.com/vnc.html` | noVNC URL |
327333

328334
### Ports
329335

0 commit comments

Comments
 (0)