Skip to content

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).