Vanguard on Codespaces¶
Status: Current | Last reviewed: 2026-07-20
The fastest way to bring up a full TrueServe stack: open a GitHub Codespace on this repo.
What you get¶
| Layer | What runs |
|---|---|
| Application services | All apps/* services as host processes under Overmind |
| Infrastructure | Postgres, Redis, Neo4j, RabbitMQ, MinIO via docker-compose.infra.yml |
| Media | Asterisk, Kamailio, Janus, rtpengine, coturn via docker-compose.media.yml |
| Code-server (optional) | Catalog editor sidecar via docker-compose.code-server.yml |
| Public ingress | nginx fronting *.<codespace>.app.github.dev |
Lifecycle¶
| Event | What happens |
|---|---|
| Codespace creates | postCreateCommand runs setup.sh to install deps |
| Codespace starts | postStartCommand runs wake-up.sh — boots compose stacks, starts Overmind |
| Codespace stops | Compose stops cleanly; Overmind dies |
| Codespace resumes | wake-up runs again; data persists in volumes |
Quick reference¶
# Boot or reboot the stack
bash .devcontainer/wake-up.sh
# Restart one service
overmind restart ai-manager
# Tail logs
overmind connect ai-orchestrator
# Infra logs
docker logs tsf-local-postgres --tail 100 -f
# Reset the local DB (destructive)
bash .devcontainer/db-init-local.sh
Full reference: .devcontainer/CLAUDE.md. Slash commands: /local-status, /local-restart, /local-logs.
Salesforce CLI credentials¶
The devcontainer sets SF_USE_GENERIC_UNIX_KEYCHAIN=true because Codespaces has no desktop D-Bus session for Linux Secret Service. If sf org list reports that an auth file is invalid and secret-tool cannot autolaunch D-Bus, repair the current shell with:
export SF_USE_GENERIC_UNIX_KEYCHAIN=true
sf org list
The setting is persisted by setup.sh and is also part of containerEnv for rebuilt containers. An existing ~/.sfdx/key.json with mode 0600 is the expected file-backed keychain; do not delete it or reauthenticate when the export restores the org.
Snapshots¶
To capture a working state for sharing across Codespaces:
bash .devcontainer/dev-snapshot-export.sh
To restore from a snapshot in a fresh Codespace:
bash .devcontainer/dev-snapshot-import.sh <snapshot-name>
Snapshots are useful for demos where you want a known agent set + integration credentials pre-loaded.
Public access¶
The Codespace's app.github.dev host fronts every published port. Service URLs follow the pattern:
| Service | URL |
|---|---|
| ai-manager | https://aim.<codespace>.app.github.dev |
| surface-app | https://surface.<codespace>.app.github.dev |
| status | https://status.<codespace>.app.github.dev |
| code-server | https://code.<codespace>.app.github.dev |
Rules live in configs/nginx/trueserve-vanguard.conf.template.