Installation

Get GoClaw running on your machine in minutes. Four paths: quick binary install, bare metal, Docker (local), or Docker on a VPS.

Overview

GoClaw compiles to a single static binary (~25 MB). Pick the path that fits your setup:

Path	Best for	What you need
Quick Install (Binary)	Fastest single-command setup on Linux/macOS	curl, PostgreSQL
Bare Metal	Developers who want full control	Go 1.26+, PostgreSQL 15+ with pgvector
Docker (Local) ⭐	Run everything via Docker Compose (recommended)	Docker + Docker Compose, 2 GB+ RAM
VPS (Production)	Self-hosted production deployment	VPS $5+, Docker, 2 GB+ RAM

Path 1: Quick Install (Binary)

Download and install the latest pre-built GoClaw binary in one command. No Go toolchain required.

curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash

Supported platforms: Linux and macOS, both amd64 and arm64.

Options:

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash -s -- --version v1.30.0

# Install to a custom directory (default: /usr/local/bin)
curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash -s -- --dir /opt/goclaw

The script auto-detects your OS and architecture, downloads the matching release tarball from GitHub, and installs the binary. It uses sudo automatically if the target directory is not writable.

After install: set up PostgreSQL

# Start a PostgreSQL instance with pgvector (Docker is the easiest option)
docker run -d --name goclaw-pg \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=goclaw \
  pgvector/pgvector:pg18

Run the setup wizard

export GOCLAW_POSTGRES_DSN='postgres://postgres:goclaw@localhost:5432/postgres?sslmode=disable'
goclaw onboard

The wizard runs migrations, generates secrets, and saves everything to .env.local.

source .env.local && goclaw

Open the Dashboard

Pre-built binaries include the embedded Web UI — the dashboard is served directly at the gateway port. No separate UI process needed.

Open http://localhost:18790 and log in:

User ID: system
Gateway Token: found in .env.local (look for GOCLAW_GATEWAY_TOKEN)

After login, follow the Quick Start guide to add an LLM provider, create your first agent, and start chatting.

Alternative: run a separate dashboard UI

If you need to run the dashboard as a separate dev server (e.g. for UI development), clone the repo and run:

git clone https://github.com/nextlevelbuilder/goclaw.git
cd goclaw/ui/web
cp .env.example .env    # Required — configures backend connection
pnpm install
pnpm dev

Dashboard will be available at http://localhost:5173.

Tip: For the easiest all-in-one experience (gateway + database + dashboard), consider Path 3: Docker (Local) instead.

Path 2: Bare Metal

Install GoClaw directly on your machine. You manage Go, PostgreSQL, and the binary yourself.

Step 1: Install PostgreSQL + pgvector

GoClaw requires PostgreSQL 15+ with the pgvector extension (for vector similarity search in memory and skills). Docker deployments use PostgreSQL 18 with pgvector (pgvector/pgvector:pg18 image).

Ubuntu 24.04+ / Debian 12+

sudo apt update
sudo apt install -y postgresql postgresql-common

# Install pgvector (replace 17 with your PG version — check with: pg_config --version)
sudo apt install -y postgresql-17-pgvector

# Create database and enable extension
sudo -u postgres createdb goclaw
sudo -u postgres psql -d goclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

Note: Ubuntu 22.04 and older ship PostgreSQL 14, which is not supported. Please upgrade to Ubuntu 24.04+ or use the Docker installation path.

macOS (Homebrew)

brew install postgresql pgvector
brew services start postgresql
createdb goclaw
psql -d goclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

Fedora / RHEL

sudo dnf install -y postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

sudo dnf install -y postgresql-devel git make gcc
git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

sudo -u postgres createdb goclaw
sudo -u postgres psql -d goclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

Verify installation:

psql -d goclaw -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';"
# Should show: vector | 0.x.x

On Linux, prefix with sudo -u postgres if your user doesn't have direct database access.

Step 2: Clone & Build

git clone https://github.com/nextlevelbuilder/goclaw.git
cd goclaw
go build -o goclaw .
./goclaw version

Python runtime (optional): Some built-in skills require Python 3. Install it with sudo apt install -y python3 python3-pip (Ubuntu/Debian) or brew install python (macOS) if you plan to use those skills.

Build Tags (Optional): Enable extra features at compile time:

go build -tags embedui -o goclaw .           # Embed web UI in binary (serves dashboard at gateway port)
go build -tags otel -o goclaw .              # OpenTelemetry tracing
go build -tags tsnet -o goclaw .             # Tailscale networking
go build -tags redis -o goclaw .             # Redis caching
go build -tags "otel,tsnet" -o goclaw .      # Combine multiple

