---
name: acahti-install
description: Install or upgrade an Acahti instance on a Linux host over SSH with the official install script. Use when the user asks to self-host Acahti, stand up a new instance, add a Runner, or upgrade.
---

# Install Acahti

Published at https://acahti.benchyard.com/install.md. You run the install over SSH; the person answers questions and watches.

## Ask once

- **Domain** (required): the public hostname, such as `acahti.example.com`. The person terminates TLS at their own proxy or tunnel and forwards it to the gateway.
- **SSH** (required): a sudoer on a Linux host with at least 2 GiB RAM. Not root.
- **Runner** (optional): SSH to a second host for CI, such as `ci@10.0.0.5`. Never the control-plane host. Without it, there is no CI until one is added.
- **Org** (optional, default `acme`) and **modules** (optional: `work`, `argos`, `chat`).

## Install

On the host:

```bash
curl -fsSL https://acahti.benchyard.com/install.sh | bash -s -- --domain acahti.example.com [--runner ci@10.0.0.5] [--org acme] [--modules work,argos]
```

The script installs Docker if needed, pulls the release image, writes `~/acahti/.env` with generated secrets, starts the services, and, with `--runner`, sets up the Runner over SSH from this host. Run `install.sh --help` for every option. On failure, read the output and fix the cause; do not improvise another installer.

Then confirm the person's proxy forwards the domain to `127.0.0.1:8080` (or `0.0.0.0:8080` when a Runner is set), and that `curl -fsS https://<domain>/healthz` succeeds.

## Report back

Without secrets:

- the instance URL and `<instance>/join`; admins create invites in the web app;
- the admin username (the password stays in `~/acahti/.env`);
- the agent prompt on the instance home page, which connects an agent and runs the demo loop.

Never paste `.env` contents, passwords, or invite codes into chat.

## Upgrade

Back up PostgreSQL and the data directory (`ACAHTI_DATA`, default `/var/lib/acahti`), then run the same command without options. It installs the latest release and keeps `.env` and all data. `--version X.Y.Z` pins a release.

```bash
curl -fsSL https://acahti.benchyard.com/install.sh | bash
```

Never run `docker compose down -v` on an instance.