Runclawd

README

# runclawd
 
 RunClawd is a curated Docker Compose preset repository for OpenClaw, providing an opinionated, production-oriented deployment.
 
 Platform scope (based on the current installer and images):
 
 - **Host OS**: Linux (multiple distros via `apt/dnf/yum/apk/pacman/zypper`)
 - **CPU arch**: `amd64` / `arm64` are explicitly handled in the Dockerfile for some bundled tools
 
 ## Prerequisites
 
 - **Root access**: the installer must run as root (`sudo sh ...`).
 - **Network access**: pulls Docker / container images, and uses Cloudflare Tunnel by default.
 
 ## One-line install (recommended)
 
 ```bash
 curl -fsSL https://get.runclawd.sh -o runclawd.sh
 sudo bash runclawd.sh
 ```
 
 What the installer does (as implemented in `get-runclawd.sh`):
 
 - **Installs dependencies**: `curl`, `git`, `ssh` (via your system package manager: `apt/dnf/yum/apk/pacman/zypper`).
 - **Installs Docker (if missing)**: via `https://get.docker.com`.
 - **Clones/updates this repo**: into `/opt/runclawd`.
 - **Starts services**: runs `docker compose up -d` in `/opt/runclawd`.
 - **Prints access info**: waits for logs and prints `Access Token`, `Web Terminal Password`, and a public `trycloudflare.com` URL.
 
 ## What you get
 
 This repo runs the following services (see `docker-compose.yaml`):
 
 - **OpenClaw Gateway**: `runclawd` container (port `18789` inside the compose network)
 - **Web terminal**: `ttyd` inside `runclawd` (port `7681`)
 - **Reverse proxy**: `caddy` routes:
   - `/` -> `runclawd:18789`
   - `/term/*` -> `runclawd:7681`
   - `/openclaw/*` -> `runclawd:7682`
 - **Public access (optional by default)**: `cloudflared` creates an ephemeral `https://xxxx.trycloudflare.com` tunnel
 - **Docker API hardening**: `docker-proxy` (docker-socket-proxy) exposes only a limited set of Docker APIs to `runclawd`
 
 Data persistence:
 
 - **Persistent volume**: `openclaw-data:/data` (contains OpenClaw state, configs, workspace, shell history, caches, etc.)
 
 ## Access URLs
 
 After installation, the installer prints URLs derived from the tunnel:
 
 - **Onboarding URL**:
   - `<tunnel_url>/openclaw/?arg=onboard`
 - **Gateway dashboard**:
   - `<tunnel_url>/?token=<access_token>`
 - **Web terminal**:
   - `<tunnel_url>/term/` (username `openclaw`, password printed by the installer)
 
 Local access (from the machine running Docker):
 
 - **Gateway**: `http://localhost:18789/?token=<token>`
 - **Web terminal**: `http://localhost:7681/term/`
 
 The gateway token is generated on first boot and stored in `/data/.openclaw/openclaw.json` inside the `runclawd` container (generated by `scripts/bootstrap.sh`).
 
 ## Device approval

 OpenClaw requires devices to be approved before they can access the gateway. The installer provides a link to do this, but you can also do it manually via the CLI or web terminal.

 1. **List devices** to find the pending **Request ID** (UUID):

    ```bash
    openclaw devices list
    ```

    Output example:

    ```text
    Pending (1)
    ┌──────────────────────────────────────┬───────────────────────────────────...
    │ Request                              │ Device                            ...
    ├──────────────────────────────────────┼───────────────────────────────────...
    │ 62cd8691-b244-4e34-90e1-62b5530ef268 │ 0b874c0cb5c7ea23541cccd1034fc930a1...
    └──────────────────────────────────────┴───────────────────────────────────...
    ```

 2. **Approve the device** using the Request ID from the first column:

    ```bash
    openclaw devices approve 62cd8691-b244-4e34-90e1-62b5530ef268
    ```

    Output example:

    ```text
    Approved 0b874c0cb5c7ea23541cccd1034fc930a1dff0895fc42eedb1ab454060a7cff9
    ```

 ## Configure API keys (.env)
 
 This compose preset reads API keys from environment variables (see `docker-compose.yaml`, e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, etc.).
 
 Docker Compose automatically loads a `.env` file from the project directory. On the host:
 
 - **Path**: `/opt/runclawd/.env`
 
 Then set the keys you actually use, for example:
 
 ```bash
 OPENAI_API_KEY=...
 ANTHROPIC_API_KEY=...
 GEMINI_API_KEY=...
 ```
 
 Restart the stack after editing `.env`:
 
 ```bash
 cd /opt/runclawd
 docker compose up -d
 ```
 
 ## Common operations
 
 - **View logs**
 
   ```bash
   cd /opt/runclawd
   docker compose logs -f runclawd
   ```
 
 - **Stop / start**
 
   ```bash
   cd /opt/runclawd
   docker compose stop
   docker compose up -d
   ```
 
 - **Disable public tunnel** (keep local-only access)
 
   ```bash
   cd /opt/runclawd
   docker compose stop cloudflared
   ```
 
 - **Upgrade**
 
   Re-run the installer (it performs `git pull --rebase` and then starts services):
 
   ```bash
   curl -fsSL https://get.runclawd.sh -o runclawd.sh
   sudo sh runclawd.sh
   ```
 
 - **Uninstall**
 
   ```bash
   cd /opt/runclawd
   docker compose down
   docker volume rm runclawd_openclaw-data
   sudo rm -rf /opt/runclawd
   ```
 
 ## Security notes (based on current code)
 
 - **Docker socket is not mounted directly into `runclawd`**. Instead it talks to `docker-proxy` (`DOCKER_HOST=tcp://docker-proxy:2375`), and only a limited set of APIs are enabled.
 - **Caddyfile is mounted read-only**: `./Caddyfile:/etc/caddy/Caddyfile:ro`.
 - **Access control**:
   - Gateway UI requires a token (`auth.mode=token`, generated on first boot).
   - Web terminal is protected by basic auth (`openclaw:<generated password>`).