Skip to content

Quick start

Status: Current | Last reviewed: 2026-06-16

This page takes you from a fresh clone to a running stack with one voice agent answering a phone call. It assumes you are running inside the dev devcontainer (Codespaces or EC2). If you are not, read environment modes first.

Prerequisites

You already have:

  • The repo cloned to /workspaces/trueserve-framework (Codespaces does this for you).
  • The devcontainer running. In VS Code: "Reopen in Container".
  • TRUESERVE_DEV_MODE=dev exported in your shell (the devcontainer sets it).

Verify:

echo "$TRUESERVE_DEV_MODE"      # should print: dev
command -v overmind             # should print a path
docker ps --filter name=tsf-local --format '{{.Names}}'

If overmind is missing or no tsf-local-* containers are running, the devcontainer is not fully provisioned. Run setup.sh and try again.

Boot the stack

One command:

bash .devcontainer/wake-up.sh

wake-up.sh is idempotent. It:

  1. Brings up the infra stack (docker-compose.infra.yml) — postgres, redis, neo4j, rabbitmq, minio.
  2. Brings up the media stack (docker-compose.media.yml) — asterisk, kamailio, janus, rtpengine, coturn.
  3. Reconciles the nginx ingress config.
  4. Starts every host process listed in Procfile under Overmind.

Watch it boot in a separate terminal:

overmind connect ai-orchestrator
# Ctrl+b then d to detach

Confirm everything is up

overmind status
docker ps --filter name=tsf-local

You should see the host processes from the Procfile and the infra/media containers. Optional restored apps such as crm-api, crm-dashboard, knowledge-engine, and disabled integrations may idle when their source or feature flag is absent. If something is crashed or unexpectedly dead, troubleshoot it.

Hit a service

Three quick checks, in order of speed:

# 1. ai-manager Next.js UI (admin console)
curl -sS http://localhost:3001/api/health

# 2. ai-orchestrator gRPC health (uses grpcurl if installed)
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

# 3. End-to-end SIP call
# Open https://*.vanguard.dev.trueserve.deloitte.com (your codespace's hostname)
# Use the in-browser phone emulator. Place a call. Hang up.
# The transcript and recording show up in ai-manager.

Make a change

Most services hot-reload. Edit any TS / Python file under apps/ and the host process restarts. To force a restart:

overmind restart ai-orchestrator

Compose-managed services (postgres, asterisk, etc.) do not hot-reload. Bounce them with:

docker restart tsf-local-asterisk

What just happened

Read voice request lifecycle for the call you just placed, then universal pipeline builder to see how the agent that answered was configured.

See also