Getting Started

Follow these steps in order; everything below is based on real scripts that live in this repository.

1. Prerequisites

• Node.js 18+ and pnpm 9 – required by Turborepo and the Express server (packages/server).
• Docker Desktop – spins up PostgreSQL from the root docker-compose.yml.
• Python 3.9+ and uv – manages virtualenvs for packages/agent.
• LiveKit Cloud project – grab LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and SIP settings referenced in .env.example.

2. Clone the repository

git clone https://github.com/onenineinnov/tellyo.git
cd tellyo

Use SSH or HTTPS depending on your access; all subsequent commands assume you are at the repo root.

3. Install dependencies

pnpm install:all           # also runs uv sync inside packages/agent

pnpm install:all comes from the root package.json and ensures both the JavaScript workspace and the Python agent stay aligned.

4. Configure environment variables

1. Copy the sample files:

   cp .env.example .env
   cp packages/server/.env.example packages/server/.env
   cp packages/agent/.env.example packages/agent/.env.local

2. Fill in:

   • DATABASE_URL for local Postgres (matches docker-compose.yml defaults).
   • API_KEYS in packages/server/.env (generate via pnpm api-key).
   • LiveKit, Azure OpenAI, and Twilio settings used by the agent and telephony service.

5. Run the database, migrations, and seeds

docker compose up -d postgres
pnpm db:migrate        # runs packages/server migrations via Drizzle
pnpm db:seed           # seeds base companies/agents data (see src/db/seed-*.ts)

The same Drizzle commands run in CI/CD before every deployment (see MIGRATION_SETUP.md), so running them locally mirrors production.

6. Start each service

pnpm --filter server dev        # Express API with hot reload (packages/server)
uv run python src/agent.py dev  # LiveKit agent (packages/agent)
pnpm --filter docs dev          # Optional: docs on http://localhost:3002

The agent automatically downloads speech models on the first run via uv run python src/agent.py download-files. Make sure SERVER_API_URL and SERVER_API_KEY are set in packages/agent/.env.local so the agent can pull configs and create call records.

7. Use Postman or HTTP clients

1. Base URL – http://localhost:3001.
2. Authorization header – set Authorization: Bearer <your API key>.
3. Collections – create folders for /api/companies, /api/agents, /api/calls, and /api/agents/:id/provision-phone.
4. Health checks – GET /health (server) and GET /api/agents to confirm API connectivity.

All REST routes live under packages/server/src/routes. See the How-To collection for concrete payloads.

8. Local tooling

• pnpm db:studio opens Drizzle Studio against your local database.
• ./packages/server/scripts/docker-db.sh mirrors the Compose commands (start/stop/status/logs).
• uv run pytest executes the agent eval suite.

Once the API responds and the agent can fetch a config by phone number, continue to the How-To guides to create companies, agents, and telephony resources.