Skip to content

Commit 78effef

Browse files
authored
feat: added Cloudflare Tunnel support (#3)
2 parents 66bfdf8 + f5d7297 commit 78effef

4 files changed

Lines changed: 454 additions & 168 deletions

File tree

‎README.md‎

Lines changed: 137 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Whether you're working from your laptop, a tablet, or someone else's machine —
1010

1111
## Features
1212

13-
- **Self-registering containers** — auto-assigns ID, writes Traefik routes, builds `APP_URL_*` env vars
13+
- **Self-registering containers** — auto-assigns ID, configures routing, builds `APP_URL_*` env vars
14+
- **Flexible routing** — choose between Traefik (self-managed) or Cloudflare Tunnels (zero open ports)
1415
- **VSCode Web** — browser-based IDE on port 8000
1516
- **noVNC** — visual desktop access on port 8002
1617
- **Chromium CDP** — headless browser automation on port 9222
@@ -21,84 +22,116 @@ Whether you're working from your laptop, a tablet, or someone else's machine —
2122
## Architecture
2223

2324
```
24-
+----------------------------------------------------------+
25-
| Devbox Container (ghcr.io/adshrc/openclaw-devbox:latest)|
26-
| |
27-
| +----------+ +----------+ +-------------------+ |
28-
| | VSCode | | noVNC | | Chromium (CDP) | |
29-
| | :8000 | | :8002 | | :9222 | |
30-
| +----------+ +----------+ +-------------------+ |
31-
| |
32-
| App 1 :8003 App 2 :8004 App 3 :8005 |
33-
| App 4 :8006 App 5 :8007 |
34-
+----------------------------+-----------------------------+
25+
+-----------------------------------------------------------+
26+
| Devbox Container (ghcr.io/adshrc/openclaw-devbox:latest) |
27+
| |
28+
| +----------+ +----------+ +-------------------+ |
29+
| | VSCode | | noVNC | | Chromium (CDP) | |
30+
| | :8000 | | :8002 | | :9222 | |
31+
| +----------+ +----------+ +-------------------+ |
32+
| |
33+
| App 1 :8003 App 2 :8004 App 3 :8005 |
34+
| App 4 :8006 App 5 :8007 |
35+
+----------------------------+------------------------------+
3536
|
36-
+-----------+
37-
| Traefik | <-- routes auto-configured
38-
+-----+-----+
39-
|
40-
https://{tag}-{id}.{domain}
37+
+-----------------------+
38+
| Traefik/Cloudflared |
39+
+-----------------------+
40+
|
41+
Browser: https://{tag}-{id}.{domain}
4142
```
4243

4344
## Prerequisites
4445

45-
### Traefik Reverse Proxy
46+
### 1. Docker Socket Access
47+
48+
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)
4662
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.
4864
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
5066

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:
5268

53-
### OpenClaw Container
69+
#### Option A: Traefik (self-managed reverse proxy)
5470

55-
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):
5678

5779
```bash
58-
docker run -d \
59-
--name openclaw \
60-
--network traefik \
61-
--restart unless-stopped \
62-
-v $HOME/openclaw:/home/node/.openclaw \
63-
-v $HOME/openclaw/workspace:/home/node/.openclaw/workspace \
64-
-v $HOME/traefik/dynamic:/etc/traefik/dynamic \
65-
-e OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN \
66-
ghcr.io/openclaw/openclaw:latest \
67-
node openclaw.mjs gateway --allow-unconfigured --bind lan
80+
-v path_to_traefik:/home/node/.openclaw/traefik
6881
```
6982

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.
7288

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.
7490

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:
7692

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
78104

79105
### 1. Install the skill
80106

81-
Copy the `SKILL.md`, `scripts/`, and `references/` directories into your OpenClaw workspace:
107+
```bash
108+
npx clawhub@latest install devboxes
109+
```
110+
111+
**OR**
112+
113+
```bash
114+
git clone https://github.com/adshrc/openclaw-devboxes-skill
115+
```
116+
117+
then copy the `SKILL.md` and `references/` directories into your OpenClaw workspace:
82118

83119
```
84-
$HOME/openclaw/workspace/skills/devboxes/
120+
/home/node/.openclaw/workspace/skills/devboxes/
85121
├── SKILL.md
86-
├── scripts/
87-
│ ├── Dockerfile
88-
│ └── entrypoint.sh
89122
└── references/
90123
└── setup-script-guide.md
91124
```
92125

93126
### 2. Ask your agent to set it up
94127

