Skip to content

simple10/openclaw-stack

BranchesTags

Repository files navigation

OpenClaw VPS Stack

Automated deployment of OpenClaw stacks on a single VPS, orchestrated by Claude Code. Cloudflare Workers handle LLM proxying and log aggregation.

All provider API keys are kept safely off of the VPS and out of OpenClaw's reach. Each claw runs in an isolated container with its own resources and config.

What's Included

Quick Start

Option A: Guided setup (recommended)

# Interactive bash script clones the repo & sets up SSH access
# Then runs `claude "onboard"`
bash <(curl -fsSL https://raw.githubusercontent.com/simple10/openclaw-stack/main/install.sh)

Option B: Manual

git clone git@github.com:simple10/openclaw-stack.git openclaw-stack
cd openclaw-stack
cp .env.example .env && cp stack.yml.example stack.yml

# Edit .env and stack.yml with your values

# Run claude with "start" or "onboard"
# Both work - "onboard" does more hand-holding to help with configuring missing .env settings
claude "start" --dangerously-skip-permissions

# It's recommended to run claude with --dangerously-skip-permissions if you want
# an automated deployment. Otherwise claude will constantly require approval.

npm run pre-deploy builds .deploy/ from .env + stack.yml + docker-compose.yml.hbs. Claude reads the playbooks and executes them step-by-step over SSH. First deploy takes ~30 minutes.

Requirements

  • Claude Code — Pro/Max subscription
  • VPS — Ubuntu 24.04+, kernel 5.12+, minimum 4 GB RAM / 2 vCPUs (8 GB+ / 4+ recommended)
  • Cloudflare account — (free tier) with a domain managed in Cloudflare DNS

Features

Mission Control — agent browsers, cost tracking, and gateway stats

Mission Control Dashboard

Easy Browser Access

  • Each agent gets its own browser sandbox
  • Access the browser via noVNC in the dashboard
  • Easy management of browser auth - just login to a site in the agent browser
  • OpenClaw never needs your website credentials

Host Alerter — daily health summary and real-time alerts via Telegram

Host Alerter Telegram Report

Local Browser Relay — docker container to run OpenClaw relay & local browsers

Local Browser Automation Relay

  • Multi-claw Stacks — Run multiple OpenClaw instances on one VPS, each in its own Sysbox container with dedicated resources, Telegram bot, and subdomain
  • AI Gateway Proxy — Cloudflare Worker proxies LLM requests to Anthropic/OpenAI with per-user KV credentials. API keys never touch the VPS. Self-service /config UI for credential management
  • LLM Observability — Structured logging via Vector to Cloudflare Workers, with optional Langfuse tracing for cost and latency analysis
  • Egress Proxy — Optional sidecar that routes requests through the VPS IP to bypass WAF blocks on Cloudflare Worker IPs (e.g., ChatGPT Codex)
  • Claude-driven Deployment & Maintenance — Modular playbooks that Claude Code executes step-by-step. First deploy ~30 minutes, mostly hands-off
  • Local Browser Relay - docker compose with support for KasmWeb, noVNC, and local browser relay

Architecture

This project deploys OpenClaw stacks to a VPS or dedicated server.

Multiple stacks can run on the same VPS. Each stack can contain multiple claws.

                       Cloudflare
                           |
          +----------------+----------------+
          |                |                |
      Tunnel          AI Gateway       Log Receiver
      (HTTPS)         Worker           Worker
          |           (LLM proxy)      (log ingest)
          v               ^                ^
  +---------------------------------------------------+
  |  VPS — OpenClaw Stack (docker compose)            |
  |                                                   |
  |  +-- openclaw-claw (Sysbox) -----------------+    |
  |  |  Gateway process           :18789         |    |
  |  |  Dashboard                 :6090          |    |
  |  |  Nested Docker daemon                     |    |
  |  |    -> sandbox containers (per agent)      |    |
  |  |    -> browser container  (noVNC)          |    |
  |  +-------------------------------------------+    |
  |  +-- openclaw-* (optional) ------------------+    |
  |  |  Run any number of additional             |    |
  |  |  claws via stack.yml                      |    |
  |  +-------------------------------------------+    |
  |                                                   |
  |  cloudflared        tunnel connector              |
  |  host-alert.sh      cron monitoring               |
  |  egress-proxy       WAF bypass (optional)         |
  |  vector             docker log shipper (optional) |
  |  sandbox-registry   local docker hub (optional)   |
  +---------------------------------------------------+
  • All claws in the stack are isolated from each other in their own docker container.
  • Sysbox manages permissions & enables OpenClaw to efficiently spawn agent sandbox containers.
  • No ports are exposed to the public internet.
  • All traffic flows through the Cloudflare Tunnel (outbound-only). SSH is the only open firewall port.
  • LLM provider API keys are stored as Cloudflare KV secrets and injected at the edge.
  • Optional sandbox-registry shares base sandbox images to speed up per-claw build time.

Configuration

Two config files plus a Handlebars template:

File Purpose Gitignored
.env Secrets & VPS access Yes
stack.yml Stack structure, claw definitions, defaults Yes
docker-compose.yml.hbs Compose template No

Create from examples: cp .env.example .env && cp stack.yml.example stack.yml

Build deployment artifacts: npm run pre-deploy (or npm run pre-deploy:dry to preview)

Day-to-Day Operations

Just use OpenClaw normally. Host alerts notify you via Telegram if something needs attention. Use Claude to troubleshoot or make changes:

claude

Update OpenClaw to the latest version

Run the verification tests

Show me the gateway logs

Help me pair a new browser with the gateway

Helper Scripts

Local CLI scripts for common tasks without Claude:

# Deployment
./scripts/deploy.sh                    # Full deploy: build + sync + restart
./scripts/sync-claw-config.sh <claw>   # Quick config push + restart for one claw

# SSH access
./scripts/ssh-vps.sh                   # SSH to VPS host
./scripts/ssh-openclaw.sh              # Shell into gateway container
./scripts/ssh-agent.sh                 # Shell into agent sandbox

# Logs & monitoring
./scripts/logs-openclaw.sh             # Stream gateway logs
./scripts/logs-docker.sh               # Stream all container logs
./scripts/logs-explorer.sh             # TUI for session & LLM logs
./scripts/health-check.sh              # Docker and gateway health

# Updates
./scripts/update-openclaw.sh           # Pull latest + rebuild gateway
./scripts/update-sandbox-toolkit.sh    # Sync toolkit + rebuild sandbox images

# Services
./scripts/restart-gateway.sh           # Restart gateway container
./scripts/restart-sandboxes.sh         # Recreate sandbox containers
./scripts/start-browser.sh             # Start browser container

# Agents
./scripts/message-agents.sh <claw> "msg"  # Message all agents (seeds files too)

# Data & config
./scripts/openclaw.sh <command>        # Run openclaw CLI via SSH
./scripts/sync-media.sh               # Download agent media files
./scripts/sync-workspaces.sh <up|down> # Bidirectional workspace sync

See docs/SCRIPTS.md for full flags and options.

Updating OpenClaw

# Via Claude:
claude "Update OpenClaw to the latest version"

# Or directly:
./scripts/update-openclaw.sh

Updates pull the latest source and rebuild the gateway Docker image with auto-patching.

Managing Sandbox Tools

Tools available inside agent sandboxes are defined in openclaw/default/sandbox-toolkit.yaml. Adding a tool is a one-line YAML edit + scripts/update-sandbox-toolkit.sh. See docs/SANDBOX-TOOLKIT.md.

Documentation

Guide Description
VPS Setup Guide VPS provisioning (OVHCloud example, any provider works)
Cloudflare Tunnel Tunnel, Access, and domain routing setup
AI Gateway Config LLM proxy configuration and provider credentials
Dashboard Browser sessions (noVNC), media files, URL routing
Scripts Reference CLI scripts — full flags and options
Sandbox Toolkit Adding and managing sandbox tools
Telegram Telegram bot setup for chat and host alerts
Claude Subscription Using Claude Code subscription tokens with OpenClaw
Codex Subscription Using OpenAI Codex subscription tokens with OpenClaw
Security Full security model: network, auth, device pairing, containers
Testing End-to-end verification (SSH + browser via DevTools MCP)

Security Overview

Defense-in-depth with multiple independent layers:

  • Zero exposed ports — Cloudflare Tunnel (outbound-only), SSH on non-standard port only
  • Two-user model — adminclaw (SSH/admin with sudo) and openclaw (app runtime, no SSH, no sudo)
  • SSH hardened — key-only auth, fail2ban, modern ciphers, all forwarding disabled
  • Sysbox containers — secure Docker-in-Docker without --privileged, uid remapping
  • Sandboxes — read-only root, all capabilities dropped, no network (default), PID/memory/CPU limits
  • API key isolation — LLM keys in Cloudflare KV, never on the VPS
  • Cloudflare Access — identity-based auth before traffic reaches the VPS
  • Device pairing — Ed25519 challenge-response protocol for gateway access

See docs/SECURITY.md for the full threat model, cryptographic inventory, and protocol details.

Testing

claude "Run the tests in docs/TESTING.md using devtools mcp"

Requires DevTools MCP installed in Claude Code.

Reference

About

Deploy a secure OpenClaw to any VPS using Claude Code.

Resources

Readme

License

View license

Security policy

Security policy
Activity

Stars

8 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages