Installation
three ways in.

01Choose a way

02Docker

One image with Python 3.11 and Node 20, no key inside. It runs as user vox (uid 10001) with a read-only root file system; only app/data (the named volume vox-data) is writable.

cp deploy/vox.env.example deploy/vox.env && chmod 600 deploy/vox.env   # optional: keys can also go in the console
docker compose up -d --build
docker compose logs vox | grep "VOX admin"           # console URL with its token
docker compose run --rm vox node src/run.js           # the 12 onboarding questions
docker compose run --rm vox python -m voice check     # what is missing, no network, no key

Other ports

VOX_ADMIN_PORT=9766 VOX_MEDIA_PORT=9765 docker compose up -d

These are Compose variables (defaults 8766 and 8765), not VOX settings. The health check moves with them.

What does not work in Docker

• PC actions and desktop clean-up work on the container's files, not on the user's computer. For that, use the user unit (below).
• MCP servers over stdio (uvx, npx): those tools are not in the image. Use HTTP MCP servers or extend the image.
• The spoken terminal briefing (say is macOS only). It is printed.

SaaS mode in Docker

The shipped compose file runs single-user mode. For SaaS, override the command and the health check, for example in docker-compose.override.yml:

services:
  vox:
    command: ["python", "-m", "voice", "saas", "--host", "127.0.0.1", "--port", "8080",
              "--serve-host", "127.0.0.1", "--serve-port", "8765"]
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request as u; u.build_opener(u.ProxyHandler({})).open('http://127.0.0.1:8080/api/csrf', timeout=4)"]

docker compose run --rm vox python -m voice saas migrate
docker compose run --rm vox python -m voice saas create-operator --email you@example.com --role owner

03Installer script (no Docker)

deploy/install.sh                 # options: --python python3.11 · --dev (also installs the test tools)

It checks Python ≥ 3.11 and Node ≥ 20, installs @anthropic-ai/sdk from the lock file (npm ci --omit=dev --ignore-scripts), creates app/.venv, installs app/voice/requirements.txt, installs and verifies NLTK punkt_tab, runs python -m voice check and prints the next steps. It never asks for, reads or stores a key. Running it again is safe.

04By hand

cd app
python3 -m venv .venv
. .venv/bin/activate
pip install -r voice/requirements.txt
python -m voice setup-nltk                   # sentence-splitter data; without it the bot is silent
python -m voice check

setup-nltk options: --dir D (install elsewhere, then set NLTK_DATA to that directory), --from-zip Z (offline, from a zip downloaded elsewhere; the zip is pinned by SHA-256), --force.

Tests (offline, no keys): pip install -r voice/requirements-dev.txt && python -m pytest -q.

05Service units (systemd)

The install procedure is in the header of each file. Both run python -m voice up and send SIGINT on stop, which up treats like Ctrl+C. For SaaS mode change ExecStart to python -m voice saas --host 127.0.0.1 --port 8080 --serve-host 127.0.0.1 --serve-port 8765. The console URL with its token is in journalctl (not printed when VOX_ADMIN_TOKEN is set).

06First run: single-user

1. Answer the 12 questionsnode src/run.js from app/. Options: --answers file.json (scripted), --no-speak. This step never calls anyone.
2. Start everythingpython -m voice up. It prints one line, VOX admin http://127.0.0.1:8766/#token=…, once the console really listens.
3. Enter the keysOpen that URL, go to Setup and enter the keys (Configuration). The media server starts only when all seven required keys and the NLTK data are present, so restart up after entering them.
4. Verify your own numberProfile → Verify number (how). Until then even a call to yourself is treated as a third-party call.
5. Place the first callpython -m voice dial --purpose "morning briefing", or the Dial section of the console.

07First run: SaaS mode

cd app && . .venv/bin/activate
python -m voice saas migrate                                   # create / upgrade data/saas/vox.db
python -m voice saas create-operator --email you@example.com --role owner
python -m voice saas --host 127.0.0.1 --port 8080 --serve-host 127.0.0.1 --serve-port 8765

One process serves the public site (/), each customer's console (/app/) and the operator panel (/op/) on port 8080, runs the multi-tenant worker, and starts the media server on port 8765 when every required key is present. Ctrl+C stops everything. Put a TLS proxy in front (Deployment) and continue with Operator panel.

The database is <data>/saas/vox.db (0600) and each customer lives in <data>/tenants/<tenant_id>/. Do not run up and saas on the same data directory at the same time.

08Command reference

serve, admin, worker, up and saas also take --data-dir PATH. --help works on every command.