Set up Klatch with your AI assistant

Paste everything below the line into Claude Code, Codex, or any assistant that can run shell commands on your server (open the assistant in an SSH session on the server, as root or with sudo). Keep it in the loop: it will stop and ask you for the things only you have.

You need ready: your Klatch license key, and for the AI account an API key (Claude, Codex or Gemini). If you want HTTPS, a domain name whose DNS already points at this server.

You are setting up Klatch, a self-hosted control room for AI coding agents, on this server. Work step by step and show me the real output of every command you run as evidence. Do not summarize output you did not read.

Goal

Klatch is installed in /opt/klatch, running under Docker, answering on its address, with the setup wizard ready for me in my browser (or finished). The command klatch doctor ends with "All good."

Rules

Never invent secrets. Do not make up, guess or reuse a license key, API key, password, token or domain. If you need one, stop and ask me, and wait.
Ask me for: the license key, the AI provider API key, the domain name (or whether I want to use an SSH tunnel instead), and my choice of owner password. I will type the license key, API key and password into the Klatch setup page in my browser myself. You never need to see them, so do not ask me to paste them into this chat.
Never disable or change the firewall (ufw, iptables, nftables, cloud firewall). If a port is blocked, tell me which port and let me open it.
Do not run anything that deletes data you did not create (docker system prune, rm -rf outside /opt/klatch).
Show the command and its output for each step. If a command fails, show the error and follow the troubleshooting table below. Do not retry the same failing command more than twice without changing something.
Do not print the contents of /opt/klatch/.env. The setup token in /opt/klatch/data/setup-token you may print once, because I need it.

Steps

1. Check the machine. Run:

cat /etc/os-release | head -5; uname -m; df -h /opt | tail -1; free -h | head -2; id -u

Expected: Ubuntu 22.04 or 24.04, or Debian 12; x86_64 or aarch64; at least 10 GB free; at least 2 GB memory; and 0 for the last line (you are root). If you are not root, prefix every command below with sudo. If the system is not supported, stop and tell me.

On a Mac, run sw_vers -productVersion; uname -m; df -h ~ | tail -1; docker info --format '{{.ServerVersion}}' instead. Expected: macOS 13 or newer and Docker answering (OrbStack or Docker Desktop running). Do not use sudo on a Mac, skip step 2 (the panel is at http://localhost:8080), and read ~/Klatch wherever this guide says /opt/klatch.

2. Ask me about the address. Ask: "Do you want a domain with HTTPS (give me the name), or an SSH tunnel?". If a domain: check that it points here:

getent hosts <domain>; curl -fsS https://api.ipify.org; echo

Expected: the two addresses are the same. If not, stop and tell me to fix the DNS first.

3. Install. Without a domain:

curl -fsSL https://klatch.dev/install.sh | sh -s -- --yes

With a domain:

curl -fsSL https://klatch.dev/install.sh | sh -s -- --yes --domain <domain>

(--yes lets it install Docker with Docker's official script if Docker is missing. If I said I do not want Docker installed by the script, leave --yes out and let it ask me.) It takes several minutes: it builds the agent image on this server. Expected last lines: ==> Klatch is running. and an address ending in #setup=<token>.

4. Verify it is up.

klatch status
curl -fsS http://127.0.0.1:8080/healthz

Expected: containers hub (and caddy if a domain was used) with status running / healthy, and {"ok":true}.

5. Hand me the setup address. Print the address the installer ended with. If you lost it:

echo "setup token: $(cat /opt/klatch/data/setup-token)"

With a domain, the address is https://<domain>/#setup=<token>.
Without one, tell me to run, on my own computer, ssh -L 8080:127.0.0.1:8080 <user>@<this-server> and open http://127.0.0.1:8080/#setup=<token>.

Tell me the four steps of the page: owner password, AI account (API key, then Check), first project (optional), license key. Wait until I say I finished.

6. Verify the finished setup.

klatch doctor

Expected: every line ok (a warn for an API host I do not use is fine) and All good.. The license line should say license: valid.

Troubleshooting

What you see	Likely cause	What to do
`unsupported system`	Not Ubuntu 22.04/24.04, Debian 12 or macOS 13+	Stop. Tell me.
`cannot talk to Docker` (Mac)	OrbStack or Docker Desktop is not running	`open -a OrbStack`, wait until it runs, re-run the install command
`cannot talk to the Docker daemon`	Docker stopped	`systemctl start docker`, then re-run the install command
`Docker Compose v2 is missing`	Old Docker	Re-run install and let it install Docker, or `apt-get install docker-compose-plugin`
`network klatch-agents exists but is not internal`	An old network with that name	Show me `docker network inspect klatch-agents`; ask before removing it
`the hub did not come up`	Crash on start	`klatch logs`; look for the first error line and show it to me
`port is already allocated` / `address already in use`	Another service on 80, 443 or 8080	`ss -ltnp \	grep -E ':(80\	443\	8080) '`; show me; ask what to do
Caddy cannot get a certificate	DNS not pointing here, or ports 80/443 blocked	`klatch logs caddy`; tell me which, do not touch the firewall
`doctor`: `FAIL agent image ... is missing`	The build did not finish	`klatch update`, then `klatch doctor`
`doctor`: `license: missing` or `invalid`	License not entered or not valid	Tell me to open Settings, License in the panel
Setup page says the token is not right	Typo, or too many tries	Print the token file again; if "Too many attempts", wait one minute
Page says setup is already done	An owner exists	Sign in; for a lost password: `cd /opt/klatch && docker compose exec hub node dist/hub.mjs passwd`

Done when

klatch doctor prints All good.
I can open the address, sign in, and the Settings page shows a valid license.
You have told me, in plain words: the address, that klatch update upgrades it, that klatch backup makes a backup (and that I should copy it off the server), and that the encryption key in /opt/klatch/.env is inside the backup.