Engine & deployment

Deployment

A summary of how the platform is run on a server, for operators.

This page is for whoever operates a deployment. It summarises the deployment guide that ships with the backend.

Limitation: The production stack has been validated as configuration but has not yet been run on a real server. Certificate issuance, WebSocket routing through the proxy and Exotel reaching the engine through it are untested. Treat a first deployment as a rehearsal.

What runs

Service	Role
Proxy	TLS, and the only service with public ports
API	The HTTP API
Worker	Calls, batches, workflows, webhooks, post-call work, scheduled jobs
Voice engine	Live conversations
Postgres with pgvector	Data and knowledge-base vectors
Redis	Job queue, rate limits, live call sessions

The model servers (speech-to-text, language model, text-to-speech) are separate and sized on their own.

Steps

Machine: a Linux host with Docker. Open ports 80 and 443 only.
Names: two DNS names, one for the API and the engine's WebSockets, one for the dashboard. The proxy obtains certificates once they resolve.
Configuration: one environment file for the platform, one for the engine. Set the domains, database and Redis passwords, a random SECRET_KEY, the operator and metrics tokens, the engine's shared secret (the same value on both sides), and the email, payment and messaging providers.
Start: bring the stack up. Migrations run before the API and the worker start. Create the first workspace with the provided script.
Check: GET /ready should report every dependency as ok.

With APP_ENV=production the API refuses to start on a placeholder SECRET_KEY and logs a warning for every development setting still on. The mock payment provider, the mock code sender and the development outboxes are switched off.

Telephony wiring

Use	Setting
Outbound calls on the engine	`OWN_AGENT_WS_URL` points at the engine's `/ws` through the proxy
Exotel inbound	The Voicebot applet is given the engine's `/exotel` address with credentials
Browser voice test	`ENGINE_PUBLIC_WS_URL` points at `/web`, and the engine's `WEB_ALLOWED_ORIGINS` lists the dashboard

See Exotel and Twilio and Plivo.

Scaling

API: stateless. More processes or containers behind the proxy.
Workers: replicas. Admission control and the ledger are safe across workers.
Voice engine: one engine per set of model servers. Its limits are per process, so a second engine against the same model servers adds load, not capacity. To add capacity, add model servers with an engine in front of them.
Database: count pool size plus overflow for every API and worker process against the server's connection limit.

A single machine is what is described. High availability, zero-downtime upgrades and automatic rollback are not provided.

Health and monitoring

Endpoint	Use
`GET /health`	Liveness: the process answers
`GET /ready`	Readiness: database and Redis, and the engine and models when configured
`GET /metrics`	Metrics for a scraper, behind its own token. Keep it off the public internet.

Logs are JSON lines with the request id and workspace id; secrets, tokens, full phone numbers and transcripts are redacted centrally. Failed background jobs and exhausted webhook deliveries are visible in dead-letter lists: see Operations.

Backups and upgrades

A backup service writes a verified database dump and keeps the newest few. Copy dumps and the storage volume (recordings, uploads) off the machine, and rehearse a restore.
To upgrade: back up, pull, rebuild. Migrations run first. Workers and the engine get a grace period to finish what they are doing.
There is no scheduled backup, no point-in-time recovery and no blue/green switch out of the box.

Before going live

Real prices in the price book, and the currency decided. The shipped numbers are placeholders.
A payment provider and a messaging provider run end to end in their test modes. Both adapters have only been tested against local fakes.
An email backend other than the outbox.
MAX_CALLS and the model concurrency caps sized to what the model servers can serve.
Recording retention decided.
The security checklist in Security notes.
Legal review of the compliance features for the places you call.