Skip to main content

​
Requirements

Node.js

Version 18 or higher required

Docker

Docker Engine 20.10+ and Docker Compose v2

Memory

Minimum 2GB RAM (8GB recommended for full stacks)

Disk space

At least 10GB free space for Docker images and volumes
You don’t need to install better-openclaw globally. Use npx to run it directly with the latest version.

​
Quick install

The recommended way to use better-openclaw is with npx: 
npx create-better-openclaw@latest
This automatically downloads and runs the latest version without requiring a global installation.

​
Verify prerequisites

1

Check Node.js version

Ensure you have Node.js 18 or higher:
node --version
If you need to install or update Node.js, visit nodejs.org or use a version manager like nvm:
# Using nvm
nvm install 18
nvm use 18
2

Check Docker installation

Verify Docker is installed and running:
docker --version
docker compose version
You should see Docker Engine 20.10+ and Docker Compose v2.
If you don’t have Docker installed, follow the official installation guide for your platform:
3

Verify Docker daemon is running

Test that Docker is working:
docker ps
If you see a list of running containers (or an empty list), Docker is ready.

​
Installation methods

Run better-openclaw without installation: 
npx create-better-openclaw@latest
This method always uses the latest version and requires no maintenance or updates.

​
Global installation

Install globally for repeated use: 
npm install -g create-better-openclaw
Then run with the shorter command: 
create-better-openclaw
# or
better-openclaw

​
Using pnpm

If you prefer pnpm: 
pnpm dlx create-better-openclaw@latest
Or install globally: 
pnpm install -g create-better-openclaw

​
Using yarn

With yarn: 
yarn dlx create-better-openclaw@latest

​
Shell completions

Enable tab completion for your shell: 
npx create-better-openclaw completion bash >> ~/.bashrc
source ~/.bashrc
After enabling completions, you can press Tab to autocomplete commands, service names, and preset IDs.

​
Bare-metal deployment

Better OpenClaw supports hybrid native + Docker deployments where supported services run directly on the host: 
npx create-better-openclaw \
  --preset devops \
  --deployment-type bare-metal \
  --platform linux/amd64 \
  --yes
1

Generate bare-metal stack

Use --deployment-type bare-metal to create native install scripts alongside docker-compose.yml.
2

Run the installer

Execute the generated installation script:
cd my-openclaw-stack
sudo ./install.sh
This installs native services (like Redis via apt/dnf) and starts remaining services with Docker.
3

Manage native services

Native services use systemd for management:
sudo systemctl status redis
sudo systemctl restart redis
Currently only Redis supports native Linux installation. More services may be added in future releases.

​
System resource guidelines

Plan your stack based on available resources:
Stack sizeRAMDiskUse case
Minimal (1-3 services)2 GB5 GBTesting and development
Small (4-10 services)4 GB10 GBSmall teams, specific workflows
Medium (11-20 services)8 GB20 GBProduction workloads, multiple teams
Large (21-40 services)16 GB40 GBComplete infrastructure, high availability
Full Stack (40+ services)32 GB80 GBEnterprise deployments, all features
These are estimates. Actual resource usage depends on service load, data volume, and concurrent users. Monitor your stack with Grafana and Prometheus (included in the DevOps preset).

​
GPU support for AI services

Enable GPU passthrough for AI services that support it (Ollama, Stable Diffusion, ComfyUI): 
npx create-better-openclaw \
  --services ollama,stable-diffusion \
  --gpu \
  --yes
1

Install NVIDIA Container Toolkit

For NVIDIA GPUs, install the container toolkit:
# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
2

Verify GPU access

Test GPU access in Docker:
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
You should see your GPU information displayed.
3

Generate stack with GPU support

Use the --gpu flag when generating your stack:
npx create-better-openclaw --preset ai-playground --gpu --yes
GPU support is added to docker-compose.yml automatically when using the --gpu flag. Services will use deploy.resources.reservations.devices to request GPU access.

​
Troubleshooting

​
Port conflicts

If you see port conflict errors: 
Error: Port 5432 is already in use
Better OpenClaw automatically detects and resolves port conflicts during generation. If you encounter conflicts after deployment:
  1. Check what’s using the port: 
    lsof -i :5432
  2. Stop the conflicting service or regenerate with custom ports: 
    npx create-better-openclaw \
  --services postgresql \
  --proxy-http-port 8080 \
  --yes

​
Docker permission errors

If you see permission denied errors: 
permission denied while trying to connect to the Docker daemon
Add your user to the docker group: 
sudo usermod -aG docker $USER
newgrp docker
Or run with sudo (not recommended for production).

​
Memory issues

If services are crashing or running slowly:
  1. Check Docker memory limits: 
    docker stats
  2. Increase Docker Desktop memory allocation (Mac/Windows):
    • Open Docker Desktop preferences
    • Navigate to Resources > Advanced
    • Increase memory allocation
  3. Use a smaller preset or fewer services: 
    npx create-better-openclaw --preset minimal --yes

​
Disk space issues

If you’re running low on disk space: 
# Remove unused Docker images
docker image prune -a

# Remove unused volumes
docker volume prune

# See disk usage
docker system df

​
Updating better-openclaw

If you installed globally, update to the latest version: 
npm update -g create-better-openclaw
Or just use npx with @latest to always get the newest version: 
npx create-better-openclaw@latest

​
Uninstalling

Remove global installation: 
npm uninstall -g create-better-openclaw
Clean up generated stacks: 
cd my-openclaw-stack
docker compose down -v  # Stops containers and removes volumes
cd ..
rm -rf my-openclaw-stack
The -v flag removes volumes, which permanently deletes all data in databases and persistent storage. Omit -v if you want to preserve data.

​
Next steps

Quick start guide

Generate your first OpenClaw stack with presets and interactive mode

Service catalog

Explore all 94 available services and their capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us