Server Pre-Flight Checks

Check before you change

Before installing anything, getbot runs pre-flight checks on your server. These catch problems early — before Incus is installed, before containers are created, before anything is modified. If something's wrong, you get a clear message with the exact fix.

Pre-flight runs automatically during setup and getbot infra hosts register. You don't need to trigger it manually.

Disk space

getbot checks free disk space on the root partition. Incus containers, Docker images, and bot data all need room to breathe.

• Less than 8 GB free — deployment blocked. You'll see remediation suggestions: sudo apt clean, clearing old journal logs, or using a server with more disk space.
• 8–15 GB free — warning, but deployment continues. You'll want to free up space soon.
• More than 15 GB free — no issues.

Port conflicts

getbot checks ports 80 (HTTP), 443 (HTTPS), and 2019 (Caddy admin API). What happens depends on what's listening:

• Caddy already running on 80/443 — warning only. getbot configures Caddy via its admin API, so an existing Caddy instance is fine. Your existing routes are preserved.
• Caddy on port 2019 — no action needed. This is Caddy's admin API, which getbot uses to register routes.
• nginx, Apache, or another process on 80/443 — error. getbot tells you exactly which process is listening and how to stop it (e.g., sudo systemctl stop nginx).

Incus detection

getbot checks whether Incus is already installed and whether the getbot-specific preseed has been applied:

• Not installed — getbot installs Incus from the Zabbly repository and applies the preseed configuration (creates getbot-pool storage and getbot-br0 network bridge).
• Installed but not initialized — getbot applies the preseed without reinstalling. This happens if a previous setup was interrupted after install but before initialization.
• Installed and initialized — getbot skips both install and init. Safe to re-run setup on a server that's already set up.

Operating system check

getbot checks the server's operating system by reading /etc/os-release over SSH. If the OS is not in the supported list, getbot stops immediately with a clear error — before making any changes to your server.

Supported operating systems

• Ubuntu 22.04 LTS
• Ubuntu 24.04 LTS
• Debian 12 (Bookworm) stable
• Debian 13 (Trixie) testing

What happens on unsupported OSes

If getbot detects an unsupported OS (e.g. Amazon Linux, Fedora, Arch, CentOS, RHEL), it prints an error message that includes:

• The detected OS name and version
• The list of supported OSes
• Your SSH connection details (host, key, user)
• A link to the manual install guide

The error message is designed as a ready-to-paste prompt for coding agents (Claude Code, Codex, Gemini CLI). Your agent can SSH into the server and follow the manual install guide to prepare it. After preparation, getbot setup works normally.

This is a one-time setup. Once the server is prepared, getbot works for all future operations including upgrades.

What a passing check looks like

  Running pre-flight checks...
  ✓ Disk space: 47 GB available
  ✓ No port conflicts
  ✓ Incus is not installed (will install)

  Pre-flight passed. Continuing setup...

What a failed check looks like

  Running pre-flight checks...
  ✓ Disk space: 47 GB available
  ✗ Port 80 is in use by nginx (pid 1234)
    → Stop nginx: sudo systemctl stop nginx
  ✓ Incus is installed and initialized

  Pre-flight failed. Fix the errors above and re-run setup.

Every error includes a → line with the exact command to fix it. Fix the issue, re-run getbot setup, and the check passes.