diff --git a/docs/install/podman.md b/docs/install/podman.md index 888bbc904b9..8c8de73bcd2 100644 --- a/docs/install/podman.md +++ b/docs/install/podman.md @@ -7,49 +7,60 @@ title: "Podman" # Podman -Run the OpenClaw gateway in a **rootless** Podman container. Uses the same image as Docker (build from the repo [Dockerfile](https://github.com/openclaw/openclaw/blob/main/Dockerfile)). +Run the OpenClaw Gateway in a **rootless** Podman container. Uses the same image as Docker (built from the repo [Dockerfile](https://github.com/openclaw/openclaw/blob/main/Dockerfile)). -## Requirements +## Prerequisites -- Podman (rootless) -- Sudo for one-time setup (create user, build image) +- **Podman** (rootless mode) +- **sudo** access for one-time setup (creating the dedicated user and building the image) ## Quick start -**1. One-time setup** (from repo root; creates user, builds image, installs launch script): + + + From the repo root, run the setup script. It creates a dedicated `openclaw` user, builds the container image, and installs the launch script: -```bash -./setup-podman.sh -``` + ```bash + ./setup-podman.sh + ``` -This also creates a minimal `~openclaw/.openclaw/openclaw.json` (sets `gateway.mode="local"`) so the gateway can start without running the wizard. + This also creates a minimal config at `~openclaw/.openclaw/openclaw.json` (sets `gateway.mode` to `"local"`) so the Gateway can start without running the wizard. -By default the container is **not** installed as a systemd service, you start it manually (see below). For a production-style setup with auto-start and restarts, install it as a systemd Quadlet user service instead: + By default the container is **not** installed as a systemd service -- you start it manually in the next step. For a production-style setup with auto-start and restarts, pass `--quadlet` instead: -```bash -./setup-podman.sh --quadlet -``` + ```bash + ./setup-podman.sh --quadlet + ``` -(Or set `OPENCLAW_PODMAN_QUADLET=1`; use `--container` to install only the container and launch script.) + (Or set `OPENCLAW_PODMAN_QUADLET=1`. Use `--container` to install only the container and launch script.) -Optional build-time env vars (set before running `setup-podman.sh`): + **Optional build-time env vars** (set before running `setup-podman.sh`): -- `OPENCLAW_DOCKER_APT_PACKAGES` — install extra apt packages during image build -- `OPENCLAW_EXTENSIONS` — pre-install extension dependencies (space-separated extension names, e.g. `diagnostics-otel matrix`) + - `OPENCLAW_DOCKER_APT_PACKAGES` -- install extra apt packages during image build. + - `OPENCLAW_EXTENSIONS` -- pre-install extension dependencies (space-separated names, e.g. `diagnostics-otel matrix`). -**2. Start gateway** (manual, for quick smoke testing): + -```bash -./scripts/run-openclaw-podman.sh launch -``` + + For a quick manual launch: -**3. Onboarding wizard** (e.g. to add channels or providers): + ```bash + ./scripts/run-openclaw-podman.sh launch + ``` -```bash -./scripts/run-openclaw-podman.sh launch setup -``` + -Then open `http://127.0.0.1:18789/` and use the token from `~openclaw/.openclaw/.env` (or the value printed by setup). + + To add channels or providers interactively: + + ```bash + ./scripts/run-openclaw-podman.sh launch setup + ``` + + Then open `http://127.0.0.1:18789/` and use the token from `~openclaw/.openclaw/.env` (or the value printed by setup). + + + ## Systemd (Quadlet, optional) diff --git a/docs/vps.md b/docs/vps.md index 008f24b9b16..2367043650e 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -6,45 +6,47 @@ read_when: title: "VPS Hosting" --- -# VPS hosting +# VPS Hosting -This hub links to the supported VPS/hosting guides and explains how cloud -deployments work at a high level. +Run the OpenClaw Gateway around the clock on a cloud VPS. This page helps you pick a provider, explains how cloud deployments work, and covers generic Linux server tuning that applies to every provider. ## Pick a provider -- **Railway** (one‑click + browser setup): [Railway](/install/railway) -- **Northflank** (one‑click + browser setup): [Northflank](/install/northflank) -- **Oracle Cloud (Always Free)**: [Oracle](/platforms/oracle) — $0/month (Always Free, ARM; capacity/signup can be finicky) -- **Fly.io**: [Fly.io](/install/fly) -- **Hetzner (Docker)**: [Hetzner](/install/hetzner) -- **GCP (Compute Engine)**: [GCP](/install/gcp) -- **Azure (Linux VM)**: [Azure](/install/azure) -- **exe.dev** (VM + HTTPS proxy): [exe.dev](/install/exe-dev) -- **AWS (EC2/Lightsail/free tier)**: works well too. Community video guide: - [https://x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547) - (community resource, may become unavailable) + + One-click, browser setup + One-click, browser setup + Always Free ARM tier ($0/month, capacity can be finicky) + Fly Machines + Docker on Hetzner VPS + Compute Engine + Linux VM + VM with HTTPS proxy + + +**AWS (EC2 / Lightsail / free tier)** also works well. +A community video walkthrough is available at +[x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547) +(community resource -- may become unavailable). ## How cloud setups work - The **Gateway runs on the VPS** and owns state + workspace. -- You connect from your laptop/phone via the **Control UI** or **Tailscale/SSH**. -- Treat the VPS as the source of truth and **back up** the state + workspace. +- You connect from your laptop or phone via the **Control UI** or **Tailscale/SSH**. +- Treat the VPS as the source of truth and **back up** the state + workspace regularly. - Secure default: keep the Gateway on loopback and access it via SSH tunnel or Tailscale Serve. - If you bind to `lan`/`tailnet`, require `gateway.auth.token` or `gateway.auth.password`. + If you bind to `lan` or `tailnet`, require `gateway.auth.token` or `gateway.auth.password`. -Remote access: [Gateway remote](/gateway/remote) -Platforms hub: [Platforms](/platforms) +Related pages: [Gateway remote access](/gateway/remote), [Platforms hub](/platforms). ## Shared company agent on a VPS -This is a valid setup when the users are in one trust boundary (for example one company team), and the agent is business-only. +Running a single agent for a team is a valid setup when every user is in the same trust boundary and the agent is business-only. - Keep it on a dedicated runtime (VPS/VM/container + dedicated OS user/accounts). - Do not sign that runtime into personal Apple/Google accounts or personal browser/password-manager profiles. - If users are adversarial to each other, split by gateway/host/OS user. -Security model details: [Security](/gateway/security) +Security model details: [Security](/gateway/security). ## Using nodes with a VPS @@ -52,7 +54,7 @@ You can keep the Gateway in the cloud and pair **nodes** on your local devices (Mac/iOS/Android/headless). Nodes provide local screen/camera/canvas and `system.run` capabilities while the Gateway stays in the cloud. -Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes) +Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes). ## Startup tuning for small VMs and ARM hosts @@ -69,14 +71,14 @@ source ~/.bashrc - `NODE_COMPILE_CACHE` improves repeated command startup times. - `OPENCLAW_NO_RESPAWN=1` avoids extra startup overhead from a self-respawn path. -- First command run warms cache; subsequent runs are faster. +- First command run warms the cache; subsequent runs are faster. - For Raspberry Pi specifics, see [Raspberry Pi](/platforms/raspberry-pi). ### systemd tuning checklist (optional) For VM hosts using `systemd`, consider: -- Add service env for stable startup path: +- Add service env for a stable startup path: - `OPENCLAW_NO_RESPAWN=1` - `NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache` - Keep restart behavior explicit: