<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://hail.so/assets/brand/social/readme-banner-dark.png">
  <img src="https://hail.so/assets/brand/social/readme-banner.png" width="100%" alt="hail.so: Give your AI assistant a phone number and an email inbox.">
</picture>

# Hail

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

[![License: AGPL v3](https://img.shields.io/github/license/hail-hq/hail)](./LICENSE)
[![PyPI — hail-sdk](https://img.shields.io/pypi/v/hail-sdk?label=hail-sdk)](https://pypi.org/project/hail-sdk/)
[![CLI release](https://img.shields.io/github/v/release/hail-hq/hail?label=hail%20CLI)](https://github.com/hail-hq/hail/releases)
[![Docs](https://img.shields.io/badge/docs-hail.so%2Fdocs-blue)](https://hail.so/docs)
[![Brand assets](https://img.shields.io/badge/brand-hail.so%2Fbrand-5284ff)](https://hail.so/brand)
[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/59134891-d34d3c4a-00eb-43f8-853d-8fc7859696b2?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D59134891-d34d3c4a-00eb-43f8-853d-8fc7859696b2%26entityType%3Dcollection%26workspaceId%3Daeb5d784-d1b6-4e09-a7ad-0d2e5b442d08)

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](docs/public/byo-llm.md)), or let Hail's fallback chain (Anthropic → OpenAI → Gemini) 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.

![Animated terminal demo of hail tail streaming live call events](docs/assets/gifs/hail-tail-live-stream.gif)

## 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](docs/public/self-host/vm-deploy.md).

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

```bash
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):

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

Next, follow [LiveKit Cloud](docs/public/self-host/livekit-cloud.md) and
[Twilio](docs/public/self-host/twilio.md) (optionally
[Telnyx](docs/public/self-host/telnyx.md) and [DIDWW](docs/public/self-host/didww.md)),
then bind a phone number to the
self-host organization using the
[first-run setup](docs/public/self-host/operations.md#self-host-first-run-setup).
To enable email, follow [AWS SES](docs/public/self-host/aws-ses.md).

Authentication differs by deployment:

- **Hail Cloud** (managed, at [hail.so](https://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](docs/public/self-host/README.md) · [Webhooks](docs/public/webhooks.md) · [MCP](docs/public/mcp.md) · [operations](docs/public/self-host/operations.md)

## Cursor plugin

Give your AI assistant a phone number and an email inbox.

Let your assistant handle calls, texts, and email. Building an app? Add AI
calls, email and SMS with one API.

Make and take calls, send and receive messages, and check conversation
history from Cursor. Get phone numbers in 120+ countries, with help for
local rules and required documents, including US A2P 10DLC registration.
Choose a built-in voice or bring your own. Build with the API, CLI, or
Python SDK. Open-source or cloud priced on usage.

From a checkout that includes the plugin, copy its files into Cursor's
local plugin directory:

```bash
mkdir -p ~/.cursor/plugins/local/hail
git archive HEAD .cursor-plugin mcp.json README.md LICENSE \
  docs/assets/hail-messenger.svg | tar -x -C ~/.cursor/plugins/local/hail
```

Reload Cursor and open Customize to find the Hail MCP server.
Enterprise administrators must allow local plugin imports first.
The plugin connects to `https://mcp.hail.so`
using OAuth. Sign in to Hail when Cursor asks. No API key or local MCP
runtime is needed. Start with a read-only request:

```text
Find call-capable Hail numbers in the UK, France, and Canada. Compare
monthly fees, setup fees, and registration requirements.
```

## Install the CLI

On macOS or Linux with [Homebrew](https://brew.sh):

```bash
brew install hail-hq/tap/hail
hail version
```

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

```bash
brew upgrade hail-hq/tap/hail
```

Alternatively, download the archive for your operating system and architecture
from [GitHub Releases](https://github.com/hail-hq/hail/releases). Release
binaries are available for macOS and Linux on Intel and ARM64. See the
[CLI reference](docs/public/cli.md) for authentication and commands.

## Make your first call

**CLI**:

```bash
hail login                        # Hail Cloud only (device flow)
hail auth logout                  # remove local credentials
hail auth token                   # print bare API key for scripting

hail call +14155550100 --prompt "be brief" --recipient-consent
hail call list
hail call status <id>             # one call's state
hail call tail <id>               # follow events for one call

hail sms +15551234567 --body "Hello!" --recipient-consent
hail sms list
hail sms status <id>
hail sms suppressions list        # opt-out list
hail sms sender-id get            # custom sender ID

hail numbers acquire              # dedicated phone number (voice + SMS), cheapest live offer
hail numbers list
hail contacts list                # org contact directory

hail email send --to a@b.com --subject hi --body "hello" --recipient-consent
hail email list
hail email get <id>
hail email tail <id>              # follow events for one email
hail email raw <id>               # RFC 5322 source
hail email suppressions list      # addresses Hail will not send to
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  # send + receive on your own domain
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 -                         # standing BYO brain (also: tts, stt)

hail tail                         # cross-channel event stream
hail tail call:<id>               # narrow by resource type

hail mcp endpoint                 # Streamable HTTP URL for the MCP server
hail completion zsh               # source <(hail completion zsh)
hail version
```

**Python** (`pip install hail-sdk`):

```python
import asyncio
from hail import Client

async def main():
    async with Client() as client:  # reads $HAIL_API_KEY
        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](openapi/openapi.yaml), [API reference](https://hail.so/docs/api)):

```bash
curl -X POST http://localhost:8080/v1/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](docs/public/mcp.md).

## 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](docs/public/byo-llm.md). TTS and STT are pluggable the same way (`hail providers set tts|stt …`).

## Tenets

1. **Clear comms.** Explicit OpenAPI contracts. No hidden behavior.
2. **Simple code.** Boring is best. No abstraction before it has two uses.
3. **Brief docs.** Each page fits on one screen. Setup takes 10 minutes from a fresh clone.
4. **Self-hostable.** Docker Compose runs Hail's API, voicebot, MCP server,
   and Postgres; LiveKit Cloud and channel providers remain external.
5. **Pluggable brain.** [BYO LLM endpoint](docs/public/byo-llm.md), or Hail's bundled fallback. The voice pipeline and transport are always Hail's.
6. **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

- Outbound
  - [x] Twilio
  - [x] Telnyx
  - [x] DIDWW
- Inbound (answered by an [agent](docs/public/agents.md))
  - [x] Twilio
  - [x] Telnyx
  - [x] DIDWW

### SMS

- Outbound
  - [x] Twilio
  - [x] Telnyx
- Inbound
  - [x] Twilio
  - [x] Telnyx
  - [x] Answered by an [agent](docs/public/agents.md)

### Numbers

- [x] Live quotes across carriers (inventory, price, verification effort)
- [x] Carrier verification for regulated countries (Twilio, Telnyx)

### Email

- Outbound
  - [x] AWS SES
  - [x] Custom sender domains (own DNS, automatic DKIM + MAIL FROM)
- Inbound
  - [x] AWS SES
  - [x] Custom domains (receive on verified domains)

### Voice pipeline

- Languages
  - [x] 39 call languages with automatic STT routing and per-language turn detection — see [docs/languages.md](docs/languages.md)
- STT
  - [x] Deepgram
  - [x] Speechmatics
  - [ ] Whisper
  - [ ] AssemblyAI
- TTS
  - [x] Cartesia
  - [x] ElevenLabs
  - [ ] Deepgram Aura
- VAD
  - [x] Silero
- Turn detection
  - [x] LiveKit turn-detector
- LLM — system-prompt mode
  - [x] Fallback: Anthropic → OpenAI → Gemini, fast models
- LLM — BYO-endpoint mode
  - [x] OpenAI chat-completions-compatible ([docs](docs/public/byo-llm.md))
- Recording
  - [x] Optional call recording
  - [ ] Diarization

### Distribution

- API
  - [x] OpenAPI spec + [hosted reference](https://hail.so/docs/api)
- CLI
  - [x] `hail` binary via GitHub Releases
- MCP server
  - [x] Remote Streamable HTTP endpoint included with each Hail deployment
  - [x] Stdio entry point included in the MCP container; see [MCP setup](docs/public/mcp.md#stdio)
- Python SDK
  - [x] `hail-sdk` on PyPI, imports as `hail`

### Infrastructure

- [x] Docker Compose scaffold
- Self-hosted LiveKit SFU
  - [ ] docker compose integration

## Architecture

The path of an outbound call:

```
AI agent ──► Hail API ──dispatch──► Voicebot ──► LiveKit Cloud ──SIP──► carrier (Twilio · Telnyx · DIDWW) ──► 📞
```

Full diagram and service breakdown: [docs/public/architecture.md](docs/public/architecture.md). All docs are published at [hail.so/docs](https://hail.so/docs) and live as plain markdown in [docs/public/](docs/public/).

## Contributing

See [docs/public/contributing.md](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](./LICENSE) — run a modified Hail as a service, release your source.
Pricing dataset (`costs/`): [CC-BY-4.0](./costs/LICENSE) — use the JSON with attribution.