Step 3: Run Setup Wizard

./goclaw onboard

The wizard guides you through:

Database connection — enter host, port, database name, username, password (defaults work for typical local PostgreSQL)
Connection test — verifies PostgreSQL is reachable
Migrations — creates all required tables automatically
Key generation — auto-generates GOCLAW_GATEWAY_TOKEN and GOCLAW_ENCRYPTION_KEY
Seed providers — inserts placeholder provider records so the dashboard UI is ready on first login
Save secrets — writes everything to .env.local

Step 4: Start the Gateway

source .env.local && ./goclaw

Step 5: Open the Dashboard

If you built with the embedui tag, the dashboard is served directly at http://localhost:18790. Log in with:

User ID: system
Gateway Token: found in .env.local (look for GOCLAW_GATEWAY_TOKEN)

Without embedui, run the dashboard as a separate React dev server in a new terminal:

cd ui/web
cp .env.example .env    # Required — configures backend connection
pnpm install
pnpm dev

Open http://localhost:5173 and log in with the same credentials above.

After login, follow the Quick Start guide to add an LLM provider, create your first agent, and start chatting.

Path 3: Docker (Local)

Run GoClaw with Docker Compose — PostgreSQL and the web dashboard included. This is the recommended path for most users.

Note: This setup includes PostgreSQL automatically via docker-compose.postgres.yml. You don't need to install it separately.

Minimum RAM: 2 GB. The gateway, PostgreSQL, and dashboard containers together use ~1.2 GB at idle.

Step 1: Clone & Configure

git clone https://github.com/nextlevelbuilder/goclaw.git
cd goclaw

# Auto-generate encryption key + gateway token
./prepare-env.sh

Optionally add an LLM provider API key to .env now (or add it later via the dashboard):

GOCLAW_OPENROUTER_API_KEY=sk-or-xxxxx
# or GOCLAW_ANTHROPIC_API_KEY=sk-ant-xxxxx

Note: You do not need to run goclaw onboard for Docker — the onboard wizard is for bare metal only. Docker reads all configuration from .env and auto-runs migrations on startup.

Step 2: Start Services

GoClaw uses modular Docker Compose files:

docker-compose.yml — Core GoClaw gateway and API server (includes embedded Web UI by default)
docker-compose.postgres.yml — PostgreSQL database with pgvector extension
docker-compose.selfservice.yml — Optional: nginx reverse proxy + separate UI container at port 3000

