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 c9f4ccd
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: SKILL.md
+73-67Lines changed: 73 additions & 67 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ description: Manage development environment containers (devboxes) with web-acces
7
7
8
8
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**.
9
9
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.
|`/home/node/.openclaw/traefik`|`/traefik`| Route configs (only if using Traefik routing) |
45
51
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`.
47
53
48
54
### Known Paths
49
55
@@ -54,13 +60,13 @@ These paths are always the same inside the OpenClaw container:
54
60
55
61
## Onboarding Flow
56
62
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.
58
64
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.
60
66
61
67
When the user asks to set up the devbox skill, do the following:
62
68
63
-
### Step 1: Verify Docker prerequisites
69
+
### Step 1: Verify Docker Access
64
70
65
71
Verify that you have access to the Docker socket and Docker binary:
66
72
@@ -80,7 +86,19 @@ and that they need to set `chmod 666 /var/run/docker.sock` manually on the host,
80
86
81
87
The OpenClaw container needs to be restarted then. After that, they can ask to set up the devbox skill again.
82
88
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!)
84
102
85
103
Find out what the host path/mapping is for `/home/node/.openclaw` inside the container:
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.
97
115
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
111
117
112
118
#### If routing mode is Traefik:
113
119
120
+
Check that /home/node/.openclaw/traefik is mounted:
121
+
114
122
```bash
115
-
# Check that /home/node/.openclaw/traefik is mounted
116
123
ls /home/node/.openclaw/traefik
117
124
```
118
125
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.
120
127
121
128
#### If routing mode is Cloudflare Tunnel:
122
129
123
130
Validate the CF API token and domain:
124
131
125
132
```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)
131
134
curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=${ROOT_DOMAIN}" \
132
135
-H "Authorization: Bearer ${CF_API_TOKEN}"| jq .
133
136
134
-
#3. Get account ID from the zone response
137
+
#2. Get account ID from the zone response
135
138
# account_id = .result[0].account.id
136
139
# zone_id = .result[0].id
137
140
```
@@ -143,7 +146,7 @@ Then create the tunnel:
143
146
curl -s -X POST "https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/cfd_tunnel" \
Use `devbox-<id>` as the label and include the `DEVBOX_ID` in the task:
274
286
275
287
```python
276
288
sessions_spawn(
277
289
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>."
280
292
)
281
293
```
282
294
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)
284
296
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:
0 commit comments