{
  "markdown": "# Hail\n\n**Give your agent a real phone number and an email inbox — in minutes, not days.**\n\n[![License: AGPL v3](https://img.shields.io/github/license/hail-hq/hail)](./LICENSE)\n[![PyPI — hail-sdk](https://img.shields.io/pypi/v/hail-sdk?label=hail-sdk)](https://pypi.org/project/hail-sdk/)\n[![CLI release](https://img.shields.io/github/v/release/hail-hq/hail?label=hail%20CLI)](https://github.com/hail-hq/hail/releases)\n[![Docs](https://img.shields.io/badge/docs-hail.so%2Fdocs-blue)](https://hail.so/docs)\n\nYour 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 (OpenAI → Gemini → Anthropic) do the talking. SMS and email work the same way — one MCP endpoint, one API key, one invoice.\n\nSelf-hostable with Docker Compose; LiveKit Cloud and the communication\nproviders remain external. Open source under AGPLv3.\n\n![Animated terminal demo of hail tail streaming live call events](docs/assets/gifs/hail-tail-live-stream.gif)\n\n## Self-host quick start\n\nPrerequisites: Git, Docker Engine, and Docker Compose v2. For a public\nproduction deployment you also need a domain, HTTPS, and a managed Postgres;\nstart with the [VM deployment guide](docs/public/self-host/vm-deploy.md).\n\nThe commands below run a local evaluation stack with bundled Postgres and\nMinIO. Voice calls additionally require LiveKit Cloud, Twilio, Deepgram,\nCartesia, and at least one LLM provider. Email is optional and requires AWS SES.\n\n```bash\ngit clone https://github.com/hail-hq/hail\ncd hail\ncp .env.example .env\n\n# Generate a shared self-host key, then put it in .env as HAIL_API_KEY.\nprintf 'hk_%s\\n' \"$(openssl rand -base64 32 | tr -d '/+=' | head -c 40)\"\n\n# Edit .env and add the providers required for the channels you will use.\ndocker compose -f docker-compose.yml -f docker-compose.local.yml \\\n  run --rm api alembic upgrade head\ndocker compose -f docker-compose.yml -f docker-compose.local.yml up -d\ndocker compose -f docker-compose.yml -f docker-compose.local.yml ps\ncurl --fail http://localhost:8080/healthz\n```\n\nSelf-host authentication uses the `HAIL_API_KEY` value from `.env`; it does not\nneed an API-key row in Postgres. Export the same key and API URL in the shell\nwhere you use the CLI or SDK (Compose does not export `.env` into your shell):\n\n```bash\nexport HAIL_API_URL=http://localhost:8080\nexport HAIL_API_KEY='<same value as .env>'\n```\n\nNext, follow [LiveKit Cloud](docs/public/self-host/livekit-cloud.md) and\n[Twilio](docs/public/self-host/twilio.md), then bind a phone number to the\nself-host organization using the\n[first-run setup](docs/public/self-host/operations.md#self-host-first-run-setup).\nTo enable email, follow [AWS SES](docs/public/self-host/aws-ses.md).\n\nAuthentication differs by deployment:\n\n- **Hail Cloud** (managed, at [hail.so](https://hail.so)): run `hail login`. The device flow writes a key to `~/.hail/credentials.json`.\n- **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`.\n\nFull 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)\n\n## Install the CLI\n\nOn macOS or Linux with [Homebrew](https://brew.sh):\n\n```bash\nbrew install hail-hq/tap/hail\nhail version\n```\n\nHomebrew adds the `hail-hq/tap` tap automatically. To update later:\n\n```bash\nbrew upgrade hail-hq/tap/hail\n```\n\nAlternatively, download the archive for your operating system and architecture\nfrom [GitHub Releases](https://github.com/hail-hq/hail/releases). Release\nbinaries are available for macOS and Linux on Intel and ARM64. See the\n[CLI reference](docs/public/cli.md) for authentication and commands.\n\n## Make your first call\n\n**CLI**:\n\n```bash\nhail login                        # Hail Cloud only (device flow)\nhail auth logout                  # remove local credentials\nhail auth token                   # print bare API key for scripting\n\nhail call +14155550100 --prompt \"be brief\" --recipient-consent\nhail call list\nhail call status <id>             # one call's state\nhail call tail <id>               # follow events for one call\n\nhail sms +15551234567 --body \"Hello!\" --recipient-consent\nhail sms list\nhail sms status <id>\nhail sms suppressions list        # opt-out list\nhail sms sender-id get            # custom sender ID\n\nhail numbers acquire              # dedicated phone number (voice + SMS)\nhail numbers list\nhail contacts list                # org contact directory\n\nhail email send --to a@b.com --subject hi --body \"hello\" --recipient-consent\nhail email list\nhail email get <id>\nhail email tail <id>              # follow events for one email\nhail email raw <id>               # RFC 5322 source\nhail email attachment <id> <att-id> --output file.pdf\nhail email domain register --kind hail_mail\nhail email domain register --kind custom --domain acme.com  # send + receive on your own domain\nhail email domain list\n\nprintf '%s' \"$YOUR_API_KEY\" | hail providers set llm \\\n  --provider openai-compatible \\\n  --base-url https://api.your-agent.dev/v1 \\\n  --model your-model \\\n  --key -                         # standing BYO brain (also: tts, stt)\n\nhail tail                         # cross-channel event stream\nhail tail call:<id>               # narrow by resource type\n\nhail mcp endpoint                 # Streamable HTTP URL for the MCP server\nhail completion zsh               # source <(hail completion zsh)\nhail version\n```\n\n**Python** (`pip install hail-sdk`):\n\n```python\nimport asyncio\nfrom hail import Client\n\nasync def main():\n    async with Client() as client:  # reads $HAIL_API_KEY\n        call = await client.calls.create(\n            to=\"+15551234567\",\n            recipient_consent=True,\n            system_prompt=\"You are calling to confirm a reschedule.\",\n        )\n        async for event in client.events.tail(id=f\"call:{call.id}\"):\n            print(event.kind, event.payload)\n\nasyncio.run(main())\n```\n\n**HTTP** ([OpenAPI spec](openapi/openapi.yaml), [API reference](https://hail.so/docs/api)):\n\n```bash\ncurl -X POST http://localhost:8080/calls \\\n  -H \"Authorization: Bearer $HAIL_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"to\":\"+15551234567\",\"recipient_consent\":true,\"system_prompt\":\"...\"}'\n```\n\n**MCP** (Claude.ai, Claude Code, ChatGPT, Cursor, …): local clients can use\n`http://localhost:8081`. Web-based clients require a publicly reachable HTTPS\nendpoint. See the [MCP setup guide](docs/public/mcp.md).\n\n## Bring your own LLM\n\nHail always runs the telephony and the voice pipeline. The brain is pluggable, at two levels:\n\n- **Per call** — pass an `llm` block to `POST /calls`; different brains for different calls.\n- **Standing** — save an endpoint once (`hail providers set llm …`); every call your org places uses it.\n\nAny 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 …`).\n\n## Tenets\n\n1. **Clear comms.** Explicit OpenAPI contracts. No hidden behavior.\n2. **Simple code.** Boring is best. No abstraction before it has two uses.\n3. **Brief docs.** Each page fits on one screen. Setup takes 10 minutes from a fresh clone.\n4. **Self-hostable.** Docker Compose runs Hail's API, voicebot, MCP server,\n   Postgres, and MinIO; LiveKit Cloud and channel providers remain external.\n5. **Pluggable brain.** [BYO LLM endpoint](docs/public/byo-llm.md), or Hail's bundled fallback. The voice pipeline and transport are always Hail's.\n6. **Agent-first docs.** AI agents are first-class readers. Runnable examples first; links to canonical sources, not paraphrase.\n\n## Milestones\n\nA checked box is a released feature. Per-artifact changelogs (GitHub Releases for the CLI, PyPI notes for the SDK) record which version shipped it.\n\n### Phone calls\n\n- Outbound\n  - [x] Twilio\n  - [ ] Telnyx\n- Inbound\n  - [ ] Twilio\n\n### SMS\n\n- Outbound\n  - [x] Twilio\n- Inbound\n  - [x] Twilio\n\n### Email\n\n- Outbound\n  - [x] AWS SES\n  - [x] Custom sender domains (own DNS, automatic DKIM + MAIL FROM)\n- Inbound\n  - [x] AWS SES\n  - [x] Custom domains (receive on verified domains)\n\n### Voice pipeline\n\n- Languages\n  - [x] 39 call languages with automatic STT routing and per-language turn detection — see [docs/languages.md](docs/languages.md)\n- STT\n  - [x] Deepgram\n  - [x] Speechmatics\n  - [ ] Whisper\n  - [ ] AssemblyAI\n- TTS\n  - [x] Cartesia\n  - [x] ElevenLabs\n  - [ ] Deepgram Aura\n- VAD\n  - [x] Silero\n- Turn detection\n  - [x] LiveKit turn-detector\n- LLM — system-prompt mode\n  - [x] Fallback: OpenAI → Gemini → Anthropic, fast models\n- LLM — BYO-endpoint mode\n  - [x] OpenAI chat-completions-compatible ([docs](docs/public/byo-llm.md))\n- Recording\n  - [ ] S3 upload\n  - [ ] Diarization\n\n### Distribution\n\n- API\n  - [x] OpenAPI spec + [hosted reference](https://hail.so/docs/api)\n- CLI\n  - [x] `hail` binary via GitHub Releases\n- MCP server\n  - [x] Remote Streamable HTTP endpoint included with each Hail deployment\n  - ~~PyPI stdio package~~ — deliberately not shipped; see [MCP setup](docs/public/mcp.md)\n- Python SDK\n  - [x] `hail-sdk` on PyPI, imports as `hail`\n\n### Infrastructure\n\n- [x] Docker Compose scaffold\n- Self-hosted LiveKit SFU\n  - [ ] docker compose integration\n\n## Architecture\n\nThe path of an outbound call:\n\n```\nAI agent ──► Hail API ──dispatch──► Voicebot ──► LiveKit Cloud ──SIP──► Twilio ──► 📞\n```\n\nFull 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/).\n\n## Contributing\n\nSee [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.\n\n## License\n\nCode: [AGPL-3.0-or-later](./LICENSE) — run a modified Hail as a service, release your source.\nPricing dataset (`costs/`): [CC-BY-4.0](./costs/LICENSE) — use the JSON with attribution.\n",
  "bytes": 10314,
  "sha": "ca5768d36b893b17518600b53b097327a934ab4c386d49f852f9c9f0d71b26bc",
  "repo_slug": "hail-hq/hail",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hail_hq_hail_mcp_3e76ff12/readme"
}