Hail

Give your agent a real phone number and an email inbox — in minutes, not days.

Your agent needs to call a person to move an appointment. Hail connects to the telephone carrier and runs the voice pipeline — STT, TTS, turn detection. Your agent is the brain: point Hail at any OpenAI-compatible endpoint (bring your own LLM), or let Hail's fallback chain (OpenAI → Gemini → Anthropic) do the talking. SMS and email work the same way — one MCP endpoint, one API key, one invoice.

Self-hostable with Docker Compose; LiveKit Cloud and the communication providers remain external. Open source under AGPLv3.

Self-host quick start

Prerequisites: Git, Docker Engine, and Docker Compose v2. For a public production deployment you also need a domain, HTTPS, and a managed Postgres; start with the VM deployment guide.

The commands below run a local evaluation stack with bundled Postgres and MinIO. Voice calls additionally require LiveKit Cloud, Twilio, Deepgram, Cartesia, and at least one LLM provider. Email is optional and requires AWS SES.

git clone https://github.com/hail-hq/hail
cd hail
cp .env.example .env

# Generate a shared self-host key, then put it in .env as HAIL_API_KEY.
printf 'hk_%s\n' "$(openssl rand -base64 32 | tr -d '/+=' | head -c 40)"

# Edit .env and add the providers required for the channels you will use.
docker compose -f docker-compose.yml -f docker-compose.local.yml \
  run --rm api alembic upgrade head
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d
docker compose -f docker-compose.yml -f docker-compose.local.yml ps
curl --fail http://localhost:8080/healthz

Self-host authentication uses the HAIL_API_KEY value from .env; it does not need an API-key row in Postgres. Export the same key and API URL in the shell where you use the CLI or SDK (Compose does not export .env into your shell):

export HAIL_API_URL=http://localhost:8080
export HAIL_API_KEY='<same value as .env>'

Next, follow LiveKit Cloud and Twilio, then bind a phone number to the self-host organization using the first-run setup. To enable email, follow AWS SES.

Authentication differs by deployment:

• Hail Cloud (managed, at hail.so): run hail login. The device flow writes a key to ~/.hail/credentials.json.
• Self-host: do not run hail login; set HAIL_API_URL and HAIL_API_KEY as shown above, or pass --api-url and --api-key.

Full setup guides: self-hosting · Webhooks · MCP · operations

Install the CLI

On macOS or Linux with Homebrew:

brew install hail-hq/tap/hail
hail version

Homebrew adds the hail-hq/tap tap automatically. To update later:

brew upgrade hail-hq/tap/hail

Alternatively, download the archive for your operating system and architecture from GitHub Releases. Release binaries are available for macOS and Linux on Intel and ARM64. See the CLI reference for authentication and commands.

Make your first call

CLI:

hail login            

... [View full README on GitHub](https://github.com/hail-hq/hail#readme)