​
Two network modes

Setup mode (AP) — when unconfigured (or when it can’t join a known network), the box hosts its own Wi-Fi: If an Ethernet uplink is connected while in AP mode, the box shares that internet connection to hotspot clients (IP forwarding + NAT). Steady state (LAN) — after setup, the box joins your network and is reachable at:
  1. http://<LAN-IP> — always works; the canonical fallback.
  2. http://clawbox.local — mDNS via avahi (hostname configurable in Settings).

​
Why clawbox.local sometimes fails — and what to do

mDNS (multicast DNS) is what resolves .local names, and it’s the least reliable part of consumer networks:
  • Windows historically resolves mDNS poorly (better in 11, still flaky).
  • Routers/APs often drop multicast between Wi-Fi and wired segments — a wired ClawBox may be invisible by name to Wi-Fi laptops (and vice versa) while being perfectly reachable by IP.
  • Guest networks and VPNs isolate clients from mDNS entirely.
The box already ships mitigations (avahi tuned for Windows quirks, re-announce on network changes) — but when the name fails, use the IP. Find it via:
  • Your router’s connected-devices list (look for clawbox).
  • Over SSH (if ssh [email protected] still works in a terminal): hostname -I — first entry.
  • The device screen/desktop if a display is attached (System Tray → network).
Reserve the box’s IP in your router’s DHCP settings (“address reservation” / “static lease”) so it never changes — then bookmark it.

​
Port map

​
Firewall

The box ships a default-deny inbound firewall (ufw): deny incoming, allow outgoing, allow routed. It is an allowlist, so a port nobody opened is closed — including one that some future package decides to bind on 0.0.0.0.
  • The service ports are scoped to private sources. 22, 80, 443, 18789 and 8090 are open only from 10/8, 172.16/12, 192.168/16, 169.254/16 and 100.64/10 (CGNAT, which is what Tailscale uses). IPv6 is deliberately NOT source-scoped: there is no RFC1918 on v6, a dual-stack LAN hands the box a global address, and that is the address avahi publishes for clawbox.local — scoping to link-local/ULA would drop SSH and the web UI over the very address the box advertises. A ClawBox is an appliance on a home or office LAN; a non-private source address means it has ended up somewhere it was never designed to be.
  • Also open: 5353/udp mDNS from anywhere (otherwise clawbox.local stops resolving), 67/udp DHCP on the AP interface, and 53/tcp+udp from 10.42.0.0/24 and 10.43.0.0/24 for the hotspot’s DNS.
  • Now closed from the LAN: 631 (CUPS), 111 (rpcbind), 8384 (Syncthing if present), and the terminal PTY on 3006 — that last one matters most, because reached directly it is unauthenticated. rpcbind is also disabled and masked, unless an NFS/NIS package is installed. CUPS is left running: on the shipped image it is a snap, so closing 631 at the firewall removes the LAN exposure without breaking local desktop printing.
  • Routing is unchanged. The FORWARD policy is deliberately pinned to ACCEPT so the hotspot’s internet sharing keeps working, and the firewall never flushes or resets — NetworkManager’s shared-AP chains are built once on connection activation and survive untouched.
  • Applied on update, not just on fresh installs, so a box already in the field gets it on its next in-app update.
Inspect the live policy on the box with sudo ufw status verbose.

​
Remote access

  • Named Cloudflare tunnel (since 4.0) — once the portal has provisioned the box, its heartbeat answer carries boxTunnel: { hostname, token }: a stable <box-handle>.clawbox.tech address and a cloudflared tunnel run token for it. Both lines are written to data/cloudflared/named-tunnel (mode 0600, hostname=… / token=…), which scripts/run-tunnel.sh parses line by line. The address does not change across reboots or tunnel restarts, which is what makes it worth bookmarking. The token is a credential — whoever holds it can serve anything under that hostname — so it is never returned by a route, never logged, and never written to tunnel.url. A token cloudflared refuses is deleted and its sha256 recorded in data/cloudflared/named-refused, so the next heartbeat does not store the same dead token and bounce the tunnel every five minutes.
  • Cloudflare Quick Tunnel (the fallback) — with no named credential on the box, clawbox-tunnel.service exposes port 80 through a temporary *.trycloudflare.com URL written to data/cloudflared/tunnel.url. No port-forwarding required. It is opt-in and off by default. The firewall doesn’t affect it: cloudflared runs on the box and delivers to http://localhost:80, so the request arrives over lo. data/cloudflared/tunnel.mode records which of the two actually started, named or quick, and is written by the script only.
  • The named hostname is on the Host allow-list, as that one name and never the whole zone: another box’s handle is still a foreign name here. See Authentication.
  • Settings → Remote Control drives it through GET /setup-api/portal/status, POST /setup-api/portal/start and POST /setup-api/portal/stop. (/setup-api/tunnel/* also exists but nothing in the UI calls it — it is a separate legacy surface. It used to report running:false while a tunnel was in fact up, because it only recognised a cloudflared it had spawned itself; since TASK-453 it reads clawbox-tunnel.service and reports the URL the unit published, plus service and managedBy fields. It still cannot stop the unit, and says so rather than reporting success.)
  • Start also regenerates. start is a systemctl restart, so pressing it on a running tunnel publishes a new URL. Stopping is a clean SIGTERM, which the unit currently records as exit status 143 — systemd scores that as failed, which the panel renders as a red error box even though the stop worked.
  • SSH — standard Ubuntu OpenSSH on port 22, user clawbox, same password as the browser login. Reachable from the private source ranges listed under Firewall — which includes a Tailscale address, since the tailnet lives in 100.64.0.0/10.
  • On the OpenClaw/dual editions, the gateway’s allowed origins are managed automatically (localhost, <hostname>.local, the AP addresses, and the box’s live LAN IPs) — refreshed on every gateway start.

​
Portal heartbeat

clawbox-heartbeat.timer fires clawbox-heartbeat.service every 5 minutes (30 s after boot). That oneshot only curls http://127.0.0.1/setup-api/portal/heartbeat-tick on loopback; the outbound request happens inside the web app.
The device ID is derived from /etc/machine-id, which a factory reset does not touch — so a reset box reappears in the portal as the same device. The cached copy under data/cloudflared/ is deleted by the reset and simply re-derived.

​
DNS & hostname

  • Hostname defaults to clawbox; changing it (Settings → System) updates hostnamectl, avahi (<name>.local), and is persisted in data/hostname.env.
  • In AP mode, clawbox.local is additionally answered by dnsmasq (mDNS doesn’t traverse the hotspot reliably).