# getbot Manual Install Guide

**Your server's OS is not supported by getbot's automated bootstrap.** The `getbot` CLI cannot install Incus, Caddy, or configure networking on this operating system. You must prepare the server manually using the steps below. Once the server is prepared, `getbot setup` will detect the existing infrastructure and deploy your bot normally.

> **Supported for automated bootstrap:** Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, Debian stable (Bookworm), Debian testing (Trixie). If you are on one of these, use `getbot setup` instead — it handles everything automatically.

> **Agent-consumable.** This guide is structured so coding agents (Claude Code, Codex, Gemini CLI) can follow it end-to-end.

## What getbot cannot do on this OS

On unsupported operating systems, `getbot setup` will refuse to run the automated bootstrap. Specifically, it will **not**:

- Install Incus (container runtime)
- Install Caddy (reverse proxy and HTTPS)
- Create the storage pool or network bridge
- Download and install `getbot-auth`

You must install and configure all of the above yourself. Once done, `getbot setup` will work normally — it detects existing infrastructure and skips the bootstrap steps.

## Prerequisites

- A server with at least 2 vCPU, 4 GB RAM, and 8 GB free disk space
- A Linux server with root or sudo access
- SSH access from your workstation to the server
- A domain pointing at the server's IP (e.g. `*.yourorg.getbot.run`)
- An LLM API key (Anthropic, OpenAI, or Google)

## Step 1: Install Incus

Incus provides container isolation for each bot deployment. getbot requires Incus (not LXD).

### Option A: Zabbly repository (Ubuntu/Debian-based)

```bash
curl -fsSL https://pkgs.zabbly.com/get/incus-stable | sudo bash
sudo incus admin init --minimal
```

> **Best-effort guidance.** The package manager commands below are provided as reference for unsupported OSes. Only the Tier 1 OSes listed above are tested and verified for getbot's automated bootstrap.

### Option B: Package manager (distros with Incus in repos)

```bash
# Check if your distro packages Incus
apt search incus 2>/dev/null || dnf search incus 2>/dev/null || pacman -Ss incus 2>/dev/null

# Install via your package manager
sudo apt install -y incus   # Debian/Ubuntu
sudo dnf install -y incus   # Fedora/RHEL
sudo pacman -S incus         # Arch

sudo incus admin init --minimal
```

### Option C: Build from source

See the [official Incus installation guide](https://linuxcontainers.org/incus/docs/main/installing/) for source builds and other methods.

### Verify Incus

```bash
incus version
# Should print a version number (e.g. 6.x)
```

## Step 2: Configure Incus storage and networking

getbot expects a specific storage pool and network bridge.

```bash
# Create the getbot storage pool
sudo incus storage create getbot-pool dir source=/var/lib/incus/storage-pools/getbot-pool

# Create the getbot network bridge
sudo incus network create getbot-br0 \
  ipv4.address=10.199.0.1/24 \
  ipv4.nat=true \
  ipv6.address=none

# Update the default profile to use getbot resources
sudo incus profile device set default root pool=getbot-pool
sudo incus profile device set default eth0 network=getbot-br0
```

### Verify storage and networking

```bash
incus storage show getbot-pool
incus network show getbot-br0
```

## Step 3: Install Caddy

Caddy provides automatic HTTPS and reverse-proxy routing for each bot.

### Option A: Official repository (Debian/Ubuntu)

```bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy
```

### Option B: Direct binary

```bash
curl -fsSL "https://caddyserver.com/api/download?os=linux&arch=amd64" -o /tmp/caddy
sudo mv /tmp/caddy /usr/bin/caddy
sudo chmod +x /usr/bin/caddy
```

### Verify Caddy

```bash
caddy version
# Should print a version number (e.g. v2.x)

# Ensure Caddy is running
sudo systemctl enable --now caddy
```

## Step 4: Install Docker inside Incus

Each getbot container runs Docker internally (Docker-in-Incus). You do **not** need Docker on the host. Docker is installed inside the Incus container automatically when getbot creates it. This step confirms the Incus security nesting configuration is correct.

```bash
# Verify security.nesting is enabled in the default profile
incus profile show default | grep security.nesting
# Expected: security.nesting: "true"

# If not set:
sudo incus profile set default security.nesting=true
```

## Step 5: Install getbot-auth

The `getbot-auth` binary runs on the host and handles Google SSO authentication.

```bash
# Download the latest getbot-auth binary
VERSION=$(curl -fsSL https://releases.getbot.run/latest)
ARCH=$(dpkg --print-architecture 2>/dev/null || uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
curl -fsSL "https://github.com/makash/getbot-secure-openclaw/releases/download/v${VERSION}/getbot-auth_${VERSION}_linux_${ARCH}.tar.gz" | sudo tar xz -C /usr/local/bin/

# Verify
getbot-auth --version
```

## Step 6: Create config directory

```bash
sudo mkdir -p /etc/getbot
sudo chmod 700 /etc/getbot
```

## Step 7: Run getbot setup

With the host prepared, run getbot from your workstation:

```bash
getbot setup --host-ip YOUR_SERVER_IP --ssh-key ~/.ssh/id_ed25519 --ssh-user root
```

getbot will detect that Incus, Caddy, and the storage pool are already configured and skip those steps. It will proceed to deploy your bot.

## Verification checklist

After completing all steps, verify:

- [ ] `incus version` prints a version
- [ ] `incus storage show getbot-pool` succeeds
- [ ] `incus network show getbot-br0` succeeds
- [ ] `caddy version` prints a version
- [ ] `systemctl is-active caddy` prints "active"
- [ ] `incus profile show default` shows `security.nesting: "true"`
- [ ] `test -x /usr/local/bin/getbot-auth` succeeds
- [ ] `test -d /etc/getbot` succeeds

If all checks pass, your server is ready for `getbot setup`.

## Troubleshooting

### Incus not found in package manager

Use the Zabbly repository (Option A) or build from source. Incus is not packaged in all distributions yet.

### Caddy fails to bind port 80 or 443

Another web server (nginx, apache) may be using those ports. Stop it first:

```bash
sudo systemctl stop nginx apache2 2>/dev/null
sudo systemctl disable nginx apache2 2>/dev/null
```

### getbot setup still tries to install Incus

getbot checks for both Incus and the `getbot-pool` storage pool. If you named the pool differently, getbot won't detect it. Use the exact names shown in Step 2.

### Permission denied during getbot-auth download

The GitHub repo is private. If you don't have access to download `getbot-auth` from GitHub releases, contact the getbot team for a direct binary link.