Installation

godotz.ai ships as a single CLI binary installable via npm or Bun. The control plane (Postgres, Redis, Langfuse) runs in Docker and is optional for solo development but required for fleet deployments.

System Requirements

Note: godotz.ai runs without Docker in solo development mode. Docker is required only when you enable the full control plane (Redis caching, Langfuse tracing, Postgres audit logs).

Install the CLI

Via npm

npm install -g @omp/cli

Via Bun (recommended)

bun add -g @omp/cli

Bun is preferred because godotz.ai’s internal runtime is Bun-native. Installation is faster and the CLI starts ~3× quicker.

Verify Installation

omp --version
# omp/2.4.1 linux-x64 bun/1.2.3

API Key Prerequisites

godotz.ai requires at least one model provider key before running any swarm.

Store keys in environment variables. godotz.ai reads them from the shell environment at startup:

export ANTHROPIC_API_KEY="sk-ant-..."
export ZAI_API_KEY="..."
export GOOGLE_API_KEY="..."

Add these to your shell profile (~/.bashrc, ~/.zshrc) to persist across sessions.

Control Plane Setup (Optional)

The control plane adds Redis caching, Langfuse observability, and Postgres audit logs. Skip this section for your first run — godotz.ai works without it.

Start the Control Plane

omp infra up

This pulls and starts four containers:

• omp-postgres — LiteLLM audit log and budget data
• omp-redis — prompt cache (target hit rate: 40%+)
• omp-langfuse — LLM call tracing and cost tracking
• omp-litellm — model gateway proxy

Verify all containers are healthy:

omp infra status
# ✓ postgres    running  (healthy)
# ✓ redis       running  (healthy)
# ✓ langfuse    running  (healthy)  → http://localhost:3000
# ✓ litellm     running  (healthy)  → http://localhost:4000

Gateway Smoke Test

curl http://localhost:4000/health
# {"status":"healthy","version":"1.40.12"}

Fleet Node Setup (Multi-Machine)

For fleet deployments across heterogeneous nodes, each node needs:

1. Tailscale installed and authenticated — provides the encrypted WireGuard mesh
2. godotz.ai CLI installed at the same version across all nodes
3. Nix flake (optional but recommended) for bit-identical environments

Install Tailscale on each node:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --authkey=tskey-auth-...

Register the node with your godotz.ai fleet:

omp fleet add --name worker-01 --tags worker,gpu

Verify fleet connectivity:

omp fleet ping
# worker-01  12ms  ✓
# worker-02  18ms  ✓

Post-Install Verification

Run the built-in doctor to confirm your environment is fully operational:

omp doctor

Expected output for a healthy solo setup:

[✓] CLI version: 2.4.1
[✓] Bun runtime: 1.2.3
[✓] ANTHROPIC_API_KEY: set (sk-ant-...abc)
[✓] ZAI_API_KEY: set
[✗] Control plane: not running (optional — run `omp infra up` to enable)
[✓] Config file: ~/.config/omp/config.yml
[✓] Models reachable: anthropic/claude-sonnet-4-6 ✓, z.ai/glm-5.1 ✓

1 warning, 0 errors — ready for solo swarms

If the control plane is down, godotz.ai falls back to direct API calls without caching or tracing. This is acceptable for development but not for production.

Upgrading

# npm
npm update -g @omp/cli

# Bun
bun update -g @omp/cli

Check the changelog before upgrading between minor versions:

omp changelog

Uninstall

# npm
npm uninstall -g @omp/cli

# Bun
bun remove -g @omp/cli

# Remove config and data
rm -rf ~/.config/omp ~/.local/share/omp

# Stop and remove Docker containers
omp infra down --volumes

Next Steps

• Quick Start — Run your first 3-agent swarm in 5 minutes
• Configuration — Understand config.yml and model routing
• First Swarm — Write and run a swarm.yaml from scratch