Skip to content

Commit 4ff19ae

Browse files
committed
feat: implement two-phase startup for devboxes with devbox-init script
1 parent c9f4ccd commit 4ff19ae

4 files changed

Lines changed: 220 additions & 168 deletions

File tree

‎SKILL.md‎

Lines changed: 13 additions & 7 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. 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.
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 devbox agent runs `devbox-init` as its first action, which builds URL env vars, writes env files, and sets up routing.
1111

1212
## File Locations
1313

@@ -30,19 +30,25 @@ Key files:
3030
The **main agent** manages the devbox counter:
3131

3232
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
33+
2. Includes the `DEVBOX_ID` in the task, instructing the devbox agent to run `devbox-init {id}` as its very first action
3534

36-
### Entrypoint
35+
### Two-Phase Startup
3736

38-
The container's entrypoint expects `DEVBOX_ID` to already be set as an environment variable and then:
37+
**Phase 1 — Entrypoint** (runs automatically at container start):
38+
39+
- Starts core services: Xvfb, Chromium (CDP), VNC, VSCode Web
40+
- Does NOT require `DEVBOX_ID` — services are available immediately
41+
42+
**Phase 2 — `devbox-init <id>`** (run by the sub-agent/devbox agent):
3943

4044
1. Builds `APP_URL_1..5`, `VSCODE_URL`, `NOVNC_URL` from tags + domain + ID
4145
2. Writes `/etc/devbox.env` and `/etc/profile.d/devbox.sh` (available in all shells)
4246
3. Routes based on `ROUTING_MODE`:
4347
- **`traefik`** (default): Writes Traefik config to `/traefik/devbox-{id}.yml`
4448
- **`cloudflared`**: Generates cloudflared ingress config, registers DNS CNAME records via CF API, starts `cloudflared tunnel run`
4549

50+
The `devbox-init` script is installed at `/usr/local/bin/devbox-init` in the Docker image.
51+
4652
### Bind Mounts (configured in openclaw.json)
4753

