Skip to content
Projects

steipete/vox has 100 GitHub stars and 19 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-18 08:56 UTC. Last push 2026-11-14.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Let's your agent run phone calls

Developer Tools

README.md

Original

vox

CLI + bridge server that connects Twilio Media Streams (PSTN phone calls) ↔ OpenAI Realtime (speech-to-speech) and lets the voice model call back into your local agent via tools.

This repo is intentionally “thin glue”: WebSocket proxying, barge-in/interrupt handling, logging, and a minimal tool adapter.

What you get

  • vox serve: HTTP endpoint that returns TwiML and a WebSocket endpoint Twilio streams audio to.
  • vox dial: outbound calling via Twilio REST to connect a call to your running vox serve.
  • OpenAI Realtime session configured for G.711 μ-law passthrough (audio/pcmu) so there’s no resampling/DSP required.
  • query_agent tool that can call:
    • an HTTP endpoint (VOX_AGENT_URL), or
    • a local subprocess (VOX_AGENT_CMD, JSONL request/response).

Requirements

  • Node.js >= 22
  • A public HTTPS URL to your laptop (Twilio needs to reach /twiml and wss://.../twilio). ngrok works fine.
  • OpenAI API key
  • Twilio account + a phone number (for PSTN calling)

Setup

npm i
cp .env.example .env

Fill in at least:

  • OPENAI_API_KEY
  • VOX_PUBLIC_BASE_URL (the public HTTPS base URL that maps to your local server, e.g. your ngrok URL)

Run

Start the bridge:

npm run dev -- serve --port 3000

Smoke check:

curl http://127.0.0.1:3000/health

Inbound calls (recommended dev loop)

Point your Twilio Phone Number’s “A call comes in” webhook to:

  • GET https://<your-public-base>/twiml

When you call that Twilio number, Twilio will stream the call to:

  • wss://<your-public-base>/twilio

Outbound calls

Set:

  • TWILIO_ACCOUNT_SID
  • TWILIO_AUTH_TOKEN

Then dial:

npm run dev -- dial +14155550123 --from +14155550999

Local simulation (no Twilio)

Useful for iterating on tool-calling and prompts without PSTN setup:

npm run dev -- simulate

Type a line, press enter, and Vox will respond (and write .wav files under VOX_LOG_DIR). Disable audio playback with --no-play. While a response or its tools are running, wait for completion before entering the next message. Failed or timed-out agent queries return a safe tool error while keeping the simulator open and saving buffered audio. A response with multiple tool calls submits every tool result before starting one assistant follow-up.

Local agent tool (query_agent)

The Realtime session registers a tool named query_agent. The voice model calls it whenever it needs facts/actions from your “real” agent.

Option A: HTTP agent

Set VOX_AGENT_URL to an endpoint that accepts POST JSON and returns JSON (or plain text).

Option B: Subprocess agent (JSONL)

Set VOX_AGENT_CMD, for example:

VOX_AGENT_CMD="node examples/echo-agent.js"

Protocol:

  • Vox writes one JSON line:
{"id":"...","type":"query","args":{...}}
  • Your agent replies with one JSON line:
{"id":"...","result":{...}}

See examples/echo-agent.js.

Set VOX_AGENT_TIMEOUT_MS to a positive millisecond value to bound HTTP or subprocess queries. It defaults to 0, preserving unbounded agent calls.

Logs

Each call writes JSONL logs under VOX_LOG_DIR:

  • events.jsonl (Twilio + OpenAI + Vox events)
  • meta.json (call start time and Twilio IDs, updated when the start event arrives)
  • report.json (if the model calls save_call_report)

Configuration

Environment variables (see .env.example):

  • OPENAI_API_KEY (required)
  • OPENAI_REALTIME_MODEL (default: gpt-realtime)
  • OPENAI_REALTIME_VOICE (optional)
  • OPENAI_REALTIME_URL (optional trusted ws:// or wss:// endpoint override)
  • OPENAI_TRANSCRIPTION_MODEL (default: gpt-4o-transcribe)
  • VOX_PUBLIC_BASE_URL (required for /twiml)
  • VOX_AGENT_URL or VOX_AGENT_CMD (optional)
  • VOX_LOG_DIR (default: ./logs)
  • VOX_INITIAL_GREETING (optional)
  • TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN (required for vox dial)

OPENAI_REALTIME_URL receives the configured OpenAI API key. Only use an endpoint you trust.

Development

npm run lint
npm run typecheck
npm test
npm run build

Safety / compliance notes

You are responsible for consent, recording rules, disclosure, and telecom compliance in the jurisdictions you call.