Docker Is a Deployment Choice, Not a Security Claim

The official OpenClaw Docker guide describes Docker as optional. It is useful for:

  • a disposable or isolated Gateway runtime;
  • a VPS where installing the Node.js toolchain on the host is undesirable;
  • reproducible Compose operations;
  • running a supported Docker-backed Agent sandbox.

It does not automatically provide:

  • hostile multi-tenant isolation;
  • safe public exposure;
  • least-privilege model or channel credentials;
  • sandboxing for every Agent tool;
  • backup or rollback compatibility.

The Gateway container, the openclaw-cli sidecar, Agent tool sandboxes, model providers, and messaging channels cross different trust boundaries. A production design must address each one.

For protocol and permission boundaries, read the OpenClaw API guide. For the product-level trust model, use the complete OpenClaw guide.

Decide the Deployment Topology First

Use the smallest topology that meets the requirement.

Single Operator

One Gateway serves one operator or a mutually trusting team. Bind to loopback by default, administer through SSH or a private VPN, and expose only the channel connections the deployment requires.

Multiple Untrusted Tenants

Do not treat session keys or chat channels as tenant authorization. The official trust model does not position one Gateway as a hostile multi-tenant security boundary. Use one isolated cell per tenant or trust domain, with separate state, credentials, network policy, and resource quotas.

Gateway Container Plus Tool Sandbox

These are separate layers:

text 
host
  -> Gateway container
       -> model and channel egress
       -> optional sandbox backend
            -> ephemeral tool container

Containerizing the Gateway changes where the control plane runs. Enabling sandboxing changes where supported tool execution runs. Neither makes mounted credentials or unrestricted network egress harmless.

Prepare the Host

The documented prerequisites are Docker Engine or Docker Desktop plus Compose v2. A local source image build needs at least 6 GB of RAM; using a prebuilt image avoids that build requirement. Also budget disk for:

  • the Gateway image and optional browser/sandbox images;
  • persistent state and workspace data;
  • session records and indexes;
  • logs and diagnostic exports;
  • one full backup plus upgrade headroom.

On a public VPS, review firewall rules, including Docker's DOCKER-USER chain. Binding an application to 127.0.0.1 inside a container is not the same as restricting the published host port. Verify the effective listener from another machine.

Use an Official, Immutable Image

OpenClaw publishes release images primarily to GHCR and mirrors the same releases to Docker Hub:

text 
ghcr.io/openclaw/openclaw
openclaw/openclaw

Use a tested release tag during qualification, then capture its digest:

bash 
export OPENCLAW_RELEASE="<tested-release>"
docker pull "ghcr.io/openclaw/openclaw:${OPENCLAW_RELEASE}"
docker image inspect \
  --format '{{index .RepoDigests 0}}' \
  "ghcr.io/openclaw/openclaw:${OPENCLAW_RELEASE}"

Set OPENCLAW_IMAGE to the reviewed image reference before running the official setup flow:

bash 
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw@sha256:<reviewed-digest>"
./scripts/docker/setup.sh

Do not use an unofficial mirror. Do not promote a floating latest, main, or channel tag directly into production. A mutable tag cannot tell an incident responder which bytes were running.

Image variants have different contents. For example, browser variants include Chromium, while slim variants trade bundled components for size. Verify plugins, browser tooling, architecture support, signatures or provenance, and vulnerability policy for the exact variant.

Understand What the Setup Script Changes

The official setup script can:

  • build openclaw:local or use OPENCLAW_IMAGE;
  • synchronize the Compose .env;
  • prompt for provider credentials;
  • generate a Gateway token;
  • create required state and legacy auth-profile directories;
  • run onboarding and configuration writes;
  • start the Compose services.

This is convenient, but it is also a state-changing operation. Review the script from the pinned release, keep .env out of source control, and record which operator ran onboarding.

For an offline host, preload every required Gateway and sandbox image and use the documented --offline mode. A successful offline check should prove that all required images already exist; it should not silently pull from an unexpected registry.

Persist the Whole State Boundary

At minimum, preserve the configured OpenClaw state/config directory and workspace directory. Credentials, device identities, channel sessions, configuration, memory files, transcripts, indexes, task or flow state, and plugin data may not all live in one obvious file.

Use a backup inventory rather than guessing:

Data Why it matters Backup treatment
Gateway configuration listeners, auth, providers, tools encrypted, versioned
device and auth state paired identities and credentials encrypted, strict access
channel credentials messaging sessions and tokens encrypted, separately revocable
workspace instructions, memory, user files encrypted, retention by data class
session/task/flow state recovery and audit continuity consistent snapshot
Compose files and .env schema reproducible wiring secrets separated from templates
image digest and release notes binary identity and migration context deployment record

A backup is not proven until it restores into an isolated host and the Gateway can pass startup checks, list expected devices, read required state, and perform a harmless end-to-end test.

Do not back up only the workspace and assume the system is recoverable. Do not copy a live SQLite database without using a consistency method supported by the deployment.

Protect Secrets and Filesystem Permissions

The state directory should be treated as sensitive. It can contain provider credentials, channel sessions, transcripts, tool output, memory, and paired-device state.

Operational controls:

  • use a dedicated host account;
  • restrict ownership and mode on bind-mounted directories;
  • keep .env and backup archives outside the repository;
  • use full-disk encryption on shared or portable hosts;
  • prefer secret references or an external secret manager where supported;
  • rotate Gateway, provider, and channel credentials independently;
  • redact logs before export;
  • define deletion across live state, backups, indexes, and diagnostics.