95-
Once the skill files are in place, simply ask your OpenClaw agent:
128+
Once installed, simply ask your OpenClaw agent:
96129

97130
> "Set up the devboxes skill"
98131
99132
The agent will read the skill's onboarding instructions and handle everything:
133+
100134
- Pull the Docker image
101-
- Create the Traefik network (if needed)
102135
- Set up the counter file and permissions
103136
- Configure `openclaw.json` with the devboxes agent
104137
- Ask you for your domain and GitHub token
@@ -111,17 +144,36 @@ After setup, just ask:
111144
112145
The agent spawns a container, waits for self-registration, and returns your URLs.
113146

147+
## Bind Mounts
148+
149+
The devbox agent config maps these paths from the OpenClaw container into each devbox:
150+
151+
| Agent path | Devbox container path | Purpose |
152+
| -------------------------------------- | ------------------------- | ----------------------------------------- |
153+
| `/home/node/.openclaw/.devbox-counter` | `/shared/.devbox-counter` | ID counter |
154+
| `/home/node/.openclaw/traefik/configs` | `/traefik` | Traefik route configs (Traefik mode only) |
155+
156+
> **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+
114158
## Self-Registration
115159

116160
Each container's entrypoint automatically:
117161

118162
1. Reads and increments the shared counter → assigns `DEVBOX_ID`
119163
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`
122168

123169
No manual routing or ID assignment needed.
124170

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+
125177
## Project Setup Scripts
126178

127179
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
145197

146198
## Environment Variables
147199

148-
| Variable | Source | Description |
149-
|----------|--------|-------------|
150-
| `DEVBOX_ID` | entrypoint | Auto-assigned sequential ID |
151-
| `APP_URL_1..5` | entrypoint | Full external URLs |
152-
| `APP_PORT_1..5` | Dockerfile | Internal ports (8003-8007) |
153-
| `APP_TAG_1..5` | config | Route tags |
154-
| `DEVBOX_DOMAIN` | config | Base domain |
155-
| `GITHUB_TOKEN` | config | GitHub PAT |
156-
| `VSCODE_URL` | entrypoint | VSCode Web URL |
157-
| `NOVNC_URL` | entrypoint | noVNC URL |
200+
### Static (set in openclaw.json sandbox.docker.env)
201+
202+
| Variable | Example | Description |
203+
| ----------------- | -------------------------- | ---------------------------------------------------- |
204+
| `ROUTING_MODE` | `traefik` or `cloudflared` | Routing backend (default: `traefik`) |
205+
| `GITHUB_TOKEN` | `ghp_...` | GitHub PAT for cloning |
206+
| `DEVBOX_DOMAIN` | `example.com` | Base domain |
207+
| `APP_TAG_1..5` | `app1`, `app2`, ... | Route tags (e.g. use "app1" as "api") |
208+
| `ENABLE_VNC` | `true` | Enable noVNC |
209+
| `ENABLE_VSCODE` | `true` | Enable VSCode Web |
210+
| `CF_TUNNEL_TOKEN` | `eyJ...` | Cloudflare tunnel run token (cloudflared only) |
211+
| `CF_API_TOKEN` | `abc123` | CF API token for DNS registration (cloudflared only) |
212+
| `CF_ZONE_ID` | `xyz789` | CF zone ID for the domain (cloudflared only) |
213+
| `CF_TUNNEL_ID` | `uuid` | CF tunnel ID for CNAME targets (cloudflared only) |
214+
215+
### Dynamic (built by entrypoint, available in all shells)
216+
217+
| Variable | Example | Description |
218+
| --------------- | -------------------------------------- | --------------------------- |
219+
| `DEVBOX_ID` | `1` | Auto-assigned sequential ID |
220+
| `APP_URL_1..5` | `https://app1-1.example.com` | Full URLs per app slot |
221+
| `APP_PORT_1..5` | `8003..8007` | Internal ports |
222+
| `VSCODE_URL` | `https://vscode-1.example.com` | VSCode Web URL |
223+
| `NOVNC_URL` | `https://novnc-1.example.com/vnc.html` | noVNC URL |
224+
225+
## Ports
226+
227+
| Port | Service |
228+
| --------- | ------------------------------ |
229+
| 8000 | VSCode Web |
230+
| 8002 | noVNC |
231+
| 9222 | Chrome DevTools Protocol (CDP) |
232+
| 8003-8007 | App slots 1-5 |
233+
234+
## Browser
235+
236+
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}`).
158237

159238
## Important Notes
160239

161240
- 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`.
164242

165243
## License
166244

0 commit comments

Comments
 (0)