Local setup¶
1. Prerequisites¶
From .tool-versions: Erlang/OTP 28.5.0.5, Elixir 1.20.4-otp-28, Zig 0.16.0 (for
mix compile.reaper; without it shell does not run), Node for the GUI. On Windows,
scripts/setup-windows-toolchain.ps1 installs them. Optional, each unlocking a part of
the suite that otherwise skips (testing.md):
| Tool | Unlocks |
|---|---|
| Docker with compose | scripts/dev-up: PostgreSQL, MinIO, OpenBao for the plane, worker and protocol suites |
python3 |
the protocol conformance test |
bubblewrap |
the sandbox tests |
inotify-tools (Linux) |
the native watch backend |
kind, kubectl, helm |
scripts/remote-up and the cluster suites |
None of it, with Docker. scripts/toolbox runs a command in a container with the
pinned toolchain plus inotify-tools and bubblewrap, joined to scripts/dev-up's
network, with _build and deps in named volumes:
scripts/dev-up
scripts/toolbox mix check
scripts/toolbox # a shell
Five tests do not pass in a container and are not made to: the OS-pid cancellation test
and four gateway tests that spawn or kill -9 a daemon. They pass on a Linux runner.
2. The gate¶
Create and migrate the test database (compose creates only troupe_plane_dev; the
plane's test_helper.exs says so when it finds none), and run the gate:
mix deps.get
MIX_ENV=test mix ecto.create && MIX_ENV=test mix ecto.migrate
mix check # compile with warnings as errors, format, credo --strict, boundaries, test
3. Development services¶
scripts/dev-up starts compose project troupe-dev (dev/docker-compose.yml) on ports
chosen not to collide with a Postgres or MinIO already on the machine, and below 32768 so
no outgoing connection is handed one first. The three services restart with Docker
(restart: unless-stopped): after the WSL VM or the machine restarts they are back as
soon as Docker is, OpenBao with its transit key written again, without scripts/dev-up.
| Service | Image | Host port | Credentials | Notes |
|---|---|---|---|---|
postgres |
postgres:16-alpine |
25432; 25433 for the restored cluster scripts/pitr-drill starts |
troupe / troupe, database troupe_plane_dev |
wal_level=replica, archive_mode=on, archive_timeout=60, data checksums; the WAL archive volume is chowned to 70:70 by a busybox init service |
minio |
pgsty/minio:RELEASE.2026-08-04T00-00-00Z, pinned by digest (Pigsty's community build; MinIO's own images are no longer public) |
29000 (S3), 29001 (console) | troupe / troupe-secret |
minio-setup creates bucket troupe-sessions and enables versioning |
openbao |
openbao/openbao:2.4.1, dev mode |
28200 | root token troupe-dev-root |
dev mode keeps everything in memory, so the container enables transit and creates key troupe-session-tokens (ecdsa-p256) each time it starts, and is healthy once the key exists; KV v2 is at secret/ |
config/config.exs points the dev and test repos at localhost:25432
(troupe_plane_dev / troupe_plane_test), the object store at localhost:29000, and both
the worker's KMS and the plane's transit at localhost:28200 with the dev root token, "for
these two environments only".
scripts/dev-down stops them; --purge also removes the volumes. Each checkout's plane
suite makes a test database of its own, and those of removed worktrees stay:
scripts/dev-down --test-databases [DAYS] stops nothing and drops the ones made more than
a week (or DAYS days) ago, saying each, and keeps one in use. A checkout that still runs
its suite makes its own again.
4. A plane and a worker on kind¶
There is no bare mix path to a serving plane: config/config.exs turns autostart off,
and only config/runtime.exs — inside if config_env() == :prod — turns it on. The one
supported path is:
scripts/remote-up # idempotent: run it again to pick up a change
It creates kind cluster troupe-dev (host ports 30080/30443) with Cilium as its CNI
(TROUPE_KIND_CNI, TROUPE_CILIUM_VERSION; the cluster suite's egress checks need a CNI
that enforces policy), installs ingress-nginx and labels its namespace, points CoreDNS's
dex.localtest.me at the ingress, builds the images and loads them (TROUPE_SKIP_BUILD=1 skips),
applies dev/kind/dependencies.yaml (PostgreSQL, MinIO, OpenBao with Kubernetes auth,
Dex), applies the CRDs, installs the chart with dev/kind/values.yaml and restarts the
plane, the operator and the GUI, then creates a WorkerProfile and its namespace's Secrets. It prints:
| Thing | Address |
|---|---|
| plane, console | http://plane.localtest.me:30080, /console (/admin redirects there) |
| identity | http://dex.localtest.me:30080/dex, user ada@example.test, password troupe |
| workers | ws://<ordinal>-<profile>.workers.localtest.me:30080/v1/socket |
Then troupe login http://plane.localtest.me:30080 and troupe --remote.
scripts/kind-down deletes the cluster. mix troupe.e2e runs the cluster suite against it.
5. Configuration¶
Troupe.Config layers the files in the ladder, then
environment variables, then explicit options, with the organisation's enforced values over
all of them (Decision 869). Every key is in one table, Troupe.Config.Schema, from which mix troupe.config.schema
writes protocol/schema/config/v1.json and the reference in
docs/user/configuration.md; CI runs it with --check, so run
it and commit the result after changing a key. TROUPE_PROVIDER=fake and
TROUPE_FAKE_SCRIPT run the daemon without a model; so do provider: fake and
fake_script: in a workspace's own file, once the workspace is on the user file's
trusted_workspaces (Decision 686), which troupe config trust there puts it on.
6. Development variables¶
| Variable | Read by | Effect |
|---|---|---|
TROUPE_SKIP_BUILD, TROUPE_KIND_CNI, TROUPE_CILIUM_VERSION, TROUPE_PROFILE_NAME, TROUPE_GATEWAY_URL, TROUPE_GATEWAY_MODEL, TROUPE_GATEWAY_SMALL_MODEL, TROUPE_GATEWAY_KEY |
scripts/remote-up |
skip the image build; the kind cluster's CNI and the Cilium it installs; the dev profile's name (dev), model endpoint (unset, a placeholder that resolves nowhere; its host is added to the policy either way), models, and the key written into its llm-credentials Secret (never into a file here) |
TROUPE_KIND_CLUSTER, TROUPE_REGISTRY, TROUPE_IMAGE_TAG, TROUPE_PUSH |
kind scripts, scripts/build-images |
cluster name (troupe-dev), image prefix, tag (dev), push instead of kind load |
TROUPE_PG_CONTAINER, TROUPE_PITR_DB |
scripts/pitr-drill |
the compose container and database |
TROUPE_REAPER_TARGETS |
mix compile.reaper |
triples to build, or all |
ZIG_LOCAL_CACHE_DIR, ZIG_GLOBAL_CACHE_DIR |
Zig | point at a plain local filesystem: Zig aborts on ecryptfs and some network mounts |
TROUPE_PROVIDER, TROUPE_BASE_URL, TROUPE_API_KEY, TROUPE_MODEL, TROUPE_FAKE_SCRIPT |
Troupe.Config |
override config.yaml |
TROUPE_STATE_HOME, TROUPE_CONFIG_HOME, XDG_*, APPDATA, LOCALAPPDATA |
Troupe.Paths |
state and config directories |
TROUPE_DAEMON_SOCKET, TROUPE_DAEMON_COMMAND |
Troupe.Protocol.Endpoint, .Daemon |
tcp or a socket path (empty is unset); what a client spawns as a daemon (else troupe-daemon on the PATH) |
KUBECONFIG, TROUPE_KUBE_CONTEXT |
operator outside a pod, cluster suites | which cluster |
7. The clients¶
clients/tui: mise exec -- mix check there, scripts/dev to run it from source,
scripts/build-local for a binary (clients/tui/CLAUDE.md).
clients/gui: pnpm install, then pnpm dev:local - the default. It runs a second
instance of the installed troupe-daemon with the scripted fake provider, under
TROUPE_DEV_HOME (default: troupe-dev-local in the temp directory), and the GUI in
local-only mode against it: no plane, no identity provider, no key. pnpm fake (an
identity provider, plane and worker on loopback) and pnpm dev are for the plane path,
as the GUI README shows, and
e2e.md covers the suites against a real plane and worker.
On this Windows machine the whole install is scripts/install-local.ps1, checked by
scripts/verify-local.ps1 (fixing-issues.md).