Install Klatch

The short way: one command on a fresh server. The long way (below) is the same steps by hand.

What you need

A server running Ubuntu 22.04 or 24.04, or Debian 12, on x86_64 or arm64. 2 CPUs, 4 GB of memory and 20 GB of disk are a comfortable start. You need root.
Or a Mac with macOS 13 or newer (Apple silicon or Intel) and OrbStack or Docker Desktop. See On a Mac.
Your license key (from the purchase email) and an AI account: a Claude API key, a Codex key, a Gemini key, or an Anthropic-compatible service. You enter these in the browser, not in the terminal.
Optional: a domain name pointing at the server, for HTTPS. Ports 80 and 443 must be open to it.
Klatch gives agents a lot of room inside their own containers, and the hub owns the Docker socket, which is root on that server. Use a server you are happy to give it to, not one that hosts something you cannot lose.

The command

curl -fsSL https://klatch.dev/install.sh | sudo sh -s -- --domain klatch.yourdomain.com

Options: --domain NAME (HTTPS, set up automatically), --yes (do not ask questions, needed when there is no terminal), --version TAG, --dry-run (show what would happen and change nothing).

What it does, in order:

Checks the system and CPU, and that there is free disk.
Asks before installing Docker with Docker's own script (https://get.docker.com), if Docker is missing.
Creates /opt/klatch with a .env (new random secrets, mode 600) and a data folder.
Pulls the Klatch hub image and takes compose.yml, the klatch command and the agent recipe out of it.
Creates the klatch-agents Docker network. It is internal: containers on it have no route to the internet.
Builds the agent image on your server. It contains Claude Code and the other agent tools, which we are not allowed to hand out ready-made, so each server installs them itself. The first install takes a few extra minutes.
Starts Klatch (with Caddy for HTTPS when you gave a domain) and waits until it answers.
Prints the setup address.

Running it again is the upgrade path: on an existing install it runs klatch update --version <tag> (default latest), which takes a backup first, so klatch rollback can undo it. Your .env and data are kept. --domain is ignored on an existing install.

The panel's machine binding reads the host's /etc/machine-id, which both compose files mount read-only into the hub as /etc/host-machine-id. Compose cannot mount a file conditionally, so install.sh (and klatch update) create /etc/machine-id with systemd-machine-id-setup when a server has none.

On a Mac

Run it as yourself, without sudo:

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

It installs into ~/Klatch, offers to install OrbStack with Homebrew if there is no Docker yet, puts the klatch command in Homebrew's bin (or ~/.local/bin), and opens the panel at http://localhost:8080. --domain is for servers only. Agents work only while the Mac is awake: keep it plugged in and stop it sleeping, or use a server for a team that works around the clock.

First run in the browser

Open the address the installer printed. It ends in #setup= and a token; the token proves you are the person who installed it, and it is used once. If you lost it: cat /opt/klatch/data/setup-token (it is deleted once the owner account exists).

Four steps, each can go back:

Owner. Choose a password (8 or more characters). Optionally add an authenticator app.
AI account. Pick Claude, Codex or Antigravity, enter the key, press Check. You can skip and do it later in Settings.
First project. A name and the HTTPS URL of a git repo, with an access token that may push. You can skip this too.
License. Paste your key. Without a valid license the team does not start new turns; reading and approving keep working.

If you did not use --domain, the panel only listens on the server itself. From your own computer:

ssh -L 8080:127.0.0.1:8080 you@your-server

then open http://127.0.0.1:8080.

Checking it

klatch status
klatch doctor

doctor prints ok, warn or FAIL for Docker, disk, the agent network, ports, DNS and HTTPS, your license, and whether the agent image works.

By hand

If you would rather not run a script: install Docker, then create /opt/klatch, put the deploy/compose.yml from this repository there, make a .env (see .env.example; set AUTH_MODE=password, and a 64-character hex KLATCH_SECRET_KEY), create the network with docker network create --internal --subnet 172.30.0.0/24 klatch-agents, build the agent image with docker build -t klatch-runner:2.1.312 runner/, and run docker compose up -d.

Without a domain: Tailscale

Put the server on your tailnet, set HUB_BIND to its tailnet address in .env, and AUTH_MODE=tailnet only if the tailnet itself should be the login. Anyone on the tailnet is then the owner. HUB_HOSTS must list the names you type in the browser (host:port).

Settings you may change in `/opt/klatch/.env`

Setting	Meaning
`HUB_BIND`, `HUB_PORT`	Where the hub listens on the server. Keep `127.0.0.1` behind Caddy or a tunnel.
`HUB_HOSTS`	Names the hub answers to (guards against DNS tricks). The installer sets it for your domain.
`PUBLIC_URL`, `TRUST_PROXY`	Set with a domain: redirects to HTTPS and trusts Caddy's client address. Never set `TRUST_PROXY` if the hub port is reachable directly.
`SLOTS`	How many agent turns run at once (default 2).
`TZ`	Timezone for quiet hours and the morning digest.
`KLATCH_SECRET_KEY`	Encrypts keys saved in the panel. Back it up with the data (`klatch backup` does).
`KLATCH_VERSION`	Image tag. `klatch update --version X` changes it.

After editing: cd /opt/klatch && docker compose up -d.

Deploys and installs

Agents can install tools for themselves and, once you add a provider token in the panel, ask to deploy your site. No extra server setup is needed. See deploy.md.

Forgot the password

cd /opt/klatch && docker compose exec hub node dist/hub.mjs passwd

Add --reset-totp if the authenticator is lost. It signs every session out.

Removing Klatch

cd /opt/klatch && docker compose down
docker network rm klatch-agents
rm -rf /opt/klatch

Deactivate your license first (Settings, License) so the seat is free for your next server.