Avoid broad host mounts. A read-write mount of the home directory turns a container escape or tool-policy failure into host-wide access. Mount only the paths needed for state and workspace, with read-only mode where possible.

Configure Network Exposure

The default Control UI is available on port 18789. Keep it on loopback or private ingress. For remote administration, prefer:

  • SSH local forwarding;
  • Tailscale or another authenticated private network;
  • a hardened reverse proxy only when its identity headers and trust configuration are correctly validated.

Never publish the Gateway unauthenticated. gateway.auth.mode: "none" is for private ingress and must stay off public or untrusted networks.

The CLI sidecar shares the Gateway network namespace so it can reach 127.0.0.1. Treat that as a shared trust boundary. Official Compose hardening such as dropped capabilities and no-new-privileges reduces risk, but it does not replace credential separation and command authorization.

Use the Three Probes Correctly

OpenClaw exposes distinct health endpoints:

bash 
curl --fail --silent http://127.0.0.1:18789/healthz
curl --fail --silent http://127.0.0.1:18789/startupz
curl --fail --silent http://127.0.0.1:18789/readyz
Probe Meaning Appropriate use
/healthz shallow process liveness process/container restart decision
/startupz startup and traffic-admission state startup gate and initial admission
/readyz deep, channel-aware readiness operator diagnosis and readiness policy

A disconnected optional channel may make deep readiness fail while the Gateway process remains healthy. If the orchestrator uses /readyz as liveness, one external provider outage can create a restart loop that destroys diagnostic evidence and increases load.

Alert on probe dimensions separately. Record which required capabilities define traffic readiness for this deployment instead of assuming every configured channel is equally critical.

Enable Agent Sandbox Deliberately

Sandboxing is off by default. It can be enabled for supported tools without putting the Gateway itself in Docker, and OpenClaw supports Docker, Podman, SSH, and OpenShell backends.

For the Docker setup flow:

bash 
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

With a rootless Docker socket:

bash 
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET="/run/user/1000/docker.sock"
./scripts/docker/setup.sh

The setup script mounts the Docker socket only after prerequisite checks. That socket gives the Gateway significant control over the Docker daemon, so compromise of the Gateway remains serious. Never mount the host Docker socket into an Agent sandbox container.

Sandbox review must include:

  • allowed tools and commands;
  • workspace visibility and mount mode;
  • network access and DNS;
  • environment variables and credentials;
  • process, memory, CPU, and time limits;
  • browser profile and download handling;
  • image provenance and patch cadence;
  • cleanup after cancellation or crash.

The official sandbox guide explicitly says sandboxing reduces blast radius but is not a perfect security boundary. Use the AI agent tool security guide to threat-model the complete path.

Day-to-Day Operations

Run Compose commands from the directory containing the deployment files, and use the same -f file set and order every time:

bash 
docker compose up -d openclaw-gateway
docker compose ps
docker compose logs -f openclaw-gateway
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli config get gateway
docker compose down

For non-interactive automation, disable pseudo-TTY allocation:

bash 
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

Collect bounded operational evidence:

  • image digest and configuration revision;
  • container restart count;
  • probe status by endpoint;
  • Gateway structured errors;
  • queue, model, channel, and tool latency;
  • disk growth and backup age;
  • device-pairing and approval changes;
  • sandbox creation, denial, timeout, and cleanup.

Do not export raw authorization headers, session content, provider keys, or unrestricted tool arguments.

Controlled Upgrade and Rollback

A safe upgrade is a data migration, not only an image pull.

Before the Upgrade

  1. Read release notes and documented migration warnings.
  2. Record current image digest, Compose files, environment schema, and plugin versions.
  3. Create a consistent encrypted snapshot of state and workspace.
  4. Restore that snapshot in a disposable environment.
  5. Test pairing, a read-only session, a harmless tool, a scheduled job, and probes.
  6. Pull and scan the candidate image by digest.

During the Upgrade

  1. Stop new high-impact work.
  2. Allow active Tasks and Flows to settle or record their recovery state.
  3. Deploy the candidate image with unchanged, reviewed Compose wiring.
  4. Check /startupz, then the deployment-specific readiness policy.
  5. Run protocol, channel, task, and sandbox smoke tests.
  6. Observe error rate, latency, restarts, disk writes, and outbound calls.

Rollback Rule

If the new release changed persistent state, do not merely switch the image tag backward. Restore the matching pre-upgrade state snapshot with the previous image and configuration. A new state format plus an old binary is not a valid rollback.

Document the point of no return before starting. If the release does not guarantee downgrade compatibility, rollback means full state restoration.

Production Gate

  • Official image pinned by digest.
  • Private ingress verified from outside the host.
  • Gateway auth enabled and device pairing tested.
  • Persistent directories inventoried, encrypted, and restored in a drill.
  • Probe roles mapped correctly.
  • Agent sandbox either explicitly off or configured and tested.
  • Host Docker socket absent from sandbox containers.
  • Tool and outbound network policies reviewed.
  • Resource and cost budgets enforced.
  • Upgrade and state-compatible rollback rehearsed.
  • Workflow behavior validated against the OpenClaw workflow guide.

Sources

Conclusion

A production OpenClaw Docker deployment is defined by controlled state, identity, ingress, probes, tool execution, and rollback—not by a successful docker compose up. Use official immutable images, keep the Gateway private, persist and test the complete state boundary, distinguish liveness from deep readiness, and enable Agent sandboxing as a separate reviewed control. Most importantly, roll back the binary and its compatible state together.