Deployment types

better-openclaw supports two deployment modes: Docker (all services containerized) and bare-metal (hybrid native + Docker). Choose the mode that fits your infrastructure and performance requirements.

Docker deployment (default)

In Docker mode, all services run in containers managed by Docker Compose.

Docker deployment is the default and recommended mode for most users.

How it works

When you generate a stack, you get:

docker-compose.yml: Defines all services, networks, and volumes
.env: Environment variables with secrets
Caddy/Traefik config: Reverse proxy rules for HTTPS
Skills: Agent skill files with service connection details

Starting your stack

docker compose up -d

All services start in isolated containers with:

Automatic networking via Docker bridge
Volume persistence for data
Health checks for readiness
Automatic restarts on failure

Advantages of Docker deployment

Isolation

Each service runs in its own container with resource limits and security boundaries.

Portability

Works identically on any platform (Linux, macOS, Windows) with Docker installed.

Easy updates

Update services by changing image tags and running docker compose pull.

Clean removal

Remove the entire stack with docker compose down -v without affecting your system.

When to use Docker

Use Docker deployment when:

You want maximum portability across environments
You’re deploying to cloud VMs, Kubernetes, or PaaS platforms
You need isolated environments for testing
You’re new to OpenClaw and want quick setup

Bare-metal deployment (hybrid)

In bare-metal mode, services that support native installation run directly on the host, while others remain in Docker.

Bare-metal deployment is experimental. Only a few services currently support native installation.

How it works

When you generate a bare-metal stack, you get:

docker-compose.yml: Services that don’t support native installation
native/: Directory with native install and run scripts
- install-linux.sh: Installs native services (apt/dnf packages, systemd units)
- start-linux.sh: Starts native services
- stop-linux.sh: Stops native services
install.sh: Top-level installer that runs native install, then Docker Compose
.env: Shared environment variables for both native and Docker services

Deployment flow

Run installer

./install.sh

Native services installed

The script installs native services (e.g., Redis via apt/dnf) and configures systemd units.

Native services started

systemctl starts native services on the host.

Docker services started

docker compose up -d starts remaining services in containers.

OpenClaw gateway connected

The OpenClaw gateway (running in Docker) connects to both native and Docker services.

Supported native services

Currently, only Redis supports native installation on Linux:

nativeSupported: true,
nativeRecipes: [
  {
    platform: "linux",
    installSteps: [
      "command -v redis-server || (apt-get update && apt-get install -y redis-server)",
      "command -v redis-server || (dnf install -y redis)",
    ],
    startCommand: "systemctl start redis-server",
    stopCommand: "systemctl stop redis-server",
    configPath: "/etc/redis/redis.conf",
    configTemplate: "port 6379\nrequirepass ${REDIS_PASSWORD}\n",
    systemdUnit: "redis-server",
  },
],

More services (PostgreSQL, Caddy, Prometheus) may support native installation in future releases.

Advantages of bare-metal

Performance

Native services avoid Docker networking overhead and use host resources directly.

Integration

Services integrate with system tools (systemd, logrotate, monitoring agents).

Resource efficiency

No container overhead for memory and CPU.

System consistency

Services use the same package manager, config paths, and logs as other host services.

When to use bare-metal

Use bare-metal deployment when:

You’re deploying to a dedicated server with root access
You need maximum performance for high-throughput services (databases, caches)
You want to integrate with existing system monitoring (Prometheus node_exporter, etc.)
You prefer traditional system administration tools

Limitations

Platform-specific: Native recipes are Linux-only (no macOS/Windows support yet)
Fewer services: Only services with native recipes run natively; the rest use Docker
Manual management: Native services require systemctl commands for start/stop/restart
Harder cleanup: Uninstalling requires removing packages and config files manually

Comparing deployment types

Feature	Docker	Bare-metal
Portability	✅ Cross-platform	⚠️ Linux-only
Setup time	✅ Instant	⚠️ Requires package install
Performance	⚠️ Networking overhead	✅ Native performance
Isolation	✅ Full container isolation	⚠️ Shared host resources
Updates	✅ Change image tag	⚠️ Manual package upgrade
Cleanup	✅ `docker compose down -v`	⚠️ Manual package removal
Service support	✅ All 94 services	⚠️ Only Redis (more coming)

Selecting deployment type

