Local Development

The whole platform runs locally from one docker-compose stack: infrastructure/local/docker-compose.yml. It brings up the three per-solution Orbit apps, Aurora (the portfolio control plane), and the portfolio registry (Postgres plus three Hono services) on a private bridge network, bind-mounting each app’s codebase for hot reload and a reference solution repository for the agent to author against.

cd infrastructure/local
cp .env.example .env   # then edit values (paths, ports, credentials)
docker compose up --build

All services join the orbit-net bridge network, so containers reach each other by service name (e.g. http://orbit-agent:3000 from inside another container). Each service also publishes a host port so the browser can hit it directly.

Topology

Ports shown are the host-side defaults; every container listens on its own fixed internal port (3000, except the agent-webapp on 3001 and Postgres on 5432).

Services

Notes on the build contexts:

• orbit-webapp, orbit-agent, the three registry services, and the activity service build with implementation/ as the context so their file: dependencies — the shared shared/trajectory-loader, shared/registry-kit, and shared/activity-kit packages — are inside the build context and get baked into the image.
• The registry services and the activity service run their own migrations on boot, so up from zero yields a working empty registry and activity feed; all four wait for the Postgres healthcheck (pg_isready) before starting.

The volume and mount model

Codebase bind mounts + anonymous volumes

Every Node service follows the same pattern, spelled out in the Dockerfile.local files:

1. Dependencies are installed at image build time (npm ci / npm install).
2. At runtime the codebase folder is bind-mounted into the container, so saved file changes hot-reload via next dev / tsx watch.
3. Anonymous volumes are declared on node_modules (and .next for the Next.js apps) — e.g. - /app/.next — so the bind mount doesn’t shadow what the image installed. Without them you’d get macOS-host node_modules inside a Linux container.

For orbit-webapp and orbit-agent the in-container layout mirrors the repo’s implementation/ folder (/app plays that role): the app lives at /app/<name>/codebase and the shared @maxq/trajectory-loader package is baked in at /app/shared/trajectory-loader, so the file:../../shared/... symlink in node_modules resolves. Changing a shared package therefore requires an image rebuild — see the workflows below.

The solution mounts (orbit-agent is the sole owner)

The agent is the single writer and sole owner of the solution-repo mounts. Since the 2026-07-02 refactor, orbit-webapp has no repository mount at all — it fetches all solution and sources data over HTTP from the agent’s in-memory model (ORBIT_AGENT_URL: http://orbit-agent:3000, a docker-network name; the browser never calls the agent directly for this).

The agent reads these in-container paths from its own environment (SOLUTION_REPOSITORY_PATH=/repo, etc.); the host paths are chosen purely via .env.

Aurora’s mounts

Aurora manages the fleet live from GitHub, so it mounts no solution repo. It gets two read-only mounts instead:

• the platform repo root at /repo-platform:ro — the in-product chat agent’s working directory (AURORA_AGENT_CWD, default /repo-platform), so the agent sees the real workspace root;
• a secrets folder at /secrets:ro — AURORA_SECRETS_PATH (default: the git-ignored implementation/aurora-webapp/codebase/secrets/), holding the two GitHub App private-key .pem files.

Named volumes (survive down, die on down -v)

Environment configuration

Copy .env.example to .env in infrastructure/local/ and fill it in. The variable names and what they point at (never commit values):

Day-to-day workflows

All commands run from infrastructure/local/ (or add -f infrastructure/local/docker-compose.yml from the repo root). The compose project is named orbit-local.

# Bring the whole stack up (build images if needed)
docker compose up --build            # foreground
docker compose up --build -d        # detached
 
# Bring it down (containers + network; named volumes survive)
docker compose down
 
# Bring it down AND wipe named volumes (Postgres data, Claude sessions!)
docker compose down -v
 
# Restart one service (no rebuild, keeps anonymous volumes)
docker compose restart orbit-webapp
 
# Tail logs
docker compose logs -f orbit-agent          # one service
docker compose logs -f --tail=100           # everything
 
# Status
docker compose ps
 
# Shell into a container
docker compose exec orbit-agent sh

Rebuilding after a dependency or shared-package change. Because node_modules lives in the image (the bind mount only carries source), any change to a package.json/lockfile — and any change to shared/trajectory-loader or shared/registry-kit, which are baked in at build time — needs an image rebuild:

docker compose up --build -d orbit-webapp      # rebuild + recreate one service
docker compose up --build -d                   # or the whole stack

Renewing anonymous volumes. restart does not recreate anonymous volumes. To force fresh node_modules (re-seeded from the image) and an empty .next:

docker compose up -d --force-recreate -V orbit-webapp

Known gotchas

globals.css edits don’t always hot-reload

Edits to orbit-webapp’s src/app/globals.css sometimes never trigger a Turbopack recompile, so the browser keeps serving the previously-compiled CSS even though the file inside the container is correct. Two things compound:

1. macOS → Docker bind-mount file watching is unreliable — inotify events across the virtiofs/gRPC-FUSE bridge are frequently dropped, so Turbopack never sees the change (large-CSS edits drop more often than JS/TSX edits).
2. .next is an anonymous volume, and docker compose restart does not recreate it — a plain restart reuses the stale compiled CSS.

The fix — clear .next inside the container, then restart:

docker compose exec -T orbit-webapp sh -c "rm -rf /app/orbit-webapp/codebase/.next/* /app/orbit-webapp/codebase/.next/.* 2>/dev/null"
docker compose restart orbit-webapp
# wait for "Ready in" in the logs, then hard-reload the browser
# (the first request recompiles and is slow)

Equivalent: docker compose up -d --force-recreate -V orbit-webapp. A full down -v + up --build also fixes it, but wipes the Claude session volume.

When verifying a CSS change, don’t trust a single browser reload — confirm the rule actually shipped (e.g. via getComputedStyle) and clear .next if it’s stale, rather than assuming the edit was wrong.

Out-of-band solution-repo edits don’t show up in the reader

The agent holds the solution tree in memory and serves it to orbit-webapp over HTTP; there is no filesystem watcher on /repo. Edits the agent makes itself are picked up (and pushed to the reader via the solution.updated SSE event), but changes made out-of-band — editing the solution repo directly on the host — are invisible until you ask the agent to reload:

curl -X POST http://localhost:3010/solution/reload

(3010 is the default AGENT_PORT.)

Other things to know

• down -v deletes orbit-claude-sessions — interrupted agent tasks can no longer be resumed afterwards. Prefer plain down, or the targeted --force-recreate -V <service> for volume problems.
• The agent container runs as a sandbox trust boundary: compose sets IS_SANDBOX=1 so the Claude Code SDK’s bypassPermissions mode works under root inside the container.
• SOLUTION_REPOSITORY_PATH is mandatory — compose fails fast with a clear error (:?Set SOLUTION_REPOSITORY_PATH in .env ...) if it’s unset.