Quickstart

Voxagent ships as a bundle — a docker-compose.yml and a reference .env.example — served directly from this docs site. Images live in our private container registry at registry.nodul.ru — pull access is granted via a read-only token (see below).

1. Download the quickstart bundle

mkdir Voxagent && cd Voxagent
curl -O https://docs.voxagent.app/cdn/docker-compose.yml
curl -O https://docs.voxagent.app/cdn/.env.example

• docker-compose.yml — full service stack (includes a one-shot postgres-init service that creates the extra databases/users after Postgres is healthy)
• .env.example — reference environment variables

2. Request a registry token

Container images at registry.nodul.ru/voxagent/nodevoice/* require a read-only token. Tokens are issued per customer on request — email us at help@mail.voxagent.app and we'll send you one.

Once you have it, log in on the host — docker will prompt for username and password:

docker login registry.nodul.ru/voxagent/nodevoice

3. Configure

cp .env.example .env

The baseline .env.example already contains everything needed to bring the stack up locally — you can leave it as-is and start. Provider keys (LLM / STT / TTS), Keycloak SMTP, billing, telephony and other integrations are optional and only needed for the corresponding functionality.

Full variable reference is in Configuration.

4. Start the stack

Pull the latest images first so you're not running a stale :latest cached from a previous docker login:

docker compose pull
docker compose up -d

First boot takes a few minutes — Postgres initialises, Keycloak imports the realm, Lago runs migrations and seeds the billing organisation.

5. Wait for angular-client to become healthy

Check service status:

docker compose ps -a --format "table {{.Service}}\t{{.Status}}\t{{.Ports}}"

As soon as the angular-client row shows Up ... (healthy), the app is ready — open it at http://localhost:4210.

6. Create a user

On the sign-in screen hit Sign up and create an account.

The docker compose bundle ships with email verification disabled (KEYCLOAK_VERIFY_EMAIL=false), so registration is instant.

Enable email verification

To require users to confirm their email before first login, edit .env:

1. Turn the flag on:

   KEYCLOAK_VERIFY_EMAIL=true

2. Fill in Keycloak SMTP credentials (used for verification + password-reset emails):

   KEYCLOAK_SMTP_HOST=smtp.example.com
   KEYCLOAK_SMTP_PORT=465
   KEYCLOAK_SMTP_FROM=no-reply@example.com
   KEYCLOAK_SMTP_USER=<smtp-user>
   KEYCLOAK_SMTP_PASSWORD=<smtp-password>
   KEYCLOAK_SMTP_SSL=true       # for port 465
   KEYCLOAK_SMTP_STARTTLS=false # flip to true for port 587

3. Recreate Keycloak to pick up the changes:

   docker compose up -d --force-recreate keycloak

Other entrypoints

Once the stack is fully up:

Ports are configurable in .env under the HOST PORTS section — change any that clash with something already running on your machine.

Next steps

• Requirements — size your host for expected concurrent load.
• Configuration — complete environment reference.
• Installation — other deployment options (managed, Kubernetes).