martinambrus/haive

Deterministic multi-CLI orchestration and AI agentic workflow utility. Replaces a markdown-driven Claude Code onboarding flow, an autonomous /workflow implementation loop, and a sandboxed local environment replication step set with a deterministic web project. Agentic CLI invocations only happen for parts that need reasoning; everything else is a TypeScript step module with a web form.
Install
There are two ways in and they are different things. **Run a release** boots published images —
no source, no build, one command. **Build from source** is the contributor path and is what the
rest of this file documents.
Run a release
Linux, macOS and Windows. On Windows this is PowerShell with Docker Desktop — no WSL shell is
involved; Docker Desktop uses WSL2 as its engine, which is its plumbing rather than a requirement
on you. If you would rather read a script than pipe one into a shell, download it, read it, run it.
**Docker is the only prerequisite, and the installer never installs it.** It names what is missing
and the exact fix for your platform, then stops having changed nothing. Everything else Haive needs
runs inside a container.
| Option | |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --version | Install a specific release. An alias (latest, next) is resolved to a concrete version and PINNED, so an install cannot drift onto a moving tag. Default: latest. |
| --install-id | Names every container, volume, network and database this install owns ([a-z0-9_], default haive). Required for a SECOND install on one machine — see below. |
| --dir | Where to install. Default ~/ . |
| --check | Run the prerequisite checks and exit, changing nothing. |
| --no-start | Write the install but do not boot it. |
| --force | Install into a non-empty directory. |
It writes one directory and nothing system-wide: the compose bundle, an .env holding secrets it
generates for this install (mode 600), and two helper scripts — ./haive and ./uninstall.sh
(.ps1 on Windows). Host ports are probed rather than assumed, so a second install, or a machine
already running ddev, gets free ones instead of a bind error.
./haive is how you run the install afterwards, and it is worth knowing before you need it:
**If the first boot does not come up,** the install directory is already complete — the compose
bundle, the .env and both helpers are written before anything is pulled. So it is a retry, not a
reinstall: ./haive up, and ./haive logs to see why. Re-running the installer will not help and
is refused anyway. The commonest cause is a pull that did not finish on a slow connection; the
images are large and the first boot then also initialises the database, which on a laptop can take
several minutes after the containers appear.
**Before you use it, know what it can do:** the Haive worker mounts the Docker socket, which is
equivalent to root on the host. That is how it runs AI CLIs in sandboxes. See
Docker socket exposure for the rootless alternative.
> **First account:** the first person to register becomes the administrator. Open the app and the
> setup page asks for an email and password; every account created after that is a normal user.
>
> Exactly one first account can be anointed even if several arrive at once — the check and the
> insert share a transaction under an advisory lock. On an instance you expose to a network before
> registering yourself, set SETUP_TOKEN in the install's .env and that first registration must
> present it, which closes the window where a stranger could claim the instance.
Upgrading
An upgrade drains running work, snapshots the database, migrates, and keeps the new version only
once the new containers report it — anything that fails before that point rolls back. Either:
- **Admin console → Maintenance & upgrade**, which also shows what work is still running and the
history of past upgrades; or
- ./haive upgrade --version 0.2.0 from the install directory, which is the one that still works
when the stack is down.
The installer never upgrades: re-running it against an existing install is refused.
Uninstalling
The default keeps your cloned repositories, uploaded bundles, CLI logins and the DDEV CA, and
lists them by name; --purge removes those too. It only ever touches resources belonging to this
install id, and it does not delete the directory it is running from — after a clean --purge the