Skip to main content
Bare-metal deployment is a hybrid native + Docker approach: services with native install recipes run directly on the host, while others remain containerized. This reduces overhead and improves performance for critical services.

​
How it works

better-openclaw generates:
  1. docker-compose.yml — For services without native recipes
  2. native/ directory — Install and run scripts for each platform
  3. install.sh (Linux/macOS) or install.ps1 (Windows) — Top-level orchestrator
The installer:
  • Installs native services (e.g., Redis via apt/dnf, configured with systemd)
  • Starts native services
  • Launches remaining services via docker compose up

​
Supported services

Currently, only Redis has a native Linux recipe (apt/dnf + systemd). More services (PostgreSQL, Caddy, Prometheus) may be added over time. Services without native recipes remain Docker-only:
  • Node.js/Python apps (n8n, LibreChat, etc.)
  • La Suite Meet
  • Ollama
  • All AI/ML services

​
Prerequisites

​
Linux

  • Ubuntu 20.04+ / Debian 11+ / RHEL 8+ / Fedora 35+
  • Docker Engine 20.10+ (for containerized services)
  • sudo privileges
  • systemd (for service management)

​
macOS

  • macOS 12+ (Monterey)
  • Docker Desktop
  • Homebrew
  • sudo privileges

​
Windows

  • Windows 10/11 with WSL2
  • Docker Desktop
  • PowerShell 7+
  • Administrator privileges

​
Deployment steps

1

Generate a bare-metal stack

Use the --deployment-mode bare-metal flag:
npx create-better-openclaw@latest --preset researcher --deployment-mode bare-metal
This generates:
  • docker-compose.yml — Docker-only services + OpenClaw gateway
  • native/install-linux.sh — Native install script for Linux
  • native/run-linux.sh — Start native services
  • install.sh — Top-level installer
  • .env — Environment variables
2

Review the configuration

Inspect which services will run natively:
cat native/install-linux.sh
Check the Docker Compose file for remaining services:
cat docker-compose.yml
3

Run the installer

Execute the top-level installer with sudo:Linux/macOS:
chmod +x install.sh
sudo ./install.sh
Windows (PowerShell):
Set-ExecutionPolicy Bypass -Scope Process
.\install.ps1
The installer will:
  1. Detect your platform (Linux/macOS/Windows)
  2. Install native services (Redis via package manager)
  3. Configure systemd units (Linux) or launchd (macOS)
  4. Start native services
  5. Launch docker compose up -d for remaining services
4

Verify services

Check native services:Linux:
systemctl status redis
macOS:
brew services list
Check containerized services:
docker compose ps

​
Service management

​
Native services (Linux)

Redis example: 
# Status
systemctl status redis

# Start
sudo systemctl start redis

# Stop
sudo systemctl stop redis

# Restart
sudo systemctl restart redis

# Enable on boot
sudo systemctl enable redis

# Disable on boot
sudo systemctl disable redis

# View logs
journalctl -u redis -f

​
Native services (macOS)

Redis example: 
# Status
brew services list

# Start
brew services start redis

# Stop
brew services stop redis

# Restart
brew services restart redis

# View logs
tail -f /usr/local/var/log/redis.log

​
Containerized services

Use standard Docker Compose commands: 
# Status
docker compose ps

# Logs
docker compose logs -f

# Restart
docker compose restart

# Stop
docker compose stop

# Start
docker compose up -d

​
Production considerations

​
Firewall rules

Configure firewall rules for native services: Linux (ufw): 
# Allow Redis (if remote access needed)
sudo ufw allow 6379/tcp
Linux (firewalld): 
# Allow Redis
sudo firewall-cmd --permanent --add-port=6379/tcp
sudo firewall-cmd --reload

​
Resource limits

For native services, configure limits via systemd: 
# Edit Redis systemd unit
sudo systemctl edit redis
Add limits: 
[Service]
MemoryLimit=1G
CPUQuota=200%
Reload and restart: 
sudo systemctl daemon-reload
sudo systemctl restart redis

​
Security hardening

​
Redis (Linux)

Edit /etc/redis/redis.conf: 
# Bind to localhost only
bind 127.0.0.1

# Require authentication
requirepass your_strong_password

# Disable dangerous commands
rename-command FLUSHDB ""
rename-command FLUSHALL ""
rename-command CONFIG ""
Restart Redis: 
sudo systemctl restart redis

​
Backups

​
Redis (Linux)

Redis automatically saves to /var/lib/redis/dump.rdb. Back up regularly: 
# Backup Redis data
sudo cp /var/lib/redis/dump.rdb /backup/redis-$(date +%F).rdb
Automate with cron: 
# Add to crontab
0 2 * * * sudo cp /var/lib/redis/dump.rdb /backup/redis-$(date +\%F).rdb

​
Uninstalling

1

Stop Docker services

docker compose down -v
2

Remove native services

Linux (Redis):
sudo systemctl stop redis
sudo systemctl disable redis
sudo apt remove redis-server  # or sudo dnf remove redis
macOS (Redis):
brew services stop redis
brew uninstall redis
3

Remove data directories

Linux:
sudo rm -rf /var/lib/redis
sudo rm -rf /var/log/redis
macOS:
rm -rf /usr/local/var/db/redis
rm -rf /usr/local/var/log/redis.log

​
Platform-specific notes

​
Ubuntu/Debian

Redis installed via: 
sudo apt update
sudo apt install -y redis-server
Configuration: /etc/redis/redis.conf Data directory: /var/lib/redis Logs: /var/log/redis/redis-server.log

​
RHEL/Fedora

Redis installed via: 
sudo dnf install -y redis
Configuration: /etc/redis/redis.conf Data directory: /var/lib/redis Logs: journalctl -u redis

​
macOS

Redis installed via: 
brew install redis
Configuration: /usr/local/etc/redis.conf Data directory: /usr/local/var/db/redis Logs: /usr/local/var/log/redis.log

​
Migrating to Docker

If you want to migrate a native service back to Docker:
1

Stop the native service

Linux:
sudo systemctl stop redis
sudo systemctl disable redis
macOS:
brew services stop redis
2

Export data

Redis:
# Trigger a save
redis-cli SAVE

# Copy dump.rdb
sudo cp /var/lib/redis/dump.rdb ./redis-data/
3

Update docker-compose.yml

Add the service back to docker-compose.yml:
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  redis-data:
4

Start Docker container

docker compose up -d redis

​
Troubleshooting

​
Native service won’t start

Check service logs: Linux: 
journalctl -u redis -n 50
macOS: 
tail -f /usr/local/var/log/redis.log

​
Port conflicts

If a native service conflicts with a Docker container, stop the native service: 
sudo systemctl stop redis  # Linux
brew services stop redis   # macOS
Then regenerate the stack with custom ports: 
npx create-better-openclaw --preset researcher --deployment-mode bare-metal --redis-port 6380

​
Permission errors

Ensure proper permissions for data directories: Linux: 
sudo chown -R redis:redis /var/lib/redis
sudo chmod 750 /var/lib/redis
macOS: 
sudo chown -R $(whoami):admin /usr/local/var/db/redis
chmod 750 /usr/local/var/db/redis

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us