How to install the Clawdbot Gateway on a Cloud Instance with Docker

English

Technical guide for running the Clawdbot Gateway continuously with data persistence and safe restarts.

Objective

This article describes the procedure to install and run the Clawdbot Gateway continuously (24/7) on a Linux cloud instance, using Docker, ensuring data persistence and safe service restarts.

Target audience

This guide is intended for users who:

Run continuous workloads on cloud instances
Have basic knowledge of Linux and Docker
Need to operate the Clawdbot Gateway persistently
Must avoid loss of sessions, tokens, and authentication data

Solution architecture

The solution consists of:

A cloud instance created on LetsCloud or another provider of choice
Docker Engine
Docker Compose
Ephemeral Docker container
Persistent directories mounted on the host

The Docker container does not store permanent state.
All long-lived state is persisted on the cloud instance host.

Prerequisites

Linux cloud instance running Ubuntu or Debian
Root access via SSH
Docker and Docker Compose
Model authentication credentials
Optional provider tokens (WhatsApp, Telegram, Gmail)

1. Cloud instance provisioning

Create a Linux cloud instance running Ubuntu or Debian.

$
ssh root@INSTANCE_IP

2. Docker installation

$$$
apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh

$$
docker --version
docker compose version

3. Clawdbot repository clone

$$
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

4. Persistent host directories

$$$$
mkdir -p /root/.clawdbot
mkdir -p /root/clawd
chown -R 1000:1000 /root/.clawdbot
chown -R 1000:1000 /root/clawd

5. Environment variables configuration

Create the .env file at the project root:

CLAWDBOT_IMAGE=clawdbot:latest
CLAWDBOT_GATEWAY_TOKEN=change-me-now
CLAWDBOT_GATEWAY_BIND=lan
CLAWDBOT_GATEWAY_PORT=18789

CLAWDBOT_CONFIG_DIR=/root/.clawdbot
CLAWDBOT_WORKSPACE_DIR=/root/clawd

GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.clawdbot

6. Docker Compose configuration

services:
  clawdbot-gateway:
    image: ${CLAWDBOT_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - CLAWDBOT_GATEWAY_BIND=${CLAWDBOT_GATEWAY_BIND}
      - CLAWDBOT_GATEWAY_PORT=${CLAWDBOT_GATEWAY_PORT}
      - CLAWDBOT_GATEWAY_TOKEN=${CLAWDBOT_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
    volumes:
      - ${CLAWDBOT_CONFIG_DIR}:/home/node/.clawdbot
      - ${CLAWDBOT_WORKSPACE_DIR}:/home/node/clawd
    ports:
      - "127.0.0.1:${CLAWDBOT_GATEWAY_PORT}:18789"

7. External binaries in the Docker image

FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

8. Build and run

$$
docker compose build
docker compose up -d clawdbot-gateway

9. Gateway access

$
ssh -N -L 18789:127.0.0.1:18789 root@INSTANCE_IP

Access:

http://127.0.0.1:18789/

Data persistence (source of truth)

The Clawdbot Gateway runs inside Docker, but Docker is not the source of truth.

Component	Location	Persistence
Configuration	`/home/node/.clawdbot`	Host volume
Tokens / OAuth	`/home/node/.clawdbot`	Host volume
Skills	`/home/node/.clawdbot/skills`	Host volume
Workspace	`/home/node/clawd`	Host volume
External binaries	`/usr/local/bin`	Docker image

Final considerations

This procedure allows the Clawdbot Gateway to run on a cloud instance using Docker, with all persistent state stored outside the container and safe service restarts ensured.