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
printf 'hk_%s\n' "$(openssl rand -base64 32 | tr -d '/+=' | head -c 40)"
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
hail auth logout
hail auth token
hail call +14155550100 --prompt "be brief" --recipient-consent
hail call list
hail call status <id>
hail call tail <id>
hail sms +15551234567 --body "Hello!" --recipient-consent
hail sms list
hail sms status <id>
hail sms suppressions list
hail sms sender-id get
hail numbers acquire
hail numbers list
hail contacts list
hail email send --to a@b.com --subject hi --body "hello" --recipient-consent
hail email list
hail email get <id>
hail email tail <id>
hail email raw <id>
hail email attachment <id> <att-id> --output file.pdf
hail email domain register --kind hail_mail
hail email domain register --kind custom --domain acme.com
hail email domain list
printf '%s' "$YOUR_API_KEY" | hail providers set llm \
--provider openai-compatible \
--base-url https://api.your-agent.dev/v1 \
--model your-model \
--key -
hail tail
hail tail call:<id>
hail mcp endpoint
hail completion zsh
hail version
Python (pip install hail-sdk):
import asyncio
from hail import Client
async def main():
async with Client() as client:
call = await client.calls.create(
to="+15551234567",
recipient_consent=True,
system_prompt="You are calling to confirm a reschedule.",
)
async for event in client.events.tail(id=f"call:{call.id}"):
print(event.kind, event.payload)
asyncio.run(main())
HTTP (OpenAPI spec, API reference):
curl -X POST http://localhost:8080/calls \
-H "Authorization: Bearer $HAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"+15551234567","recipient_consent":true,"system_prompt":"..."}'
MCP (Claude.ai, Claude Code, ChatGPT, Cursor, …): local clients can use
http://localhost:8081. Web-based clients require a publicly reachable HTTPS
endpoint. See the MCP setup guide.
Bring your own LLM
Hail always runs the telephony and the voice pipeline. The brain is pluggable, at two levels:
- Per call — pass an
llm block to POST /calls; different brains for different calls.
- Standing — save an endpoint once (
hail providers set llm …); every call your org places uses it.
Any OpenAI chat-completions-compatible endpoint works. A complete runnable example lives in docs/public/byo-llm.md. TTS and STT are pluggable the same way (hail providers set tts|stt …).
Tenets
- Clear comms. Explicit OpenAPI contracts. No hidden behavior.
- Simple code. Boring is best. No abstraction before it has two uses.
- Brief docs. Each page fits on one screen. Setup takes 10 minutes from a fresh clone.
- Self-hostable. Docker Compose runs Hail's API, voicebot, MCP server,
Postgres, and MinIO; LiveKit Cloud and channel providers remain external.
- Pluggable brain. BYO LLM endpoint, or Hail's bundled fallback. The voice pipeline and transport are always Hail's.
- Agent-first docs. AI agents are first-class readers. Runnable examples first; links to canonical sources, not paraphrase.
Milestones
A checked box is a released feature. Per-artifact changelogs (GitHub Releases for the CLI, PyPI notes for the SDK) record which version shipped it.
Phone calls
SMS
Email
Voice pipeline
- Languages
- STT
- TTS
- VAD
- Turn detection
- LLM — system-prompt mode
- LLM — BYO-endpoint mode
- Recording
Distribution
- API
- CLI
- MCP server
- Python SDK
Infrastructure
Architecture
The path of an outbound call:
AI agent ──► Hail API ──dispatch──► Voicebot ──► LiveKit Cloud ──SIP──► Twilio ──► 📞
Full diagram and service breakdown: docs/public/architecture.md. All docs are published at hail.so/docs and live as plain markdown in docs/public/.
Contributing
See docs/public/contributing.md. Short version: fork, branch, conventional commits, pull request. Provider adapters go in core/hailhq/core/providers/; new env vars update .env.example in the same commit.
License
Code: AGPL-3.0-or-later — run a modified Hail as a service, release your source.
Pricing dataset (costs/): CC-BY-4.0 — use the JSON with attribution.