OpenClaw Deployment (Provisioning Flow)

Last updated: 2026-08-06

This document describes how an OpenClaw runtime is provisioned on the HostAgentics platform: the service layout, persistence, gateway credential, domain, health verification, hardening, and channel setup. It is an internal engineering document; customer-facing claims must stay within what this flow actually delivers.

1. Service layout

An OpenClaw runtime is a **dedicated gateway service** from the official OpenClaw production image (`ghcr.io/openclaw/openclaw:2026.7.1-2` at the tested default, digest-pinned via the version catalog). One gateway cell per tenant matches the official multi-tenant model. The service runs in the runtime's shard project and region.

2. Persistence: config and workspace volumes

**State volume** mounted at `/home/node/.openclaw` — holds configuration, workspaces, agent state, and the XDG auth-profile encryption material. `XDG_CONFIG_HOME` points into this volume because the infrastructure provider supports one volume per service.

**Auth-profile keys** are kept separately under `/home/node/.config/openclaw` (the directory the official image uses for auth-profile encryption keys), so encryption key material is not mixed with workspace data.

Both directories live on the runtime's own persistent volume; storage is never shared between runtimes, and the volume is attached to exactly this runtime's service.

3. Gateway credential: generated, encrypted, per runtime

Each OpenClaw runtime gets a **generated gateway token** (`gateway-token` → `OPENCLAW_GATEWAY_TOKEN`), created at provisioning time, stored in the runtime's encrypted secret scope (AES-256-GCM envelope, `docs/secret-rotation.md`), and injected into the service environment at configure time. There is no shared platform credential: one token per runtime, and a rotated token stops working on redeploy. Model access is provided via a restricted per-runtime key (HostAgentics credit) or the customer's BYOK key — never the platform management key.

4. Domain and HTTPS

The runtime is assigned a branded domain `<subdomain>.runtime.hostagentics.com` with automatic HTTPS: the provider assigns the domain, DNS records are confirmed, and certificate status is polled until `active` before the runtime is presented as ready. The gateway's base URL is derived from that domain.

5. Health verification

The gateway listens on port **18789**. The health probe sends an authenticated request to the gateway root; **any HTTP response — including a 401 auth challenge — proves the process is live and enforcing authentication**, and counts as healthy. A gateway that answers without an auth challenge is treated as unhealthy (it is not enforcing token auth). Provisioning cannot reach `running`, and restores cannot be marked completed, until this probe passes.

6. Hardening (no host access)

OpenClaw runtimes run with the platform's standard sandbox posture (see `docs/sandboxing.md`):

**No host Docker socket** — neither the control plane nor any runtime exposes one; there is no socket concept in the provider abstraction.

**No cloud metadata access** — runtime workloads cannot reach provider-internal metadata endpoints or control-plane internal services.

**Restricted filesystem** — persistence is confined to the runtime's volumes; the agent's file access is bounded by the safe-mode policy.

**Safe mode is the default** — agent tool use and outbound actions are restricted unless the customer explicitly configures otherwise, and plan concurrency/browser-session caps are enforced regardless of mode.

7. Channel setup

OpenClaw connects to the customer's messaging channels through guided setup: **web chat, Telegram, Discord, Slack, and WhatsApp**. Channel credentials (bot tokens, webhook secrets) are submitted once, stored encrypted in the runtime's secret scope, and never displayed again in plaintext. The platform does not read agent conversation content.

8. Lifecycle notes

Updates: pre-update backup, then deploy of the catalog-pinned target version; the official image runs startup-safe migrations (see `docs/updates.md`).

Backups: daily provider snapshots of the state volume, confirmed through the provider before "completed" (see `docs/backups.md`).

Secret rotation: a new gateway token is generated into the secret scope and re-applied; the old token stops working on redeploy.

9. Related documents

`docs/runtime-adapters.md` — the adapter contract behind this flow

`docs/sandboxing.md` — the isolation and safe-mode posture

`docs/ai-credit-system.md` — model access for agent runtimes