Installing Clanky

Clanky is a swarm visibility and management engine. One install delivers the whole product: the clanky CLI, the clanky-agent brain (the lead agent that spawns, watches, and harvests worker harnesses), and clanky-herdr — Clanky's bundled terminal multiplexer, where those workers run as visible panes. The Discord voice / Go Live media plane (clankvox) and the always-on cold-start supervisor are opt-in install flags.

There are two ways in — the create-clanky bootstrapper, or running the root installer against a checkout you already have. Both end at the same place: scripts/install.sh builds Herdr, wires the CLI, and records the paths the brain needs.

Prerequisites

Platform: the core install (agent + Herdr + CLI) is portable. The --supervisor launchd daemon is macOS-only today; the brain host itself is portable by design, and the phone already treats the brain as remote, so a Linux box or a hosted deployment are supported shapes for the brain even though the supervisor flag is macOS-specific.

Install

With create-clanky (clone + install)

During pre-public bring-up the bootstrapper runs straight from the private Git repo — nothing is published to npm:

npx --yes --package git+ssh://git@github.com/Volpestyle/clanky-internal.git#master -- create-clanky clanky
cd clanky
clanky up

create-clanky [dir] clones into dir (default clanky) and runs scripts/install.sh. Pass installer flags after --:

npx --yes --package git+ssh://git@github.com/Volpestyle/clanky-internal.git#master -- create-clanky clanky -- --with-clankvox

Once the package ships, the intended new-user form is npx create-clanky clanky. See packages/create-clanky/README.md for --repo, --branch, and --use-existing.

From an existing checkout

If you already cloned the repo, run the installer directly:

git clone <clanky-repo-url> clanky
cd clanky
./scripts/install.sh
clanky up

Or drive the same path through the bootstrapper without re-cloning:

npx --yes ./packages/create-clanky --use-existing .

What the installer does

scripts/install.sh is idempotent — re-running it is safe. In order, it:

1. Checks prerequisites — Node >= 24, pnpm (or corepack), and cargo (installing Rust via rustup if absent). Each missing tool fails with a fix hint.
2. Installs clanky-agent dependencies with pnpm install --frozen-lockfile.
3. Builds the terminal multiplexer — cargo build --release --locked --bin clanky-herdr → herdr/target/release/clanky-herdr. Skipped when the binary already exists (unless --force). The first build can take a few minutes.
4. Records Herdr paths — writes CLANKY_REPO_DIR and CLANKY_HERDR_BIN into clanky-agent/.env.local, the durable, gitignored config store every Clanky surface reads.
5. Installs the CLI — symlinks ~/.local/bin/clanky to this checkout's clanky-agent/bin/clanky.ts.
6. Optional extras — builds ClankVox (--with-clankvox) and/or installs the launchd supervisor (--supervisor).

flowchart TD
  A["npx create-clanky<br/>(or ./scripts/install.sh)"] --> B{clone needed?}
  B -->|yes| C["git clone --depth 1"]
  B -->|no| D["use existing checkout"]
  C --> E["scripts/install.sh"]
  D --> E
  E --> F["preflight: Node 24 / pnpm / cargo"]
  F --> G["pnpm install --frozen-lockfile"]
  G --> H["cargo build clanky-herdr"]
  H --> I["write CLANKY_REPO_DIR + CLANKY_HERDR_BIN<br/>to clanky-agent/.env.local"]
  I --> J["symlink ~/.local/bin/clanky"]
  J --> K{optional flags}
  K -->|"--with-clankvox"| L["build clankvox binary"]
  K -->|"--supervisor"| M["load launchd daemon"]
  K --> N["clanky up"]
  L --> N
  M --> N

Optional flags

First run

clanky up      # ensures the herdr session and the Clanky brain pane are running
clanky dev     # opens the interactive face (TUI); run it in a terminal or pane

clanky up is idempotent and non-interactive — it brings the terminal session and the headless command host (which owns the eve brain) online, or reports that they already are. clanky dev attaches the face; it needs a real TTY.

Configuration lives in clanky-agent/.env.local. You rarely edit it by hand: the face's slash commands (/model, /auth, /discord-scope, /voice, …) write it for you. The commented template is clanky-agent/.env.example; the full variable reference is clanky-agent/docs/env-reference.md (pnpm env:reference regenerates it).

Connecting the iOS app is a separate step — see Troubleshooting below and clanky pair.

Updating

From inside the checkout:

clanky update          # git pull --ff-only, pnpm install, refresh the CLI symlink
clanky update --check  # also run pnpm check

Troubleshooting

clanky: command not found. ~/.local/bin is not on your PATH. Add it: export PATH="$HOME/.local/bin:$PATH" (the installer prints this note when it detects the gap). The CLI is a symlink into the checkout, so the checkout must stay in place.

pnpm install --frozen-lockfile fails. The lockfile is frozen so a fresh clone reproduces exactly. A failure means your working tree diverged from the committed lockfile — install from a clean clone, or reconcile the lockfile before re-running.

cargo still not found after the rustup install. The new toolchain is not on this shell's PATH. Run source "$HOME/.cargo/env" (or open a new shell) and re-run the installer.

Node too old. The installer requires Node >= 24 and stops with the version it found. Upgrade (nvm install 24 or nodejs.org) and re-run.

The brain 503s ("Dev server is unavailable") after editing the repo. Editing watched files or building in the live checkout can trigger an eve dev rebuild that leaves the front returning 503. Restart with clanky up.

clanky pair says "no CLANKY_RELAY_TOKEN set". The iOS app connects over the relay, which is fail-closed without a bearer token, and the installer does not mint one. Set it before pairing: in the face run /auth and choose the relay token, or generate one and store it yourself —

# from clanky-agent/, add a strong random token to .env.local
printf 'CLANKY_RELAY_TOKEN=%s
' "$(openssl rand -hex 32)" >> .env.local

Then run clanky pair for the QR (or clanky pair --link).

--supervisor fails off macOS. The supervisor is a launchd daemon and needs launchctl. On other platforms, skip the flag; the core install (agent + Herdr

• CLI) does not depend on it.

ClankVox source not found. --with-clankvox builds from the clankvox package in the checkout. If it is missing, point CLANKY_CLANKVOX_DIR at the ClankVox source and re-run.

See also

• Root README — ecosystem map and package layout.
• packages/create-clanky/README.md — bootstrapper options.
• clanky-agent/docs/env-reference.md — every config variable.