Ubuntu Server Setup

This guide walks through setting up a clean Ubuntu server to run ClawHalla. While ClawHalla runs inside Docker, having a well-configured host makes development, debugging, and management much smoother.

Recommended OS: Ubuntu 24.04 LTS (server or desktop)

System Preparation

Update the system
Terminal window
```
sudo apt update && sudo apt upgrade -y
```

Install essential packages

sudo apt install -y \
  git \
  curl \
  wget \
  build-essential \
  ca-certificates \
  gnupg \
  lsb-release \
  htop \
  jq \
  unzip

Install Zsh and Oh My Zsh

A comfortable shell environment makes working with ClawHalla much more productive.

Install zsh
Terminal window
```
sudo apt install -y zsh
```

Install Oh My Zsh

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

When prompted, set zsh as your default shell.

Install Spaceship theme

git clone https://github.com/spaceship-prompt/spaceship-prompt.git \
  "$HOME/.oh-my-zsh/custom/themes/spaceship-prompt" --depth=1

ln -s "$HOME/.oh-my-zsh/custom/themes/spaceship-prompt/spaceship.zsh-theme" \
  "$HOME/.oh-my-zsh/custom/themes/spaceship.zsh-theme"

Install Zinit plugin manager

mkdir -p "$HOME/.zinit"
git clone https://github.com/zdharma-continuum/zinit "$HOME/.zinit/bin" --depth=1

Configure .zshrc

Replace or edit ~/.zshrc with the following configuration:

export ZSH="$HOME/.oh-my-zsh"
ZSH_THEME="spaceship"

plugins=(git docker node npm)

source $ZSH/oh-my-zsh.sh

# Spaceship prompt configuration
SPACESHIP_PROMPT_ORDER=(
  time user host dir git node exec_time
  line_sep char
)
SPACESHIP_TIME_SHOW="true"
SPACESHIP_DIR_TRUNC="4"
SPACESHIP_USER_SHOW=always
SPACESHIP_PROMPT_ADD_NEWLINE=false
SPACESHIP_CHAR_SUFFIX=" "
SPACESHIP_USER_COLOR=yellow

# Zinit plugins
if [[ -f "$HOME/.zinit/bin/zinit.zsh" ]]; then
  source "$HOME/.zinit/bin/zinit.zsh"
  zinit light zdharma-continuum/fast-syntax-highlighting
  zinit light zsh-users/zsh-autosuggestions
  zinit light zsh-users/zsh-completions
fi

# NVM (if installed on host)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# pnpm
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

# ClawHalla aliases
alias ll='ls -la --color=auto'
alias la='ls -A --color=auto'
alias oc='openclaw'
alias mc='cd ~/mission-control && pnpm dev'
alias gw='openclaw gateway'
alias agents='openclaw agent list'
alias crons='openclaw cron list'
alias logs='tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log'

# Docker aliases
alias dc='docker compose'
alias dcup='docker compose up -d'
alias dcdown='docker compose down'
alias dcps='docker compose ps'
alias dclogs='docker compose logs -f'
alias claw='docker compose exec clawhalla zsh'

Install Docker

Install Docker Engine and Compose plugin

sudo apt install -y docker.io docker-compose-plugin

Add your user to the docker group (to avoid sudo for every command)
Terminal window
```
sudo usermod -aG docker $USER
```
Log out and back in (or run newgrp docker) for this to take effect.
Verify Docker is working
Terminal window
```
docker info
docker compose version
```

Install Node.js 24 (Host)

While ClawHalla runs Node inside Docker, having Node on the host is useful for development and running Mission Control outside the container.

Install NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.zshrc

Install Node 24
Terminal window
```
nvm install 24
nvm alias default 24
```
Enable pnpm via Corepack
Terminal window
```
corepack enable pnpm
```

Verify

node --version    # v24.x.x
pnpm --version    # 9.x.x or later

Firewall Setup

If your server is exposed to the internet, configure the firewall to allow only necessary ports.

# Enable UFW
sudo ufw enable

# Allow SSH (important -- do this first!)
sudo ufw allow 22/tcp

# Allow Mission Control
sudo ufw allow 3000/tcp

# Allow OpenClaw Gateway
sudo ufw allow 18789/tcp

# Check status
sudo ufw status

Recommended: use Tailscale instead

For remote access without opening ports to the public internet, use Tailscale:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Then access your services via Tailscale IPs. No firewall rules needed.

Install ClawHalla

With the server prepared, install ClawHalla:

cd ~
git clone https://github.com/deegalabs/clawhalla.git
cd clawhalla
cp .env.example .env
# Edit .env with your keys
nano .env
bash scripts/start.sh

Then follow the Installation guide from step 4 onward.

Production Recommendations

Auto-start on boot

Create a systemd service for Docker Compose:

[Unit]
Description=ClawHalla
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/youruser/clawhalla
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
User=youruser
Group=docker

[Install]
WantedBy=multi-user.target

sudo systemctl enable clawhalla
sudo systemctl start clawhalla

Log rotation

Docker logs can grow large. Configure rotation in /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

Restart Docker after changes:

sudo systemctl restart docker

Backups

Back up the volumes directory regularly:

# Manual backup
tar -czf clawhalla-backup-$(date +%Y%m%d).tar.gz ~/clawhalla/volumes/

# Cron job (daily at 3 AM)
echo "0 3 * * * tar -czf /backups/clawhalla-$(date +\%Y\%m\%d).tar.gz /home/youruser/clawhalla/volumes/" | crontab -

Monitoring

Keep an eye on resource usage:

# Container stats
docker stats clawhalla

# Disk usage
df -h

# Memory
free -h