Show HN: Hail.so – Open-source phone, SMS and email for agents and humans, v0.15

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 5

Star 15

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

448 Commits

448 Commits

.agents/skills/livekit-agents

.agents/skills/livekit-agents

.claude

.claude

.github/workflows

.github/workflows

.husky

.husky

api

api

cli

cli

core

core

costs

costs

docs

docs

infra

infra

mcp

mcp

openapi

openapi

scripts/costs

scripts/costs

sdk

sdk

voicebot

voicebot

web

web

.dockerignore

.dockerignore

.env.example

.env.example

.gitignore

.gitignore

.lintstagedrc.js

.lintstagedrc.js

CHANGELOG.md

CHANGELOG.md

CLAUDE.md

CLAUDE.md

Caddyfile

Caddyfile

LICENSE

LICENSE

README.md

README.md

docker-compose.local.yml

docker-compose.local.yml

docker-compose.prod.yml

docker-compose.prod.yml

docker-compose.yml

docker-compose.yml

glama.json

glama.json

package.json

package.json

pnpm-lock.yaml

pnpm-lock.yaml

pnpm-workspace.yaml

pnpm-workspace.yaml

pyproject.toml

pyproject.toml

skills-lock.json

skills-lock.json

uv.lock

uv.lock

vercel.json

vercel.json

Repository files navigation

Universal communication platform for AI agents. Phone calls, SMS, email — outbound first, inbound next. Self-hostable. Open source (AGPLv3).

Your agent wants to place a call: "Call +1… and ask if they want to reschedule." Hail does the carrier glue, runs the voice pipeline, and lets the agent plug in its own brain (or fall back to OpenAI → Gemini → Claude).

Quickstart

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

fill in Twilio, LiveKit Cloud, Deepgram, Cartesia, and one of OpenAI / Gemini / Anthropic

docker compose up

Authenticate:

Hail Cloud (managed at hail.so): hail login runs the device-flow and saves an API key to ~/.hail/credentials.json.

Self-host: seed an API key directly into your local stack — see docs/operations.md "First-run DB seed". Then export HAIL_API_KEY (or pass --api-key).

Use it — CLI (for humans scripting Hail):

hail login # authenticate (device flow) hail auth logout # remove local credentials hail auth token # print bare API key for scripting

hail call +14155550100 --prompt "be brief" hail call list hail call tail # follow events for one call

hail email send --to [email protected] --subject hi --body "hello" hail email list hail email get hail email tail # follow events for one email hail email raw # RFC 5322 source hail email attachment --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

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

hail mcp endpoint # Streamable HTTP URL for the MCP server hail completion zsh # source :8081 (self-hosted)

https://mcp.hail.so (Hail Cloud, later)

hail tail in action:

Full setup: docs/setup/twilio.md, docs/setup/livekit-cloud.md, docs/setup/aws-ses.md, docs/setup/mcp.md.

Tenets

Clear comms. Explicit OpenAPI contracts. No magic.

Simple code. Boring is best. No abstractions without two uses.

Brief docs. One screen per page. Setup ≤ 10 minutes from a fresh clone.

Self-hostable. docker compose up runs everything except LiveKit Cloud.

Pluggable brain. BYO endpoint compatible with OpenAI's completions API, or use Hail's bundled fallback (OpenAI → Gemini → Anthropic). Voice pipeline + transport are always Hail's.

Agent-first docs. AI agents are first-class readers. Lead with concrete, runnable examples; link to canonical sources (OpenAPI spec, MCP tool schemas, code paths) rather than paraphrase them. Every page should let a reader — human or agent — take the next action.

Milestones

Checked = shipped. Per-artifact changelogs (GitHub Releases for the CLI, PyPI release notes for the SDK) own the "shipped in which version" question.

Phone calls

Outbound

Twilio

Telnyx

Inbound

Twilio

SMS

Outbound

Twilio

Inbound

Twilio

Email

Outbound

AWS SES

Custom sender domains (own DNS, auto DKIM + MAIL FROM)

Inbound

AWS SES

Custom domains (receive on verified domains)

Voice pipeline

STT

Deepgram

Whisper

AssemblyAI

TTS

Cartesia

ElevenLabs

Deepgram Aura

VAD

Silero

Turn detection

LiveKit turn-detector

LLM — system-prompt mode

Fallback: OpenAI → Gemini → Anthropic, fast models

LLM — BYO-endpoint mode

OpenAI chat-completions-compatible

Recording

S3 upload

Diarization

Distribution

API

OpenAPI spec

CLI

hail binary via GitHub Releases

MCP server

Remote Streamable HTTP endpoint bundled with every Hail deploy

PyPI stdio package — intentionally not shipped; see docs/setup/mcp.md

Python SDK

hail-sdk on PyPI, imports as hail

Infrastructure

Docker Compose scaffold

Self-hosted LiveKit SFU

docker compose integration

Architecture

AI agent ──► Hail API ──dispatch──► Voicebot ──► LiveKit Cloud ──SIP──► Twilio ──► 📞

Full diagram: docs/architecture.md.

Contributing

See docs/contributing.md. TL;DR: fork, branch, conventional-commit, PR. Provider adapters go in core/hailhq/core/providers/. Update .env.example for any new env var.

License

Source code: AGPL-3.0-or-later — if you run a modified Hail as a service, you must release your source. Pricing dataset (costs/): CC-BY-4.0 — reuse the pricing JSON freely with attribution.

About

🩵 The universal communication platform for AI agents. Give your agent inbound and outbound phone calls, sms, emails, and more.

hail.so

Topics

twilio

email

mcp

sms

telephony

ai-agents

voice-ai

livekit

Resources

Readme

License

AGPL-3.0 license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity

Custom properties

Stars

15 stars

Watchers

0 watching

Forks

5 forks

Report repository

Releases 19

hail CLI v0.14.0

Latest

Jul 18, 2026

+ 18 releases

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 81.0%

Go 13.8%

TypeScript 2.7%

CSS 0.8%

HCL 0.7%

JavaScript 0.6%

Other 0.4%