The default docker-compose.yml sets ENABLE_EMBEDUI: true, so the dashboard is served directly at the gateway port (http://localhost:18790). You only need two files for a complete local setup:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  up -d --build

This starts:

GoClaw gateway + embedded dashboard — http://localhost:18790
PostgreSQL with pgvector — port 5432

GoClaw automatically runs pending database migrations on every start. No need to run goclaw onboard or goclaw migrate manually.

Open http://localhost:18790 and log in:

User ID: system
Gateway Token: found in .env (look for GOCLAW_GATEWAY_TOKEN)

Optional: nginx + separate UI (selfservice)

If you prefer a separate UI container at port 3000 (e.g. for nginx reverse proxy with a distinct UI port), add the selfservice overlay:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.selfservice.yml \
  up -d --build

Dashboard will be available at http://localhost:3000.

After login, follow the Quick Start guide to add an LLM provider, create your first agent, and start chatting.

Optional Add-ons

Add more capabilities with Docker Compose overlay files:

Overlay file	What it adds
`docker-compose.sandbox.yml`	Code sandbox for isolated script execution
`docker-compose.tailscale.yml`	Secure remote access via Tailscale
`docker-compose.otel.yml`	OpenTelemetry tracing (Jaeger UI on `:16686`)
`docker-compose.redis.yml`	Redis caching layer
`docker-compose.browser.yml`	Browser automation (Chrome sidecar)
`docker-compose.upgrade.yml`	Database upgrade service

Append any overlay with -f when starting services:

# Example: add Redis caching
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.redis.yml \
  up -d --build

Note: Redis and OTel overlays require rebuilding the GoClaw image with the corresponding build args (ENABLE_REDIS=true, ENABLE_OTEL=true). Set ENABLE_EMBEDUI=false to disable the embedded UI (e.g. when using the selfservice nginx overlay). See the overlay files for details.

Python runtime: The default docker-compose.yml builds GoClaw with ENABLE_PYTHON: "true", so Python-based skills work out of the box in Docker.

Privilege separation: The Docker image runs GoClaw as a non-root goclaw user (UID 1000). A separate pkg-helper binary runs as root to manage system (apk) package installs via a Unix socket (/tmp/pkg.sock), keeping the app process unprivileged. This is managed automatically by the docker-entrypoint.sh script.

Path 4: VPS (Production)

Deploy GoClaw on a VPS with Docker. Suitable for always-on, internet-accessible setups.

Note: PostgreSQL runs inside Docker. The compose file handles setup — you don't install it on the VPS system.

Requirements

VPS: 1 vCPU, 2 GB RAM minimum ($6 tier). 2 vCPU / 4 GB recommended for heavier workloads.
OS: Ubuntu 24.04+ or Debian 12+
Domain (optional): For HTTPS/SSL via reverse proxy

Step 1: Server Setup

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker (official script — includes Compose plugin)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group change to take effect

Step 2: Firewall

sudo apt install -y ufw
sudo ufw allow 22/tcp     # SSH
sudo ufw allow 80/tcp     # HTTP
sudo ufw allow 443/tcp    # HTTPS
sudo ufw --force enable

Step 3: Create Working Directory & Clone

sudo mkdir -p /opt/goclaw
sudo chown $(whoami):$(whoami) /opt/goclaw
git clone https://github.com/nextlevelbuilder/goclaw.git /opt/goclaw
cd /opt/goclaw

# Auto-generate secrets
./prepare-env.sh

Step 4: Start Services

The default compose includes the embedded Web UI. Two files are sufficient for a complete production setup:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  up -d --build

GoClaw automatically runs pending database migrations on every start. No need to run goclaw onboard or goclaw migrate manually.

The dashboard is available at http://localhost:18790.

Optional: To use nginx + a separate UI container at port 3000, add -f docker-compose.selfservice.yml. See the Optional: nginx + separate UI section in Path 3 for details.

Step 4.5: Verify Services Started

Before setting up reverse proxy, make sure everything is running:

docker compose ps
# Should show all services as "Up"

docker compose logs goclaw | grep "gateway starting"
# Should see: "goclaw gateway starting"

Step 5: Reverse Proxy with SSL

DNS setup: Create an A record pointing to your VPS IP:

Record	Type	Value
`yourdomain.com`	A	`YOUR_VPS_IP`

Caddy (Recommended):

sudo apt install -y caddy

Create /etc/caddy/Caddyfile:

yourdomain.com {
    reverse_proxy localhost:18790
}

Note: With ENABLE_EMBEDUI: true (default), both the dashboard and API/WebSocket are served from the same port (18790). If using docker-compose.selfservice.yml, point the dashboard domain to localhost:3000 instead.

sudo systemctl reload caddy

Caddy auto-provisions SSL certificates via Let's Encrypt.

Nginx:

sudo apt install -y nginx certbot python3-certbot-nginx

Create /etc/nginx/sites-available/goclaw:

server {
    server_name yourdomain.com;
    location / {
        proxy_pass http://localhost:18790;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Note: With ENABLE_EMBEDUI: true (default), all traffic (dashboard + API + WebSocket) goes through the single gateway port. If using docker-compose.selfservice.yml, configure a separate server block pointing to localhost:3000 for the UI and localhost:18790 for the WebSocket gateway.

sudo ln -s /etc/nginx/sites-available/goclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d yourdomain.com

Step 6: Backup (Recommended)

Add a daily PostgreSQL backup cron job:

sudo mkdir -p /backup
(crontab -l 2>/dev/null; echo "0 2 * * * cd /opt/goclaw && docker compose -f docker-compose.yml -f docker-compose.postgres.yml exec -T postgres pg_dump -U goclaw goclaw | gzip > /backup/goclaw-\$(date +\%Y\%m\%d).sql.gz") | crontab -

Updating to Latest Version

Already running GoClaw and want to upgrade? Follow the steps for your installation path.

Path 1: Quick Install (Binary)

Re-run the install script — it downloads the latest release and overwrites the existing binary:

curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash

Then upgrade the database schema:

source .env.local && goclaw upgrade

Tip: Run goclaw upgrade --status first to check if a schema upgrade is needed, or goclaw upgrade --dry-run to preview changes.

Path 2: Bare Metal

cd goclaw
git pull origin main
go build -o goclaw .
./goclaw upgrade

The goclaw upgrade command applies pending SQL migrations and runs data hooks. It is safe to run multiple times (idempotent).

Path 3 & 4: Docker (Local / VPS)

cd /path/to/goclaw     # or /opt/goclaw on VPS
git pull origin main
docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  up -d --build

GoClaw automatically runs pending migrations on startup — no manual goclaw upgrade needed.

Alternative: use the upgrade overlay for a one-shot database upgrade without restarting the gateway:

# Preview changes
docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml run --rm upgrade --dry-run

# Apply upgrade
docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
  -f docker-compose.upgrade.yml run --rm upgrade

Auto-upgrade on Startup

Set the GOCLAW_AUTO_UPGRADE environment variable to automatically run migrations when the gateway starts — useful for CI/CD and Docker deployments:

# .env or .env.local
GOCLAW_AUTO_UPGRADE=true

When enabled, GoClaw applies pending SQL migrations and data hooks inline during startup. If you prefer manual control, leave this unset and run goclaw upgrade yourself.

Troubleshooting Upgrades

Problem	Solution
`database schema is dirty`	A previous migration failed. Run `goclaw migrate force <version-1>` then `goclaw upgrade`
`schema is newer than this binary`	Your binary is older than your database. Update the binary first
`UPGRADE NEEDED` on gateway start	Run `goclaw upgrade` or set `GOCLAW_AUTO_UPGRADE=true`

Verify Installation

Works for all three paths:

# Health check
curl http://localhost:18790/health
# Expected: {"status":"ok"}

# Docker logs (Docker/VPS paths)
docker compose logs goclaw
# Look for: "goclaw gateway starting"

# Diagnostic check (bare metal)
./goclaw doctor

Common Issues

Problem	Solution
`go: module requires Go >= 1.26`	Update Go: `go install golang.org/dl/go1.26@latest`
`pgvector extension not found`	Run `CREATE EXTENSION vector;` in your goclaw database
Port 18790 already in use	Set `GOCLAW_PORT=18791` in `.env` (Docker) or `.env.local` (bare metal)
Docker build fails on ARM Mac	Enable Rosetta in Docker Desktop settings
`no provider API key found`	Add an LLM provider & API key through the Dashboard
`encryption key not set`	Run `./goclaw onboard` (bare metal) or `./prepare-env.sh` (Docker)
`Cannot connect to the Docker daemon`	Start Docker Desktop first: `open -a Docker` (macOS) or `sudo systemctl start docker` (Linux)

What's Next

Quick Start — Run your first agent
Configuration — Customize GoClaw settings

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Installation

Overview

Path 1: Quick Install (Binary)

After install: set up PostgreSQL

Run the setup wizard

Open the Dashboard

Path 2: Bare Metal

Step 1: Install PostgreSQL + pgvector

Step 2: Clone & Build

Step 3: Run Setup Wizard

Step 4: Start the Gateway

Step 5: Open the Dashboard

Path 3: Docker (Local)

Step 1: Clone & Configure

Step 2: Start Services

Optional Add-ons

Path 4: VPS (Production)

Requirements

Step 1: Server Setup

Step 2: Firewall

Step 3: Create Working Directory & Clone

Step 4: Start Services

Step 4.5: Verify Services Started

Step 5: Reverse Proxy with SSL

Step 6: Backup (Recommended)

Updating to Latest Version

Path 1: Quick Install (Binary)

Path 2: Bare Metal

Path 3 & 4: Docker (Local / VPS)

Auto-upgrade on Startup

Troubleshooting Upgrades

Verify Installation

Common Issues

What's Next

FilesExpand file tree

installation.md

Latest commit

History

installation.md

File metadata and controls

Installation

Overview

Path 1: Quick Install (Binary)

After install: set up PostgreSQL

Run the setup wizard

Open the Dashboard

Path 2: Bare Metal

Step 1: Install PostgreSQL + pgvector

Step 2: Clone & Build

Step 3: Run Setup Wizard

Step 4: Start the Gateway

Step 5: Open the Dashboard

Path 3: Docker (Local)

Step 1: Clone & Configure

Step 2: Start Services

Optional Add-ons

Path 4: VPS (Production)

Requirements

Step 1: Server Setup

Step 2: Firewall

Step 3: Create Working Directory & Clone

Step 4: Start Services

Step 4.5: Verify Services Started

Step 5: Reverse Proxy with SSL

Step 6: Backup (Recommended)

Updating to Latest Version

Path 1: Quick Install (Binary)

Path 2: Bare Metal

Path 3 & 4: Docker (Local / VPS)

Auto-upgrade on Startup

Troubleshooting Upgrades

Verify Installation

Common Issues

What's Next