4854
| Agent path | Devbox container path | Purpose |
@@ -288,7 +294,7 @@ Use `devbox-<id>` as the label and include the `DEVBOX_ID` in the task:
288294
sessions_spawn(
289295
agentId="devbox",
290296
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>."
297+
task=f"Your task description. Your DEVBOX_ID is {DEVBOX_ID} — run `devbox-init {DEVBOX_ID}` as your very first action before doing anything else. This sets up routing and writes env vars. After that, env vars (APP_URL_*, VSCODE_URL, etc.) are in your shell via `source /etc/profile.d/devbox.sh`. GitHub token is in $GITHUB_TOKEN. ALWAYS use /workspace as the working directory! When cloning, the structure must be /workspace/<repo>."
292298
)
293299
```
294300

@@ -321,7 +327,7 @@ OpenClaw manages container lifecycle — containers are removed when sessions en
321327
| `CF_ZONE_ID` | `xyz789` | CF zone ID for the domain (cloudflared only) |
322328
| `CF_TUNNEL_ID` | `uuid` | CF tunnel ID for CNAME targets (cloudflared only) |
323329

324-
### Dynamic (built by entrypoint, available in all shells)
330+
### Dynamic (built by `devbox-init`, available in all shells after running it)
325331

326332
| Variable | Example | Description |
327333
| --------------- | -------------------------------------- | --------------------------- |

‎docker/Dockerfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,9 @@ WORKDIR /workspace
139139
COPY entrypoint.sh /entrypoint.sh
140140
RUN chmod +x /entrypoint.sh
141141

142+
COPY devbox-init.sh /usr/local/bin/devbox-init
143+
RUN chmod +x /usr/local/bin/devbox-init
144+
142145
# Re-declare ARGs
143146
ARG VSCODE_PORT=8000
144147
ARG NOVNC_PORT=8002

‎docker/devbox-init.sh‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
#!/bin/bash
2+
#
3+
# devbox-init — called by the devbox agent with the assigned DEVBOX_ID.
4+
# Usage: devbox-init <id>
5+
#
6+
# Builds URL env vars, writes env files, and sets up routing
7+
# (Traefik or Cloudflare Tunnel) based on the assigned DEVBOX_ID.
8+
#
9+
set -e
10+
11+
if [ -z "${1:-}" ]; then
12+
echo "[devbox-init] ERROR: Missing argument. Usage: devbox-init <id>"
13+
exit 1
14+
fi
15+
16+
export DEVBOX_ID="$1"
17+
18+
# Read port/tag defaults from the environment (set by entrypoint)
19+
: "${VSCODE_PORT:=8000}"
20+
: "${NOVNC_PORT:=8002}"
21+
: "${APP_PORT_1:=8003}"
22+
: "${APP_PORT_2:=8004}"
23+
: "${APP_PORT_3:=8005}"
24+
: "${APP_PORT_4:=8006}"
25+
: "${APP_PORT_5:=8007}"
26+
: "${DEVBOX_DOMAIN}"
27+
: "${APP_TAG_1:=app1}"
28+
: "${APP_TAG_2:=app2}"
29+
: "${APP_TAG_3:=app3}"
30+
: "${APP_TAG_4:=app4}"
31+
: "${APP_TAG_5:=app5}"
32+
33+
echo "[devbox-init] Initializing with DEVBOX_ID=$DEVBOX_ID"
34+
35+
########################################
36+
# Build APP_URL_* env vars
37+
########################################
38+
for i in 1 2 3 4 5; do
39+
tag_var="APP_TAG_$i"
40+
export "APP_URL_$i=https://${!tag_var}-${DEVBOX_ID}.${DEVBOX_DOMAIN}"
41+
done
42+
export VSCODE_URL="https://vscode-${DEVBOX_ID}.${DEVBOX_DOMAIN}"
43+
export NOVNC_URL="https://novnc-${DEVBOX_ID}.${DEVBOX_DOMAIN}/vnc.html"
44+
45+
########################################
46+
# Write env files
47+
########################################
48+
cat > /etc/devbox.env << EOF
49+
export DEVBOX_ID=$DEVBOX_ID
50+
export DEVBOX_DOMAIN=$DEVBOX_DOMAIN
51+
export VSCODE_URL=$VSCODE_URL
52+
export NOVNC_URL=$NOVNC_URL
53+
$(for i in 1 2 3 4 5; do
54+
tag_var="APP_TAG_$i"
55+
port_var="APP_PORT_$i"
56+
echo "export APP_TAG_$i=${!tag_var}"
57+
echo "export APP_PORT_$i=${!port_var}"
58+
echo "export APP_URL_$i=$(eval echo \$APP_URL_$i)"
59+
done)
60+
EOF
61+
62+
# Make env vars available in all new shells
63+
cp /etc/devbox.env /etc/profile.d/devbox.sh
64+
grep -q '/etc/devbox.env' /root/.bashrc 2>/dev/null || echo ". /etc/devbox.env" >> /root/.bashrc
65+
66+
# Source into the current shell
67+
. /etc/devbox.env
68+
69+
echo "[devbox-init] Env files written"
70+
71+
########################################
72+
# Routing: Traefik or Cloudflare Tunnel
73+
########################################
74+
: "${ROUTING_MODE:=traefik}"
75+
76+
if [ "$ROUTING_MODE" = "cloudflared" ]; then
77+
########################################
78+
# Cloudflare Tunnel routing
79+
########################################
80+
echo "[devbox-init] Routing mode: cloudflared"
81+
82+
if [ -z "${CF_TUNNEL_TOKEN:-}" ]; then
83+
echo "[devbox-init] ERROR: CF_TUNNEL_TOKEN is required for cloudflared routing mode"
84+
exit 1
85+
fi
86+
87+
# Build ingress config
88+
CF_CONFIG_DIR="/etc/cloudflared"
89+
mkdir -p "$CF_CONFIG_DIR"
90+
91+
cat > "${CF_CONFIG_DIR}/config.yml" << CFEOF
92+
ingress:
93+
- hostname: vscode-${DEVBOX_ID}.${DEVBOX_DOMAIN}
94+
service: http://localhost:${VSCODE_PORT}
95+
- hostname: novnc-${DEVBOX_ID}.${DEVBOX_DOMAIN}
96+
service: http://localhost:${NOVNC_PORT}
97+
$(for i in 1 2 3 4 5; do
98+
tag_var="APP_TAG_$i"
99+
port_var="APP_PORT_$i"
100+
echo " - hostname: ${!tag_var}-${DEVBOX_ID}.${DEVBOX_DOMAIN}"
101+
echo " service: http://localhost:${!port_var}"
102+
done)
103+
- service: http_status:404
104+
CFEOF
105+
106+
echo "[devbox-init] Cloudflared config written: ${CF_CONFIG_DIR}/config.yml"
107+
108+
# Register DNS records via CF API
109+
if [ -n "${CF_API_TOKEN:-}" ] && [ -n "${CF_ZONE_ID:-}" ] && [ -n "${CF_TUNNEL_ID:-}" ]; then
110+
HOSTNAMES="vscode-${DEVBOX_ID}.${DEVBOX_DOMAIN} novnc-${DEVBOX_ID}.${DEVBOX_DOMAIN}"
111+
for i in 1 2 3 4 5; do
112+
tag_var="APP_TAG_$i"
113+
HOSTNAMES="$HOSTNAMES ${!tag_var}-${DEVBOX_ID}.${DEVBOX_DOMAIN}"
114+
done
115+
116+
for h in $HOSTNAMES; do
117+
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/${CF_ZONE_ID}/dns_records" \
118+
-H "Authorization: Bearer ${CF_API_TOKEN}" \
119+
-H "Content-Type: application/json" \
120+
-d "{\"type\":\"CNAME\",\"name\":\"${h}\",\"content\":\"${CF_TUNNEL_ID}.cfargotunnel.com\",\"proxied\":true}" \
121+
> /dev/null 2>&1 || true
122+
done
123+
echo "[devbox-init] DNS records registered for devbox-${DEVBOX_ID}"
124+
else
125+
echo "[devbox-init] WARNING: CF_API_TOKEN/CF_ZONE_ID/CF_TUNNEL_ID not set, skipping DNS registration"
126+
fi
127+
128+
# Start cloudflared tunnel
129+
cloudflared tunnel --config "${CF_CONFIG_DIR}/config.yml" run --token "${CF_TUNNEL_TOKEN}" &
130+
echo "[devbox-init] Cloudflared tunnel started"
131+
132+
else
133+
########################################
134+
# Traefik registration (default)
135+
########################################
136+
echo "[devbox-init] Routing mode: traefik"
137+
138+
TRAEFIK_DIR="/traefik"
139+
if [ -d "$TRAEFIK_DIR" ]; then
140+
CONTAINER_NAME=$(hostname)
141+
CONFIG_FILE="${TRAEFIK_DIR}/devbox-${DEVBOX_ID}.yml"
142+
143+
python3 -c "
144+
import sys
145+
devbox_id = '${DEVBOX_ID}'
146+
container = '${CONTAINER_NAME}'
147+
domain = '${DEVBOX_DOMAIN}'
148+
149+
services = {'vscode': ${VSCODE_PORT}, 'novnc': ${NOVNC_PORT}}
150+
tags = ['${APP_TAG_1}','${APP_TAG_2}','${APP_TAG_3}','${APP_TAG_4}','${APP_TAG_5}']
151+
ports = [${APP_PORT_1},${APP_PORT_2},${APP_PORT_3},${APP_PORT_4},${APP_PORT_5}]
152+
for tag, port in zip(tags, ports):
153+
services[tag] = port
154+
155+
lines = ['http:', ' routers:']
156+
for name in services:
157+
svc = f'{name}-{devbox_id}'
158+
lines += [
159+
f' {svc}:',
160+
f' rule: \"Host(\`{svc}.{domain}\`)\"',
161+
f' service: {svc}',
162+
f' entryPoints:',
163+
f' - web',
164+
]
165+
lines.append(' services:')
166+
for name, port in services.items():
167+
svc = f'{name}-{devbox_id}'
168+
lines += [
169+
f' {svc}:',
170+
f' loadBalancer:',
171+
f' servers:',
172+
f' - url: \"http://{container}:{port}\"',
173+
]
174+
with open('${CONFIG_FILE}', 'w') as f:
175+
f.write('\n'.join(lines) + '\n')
176+
"
177+
echo "[devbox-init] Traefik config written: $CONFIG_FILE"
178+
else
179+
echo "[devbox-init] WARNING: /traefik not mounted, skipping Traefik registration"
180+
fi
181+
fi
182+
183+
########################################
184+
# Summary
185+
########################################
186+
echo "[devbox-init] URLs:"
187+
echo " VSCode: $VSCODE_URL"
188+
echo " noVNC: $NOVNC_URL"
189+
for i in 1 2 3 4 5; do
190+
tag_var="APP_TAG_$i"
191+
port_var="APP_PORT_$i"
192+
url_var="APP_URL_$i"
193+
echo " App $i (${!tag_var}): port=${!port_var} url=${!url_var}"
194+
done
195+
echo "[devbox-init] Done."

0 commit comments

Comments
 (0)