C.O.D.E Dev Environment Runbook

What it is

C.O.D.E — Collaborative Online Development ENvironment. Each developer gets an isolated browser-based code-server (VS Code) on the Phenom Mac Studio (lbb), pre-loaded with the React Native / Expo toolchain, Claude Code + PAI (LifeOS), and the Code:Talker voice bridge running that developer’s persona. Everyone signs in at the single domain code.thephenom.app through an app-rendered Cognito terminal login (ADR-003), then lands on their own code-server.

Distinct from the staging/prod tiers — that runbook is about dev-nest vs nest. This one is the developer workstation platform.

Architecture

code.thephenom.app  ──(cloudflared tunnel "Logan's Mac Studio")──▶  Traefik (:80)
  /login, /assets, /auth/callback   ▶ login-static      (C.O.D.E terminal-login SPA)
  /auth/session, /auth/logout       ▶ cognito-verifier  (id_token → HttpOnly session cookie)
  /enroll/                          ▶ voice-enrollment  (first-login voice clone, gated)
  <authed root>                     ▶ box-router ▶ per-user code-server  [LIVE #10]
                                      (cognito-verify → persona-provision → Sablier wake)
Qwen3-TTS (bare metal, :8880)       ◀ per-developer cloned voices (enrollment)

• Access layer = Phenom-earth/sablier-weblogon (ADR-003). Runs as a docker-compose stack on the Mac Studio under the builder account’s OrbStack.
• Auth is app-rendered, not Cloudflare Access. The code.thephenom.app CF Access app is set to bypass; the origin’s cognito-verifier (ForwardAuth) mints/verifies the session cookie against the Synapse-trusted Cognito pool (us-east-1_knEL7cqS3).
• Voice = bare-metal Qwen3-TTS (Phenom-earth/Qwen3-TTS, MLX, model Qwen3-TTS-12Hz-0.6B-Base-4bit) on :8880, reachable from containers via host.docker.internal. Each developer clones their own voice at first login.

Images (ghcr)

All access-layer images are built for linux/arm64 on ai and pushed to ghcr:

ghcr pull credential: a classic PAT with read:packages (the sanmarcsoft/github-pat identity smsmatt). Pull auth is written to a temp docker config to avoid the Mac’s locked login keychain.

Deploy / redeploy the access layer

On the Mac Studio, as builder, from ~/PhenomDevEnvironment/sablier-weblogon (branch main):

# docker-compose.override.yml maps build-services to their ghcr image tags, then:
docker compose pull
docker compose up -d --no-build
docker compose ps        # expect 7/7 Up (cloudflared, traefik, login-static,
                         # cognito-verifier, persona-provisioner, voice-enrollment, sablier)

Required .env keys: CLOUDFLARE_TUNNEL_TOKEN, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD, SESSION_SECRET (session-cookie signing), QWEN3_TTS_DIR (~/PhenomDevEnvironment/Qwen3-TTS), TTS_URL (http://host.docker.internal:8880).

Qwen3-TTS (voice)

Runs as a LaunchAgent, not a container (needs native Apple Silicon / MLX):

cd ~/PhenomDevEnvironment/Qwen3-TTS
scripts/run-cloning-server.sh --install-launchd     # LaunchAgent com.phenom.qwen3-tts, :8880
curl -s http://localhost:8880/health                # status ok; voices:[] until enrollment

The server boots with an empty voice set; a developer’s cloned voice is added at enrollment (<id>_ref.wav dropped in the repo dir, then POST /v1/voices/reload).

Verify

curl -sI https://code.thephenom.app/login          # origin serves the SPA (no CF Access 302)
#   → HTTP/2 200, <title>C.O.D.E // Secure Terminal</title>
# On the Mac (as builder):
docker compose ps                                   # 7/7 Up
curl -s http://localhost:8880/health                # Qwen3-TTS ok

Current state (2026-07-24) & what’s left

Live: the terminal login at code.thephenom.app/login authenticates against Cognito; the access layer + Qwen3-TTS are deployed and healthy. Per-user code-server routing is shipped and tested — the box-router (persona/box-router.ts + persona/boxes.ts, with unit tests) landed in #10 and closes the post-login 404, so a logged-in developer lands in their own persistent box. The Cognito id_token to box bridge for Synapse login shipped in #13/#14, and #18 (2026-07-22) auto-provisions a box for any nest-access Cognito member (no manual box creation). Code:Talker (phenom.codetalker, per-box VS Code extension) is installed and functional: #dev roster, speech-bubble chat, and the Qwen3-TTS/Whisper voice bridge (speak + push-to-talk transcription) all work end-to-end, including PAI DA speaking into #dev via the extension’s speak-queue path. See the welcome guide for the end-user walkthrough and the codetalker-dev repo for the extension itself.

Still worth reconciling: the route-to-box wiring the 2026-07-09 audit flagged as unimplemented is now the shipped box-router, but this pass verified it from the merged, tested source rather than a fresh live session, so treat live health as re-probe-on-touch. Also still open: (1) per-user container placement under /Volumes/Orbstack/dev-root/<user>/ on the phenom-access network, reconciling any duplicate scale-to-zero traefik/sablier; (2) Pulse (LifeOS, :31337) proxied per box via code-server /absproxy/31337/.

Access to the box

SSH to the Mac Studio is via the lbb.thephenom.app cloudflared tunnel (SSH-over-Access, claude-code-testing service token), then sudo -u builder. OrbStack + the dev-env stack run under builder.

Related

• Runbooks index
• Development Environments (staging vs prod)
• Federated Login Keys