Interactive CLI
Non-interactive CLI
REST API
Web UI

The wizard asks which deployment type you want:

npx create-better-openclaw
# Choose "Docker" or "Bare-metal" when prompted

Use the --deployment-type flag:

# Docker (default)
npx create-better-openclaw --preset devops --yes

# Bare-metal
npx create-better-openclaw --preset devops --deployment-type bare-metal --yes

Specify deploymentType in the request:

curl -X POST http://localhost:3456/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "devops",
    "deploymentType": "bare-metal"
  }'

Hybrid architecture example

Here’s how a bare-metal DevOps stack is structured:

my-devops-stack/
├── docker-compose.yml        # n8n, Grafana, Uptime Kuma (Docker)
├── .env                      # Shared secrets
├── native/
│   ├── install-linux.sh      # Install Redis, PostgreSQL, Prometheus (native)
│   ├── start-linux.sh        # Start native services
│   ├── stop-linux.sh         # Stop native services
│   └── configs/
│       ├── redis.conf        # Redis config with generated password
│       └── prometheus.yml    # Prometheus config
├── install.sh                # Top-level installer
└── skills/                   # OpenClaw skills (same for both modes)

Native services (on host):

Redis (systemd: redis-server.service)
PostgreSQL (systemd: postgresql.service)
Prometheus (systemd: prometheus.service)

Docker services:

n8n (workflow automation)
Grafana (dashboards)
Uptime Kuma (uptime monitoring)
OpenClaw gateway (agent orchestration)

Port management

better-openclaw automatically detects port conflicts on your system:

Docker mode: Checks for ports in use by other containers or host services
Bare-metal mode: Checks for ports used by systemd services and running processes

If a conflict is detected, the generator reassigns the service to an available port.

You can override ports with --proxy-http-port and --proxy-https-port flags.

Network communication

Docker mode

All services communicate via Docker’s bridge network:

networks:
  openclaw-network:
    driver: bridge

services:
  redis:
    networks:
      - openclaw-network
  n8n:
    networks:
      - openclaw-network
    environment:
      - REDIS_HOST=redis  # Service name resolves to container IP

Bare-metal mode

Native services listen on localhost or the host IP. Docker services connect via host.docker.internal:

services:
  n8n:
    environment:
      - REDIS_HOST=host.docker.internal  # Host-to-Docker communication
      - REDIS_PORT=6379

Future enhancements

Planned improvements for bare-metal deployment:

More native recipes: PostgreSQL, Caddy, Prometheus, Ollama
macOS support: Homebrew-based native installation
Windows support: Chocolatey or native installers
Kubernetes hybrid mode: Native services on nodes, containerized services in pods

Contribute

Help us add native recipes for more services

Get Started

Core Concepts

CLI Guide

Configuration

Deployment

Guides

Docker deployment (default)

How it works

Starting your stack

Advantages of Docker deployment

Isolation

Portability

Easy updates

Clean removal

When to use Docker

Bare-metal deployment (hybrid)

How it works

Deployment flow

Supported native services

Advantages of bare-metal

Performance

Integration

Resource efficiency

System consistency

When to use bare-metal

Limitations

Comparing deployment types

Selecting deployment type

Hybrid architecture example

Port management

Network communication

Docker mode

Bare-metal mode

Future enhancements

Contribute

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Guide

Configuration

Deployment

Guides

​Docker deployment (default)

​How it works

​Starting your stack

​Advantages of Docker deployment

Isolation

Portability

Easy updates

Clean removal

​When to use Docker

​Bare-metal deployment (hybrid)

​How it works

​Deployment flow

​Supported native services

​Advantages of bare-metal

Performance

Integration

Resource efficiency

System consistency

​When to use bare-metal

​Limitations

​Comparing deployment types

​Selecting deployment type

​Hybrid architecture example

​Port management

​Network communication

​Docker mode

​Bare-metal mode

​Future enhancements

Contribute

Build docs developers (and LLMs) love

Docker deployment (default)

How it works

Starting your stack

Advantages of Docker deployment

When to use Docker

Bare-metal deployment (hybrid)

How it works

Deployment flow

Supported native services

Advantages of bare-metal

When to use bare-metal

Limitations

Comparing deployment types

Selecting deployment type

Hybrid architecture example

Port management

Network communication

Docker mode

Bare-metal mode

Future enhancements