Fonoster: self-hosted voice agents on real phone lines, in the middle of a rebuild
🚀 The open-source alternative to Twilio.
At a glance
- What is it?
- Fonoster is an MIT-licensed TypeScript platform, pitched as an open-source alternative to Twilio, for running AI voice agents and programmable call flows on your own servers or on Fonoster Cloud. Its README opens with a warning about breaking changes and paused contributions, and that warning should shape any adoption decision right now.
- Who is it for?
- Fonoster suits a developer who wants phone-line voice agents under an MIT licence, is prepared to run Routr, RTPEngine, Postgres, NATS and the rest of the bundle, and can absorb breaking changes while the platform is rebuilt. It does not suit a team that needs a stable API this quarter or plans to contribute code, since the README pauses contributions.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- fonoster/fonoster8,166 ★ · +47
| Repository | 2026-09-22 | 2026-11-14 |
|---|---|---|
| fonoster/fonoster | 8.1k | 8.2k |
47 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
An Autopilot agent is one YAML file naming three providers
The shortest path to a working phone agent in Fonoster is Autopilot. An agent is a YAML file with a name, the type AUTOPILOT, and three provider blocks. speechToText points at a productRef such as stt.deepgram with the model nova-3 and languageCode multi. textToSpeech points at tts.deepgram with the voice aura-asteria-en. intelligence points at llm.openai, and its conversationSettings carry the firstMessage, the systemPrompt, a goodbyeMessage and a systemErrorMessage that the caller hears when something fails. The example agent books appointments for a dental clinic.
The file is deployed with the fonoster command-line tool:
# Install the fonoster command
npm install -g @fonoster/ctl
# Log in once with an API key from your workspace
fonoster workspaces:login
# Create the agent
fonoster applications:create -f agent.yamlThe agent answers nothing until a phone number points at it, which happens in the dashboard or with fonoster sipnet:numbers:create. Autopilot also handles tools, a knowledge base and call transfers. Each productRef is an external service, so a working agent needs accounts and keys with those providers in addition to Fonoster itself.
Voice Applications get one signed WebSocket session per call
When a YAML agent is not enough, Fonoster hands the call to your own code. For every call it opens a single signed WebSocket session to your application, following the protocol in docs/session-protocol.md. Two SDKs wrap that protocol: @fonoster/voice for TypeScript and fonoster-voice for Python. In the TypeScript example, a VoiceServer listens on port 3000 and receives a session object per call; AppBridge signs every connection, and the server needs APP_SIGNING_SECRET set to the application's signing secret.
The session verbs cover the usual call-control vocabulary. say speaks text or a stream of model tokens and reports what the caller heard. gather waits for speech or keypresses, with options such as maxDigits and finishOnKey. play and playDtmf send media or tones, transfer does cold, warm or SIP REFER transfers to a number or SIP URI, and hold, resume, handoff and hangup do what their names say. The audio verb exposes raw call audio in both directions, for teams that want their own speech stack instead of the catalog providers. Events arrive for turns, partial transcripts and keypresses.
Outbound calls go through @fonoster/sdk and an access key ID
Originating a call is an API call rather than a dialplan entry. The @fonoster/sdk example creates an SDK.Client with an accessKeyId (the sample value starts with WO followed by zeros), logs in with loginWithApiKey using an API key and secret, then builds an SDK.Calls object and calls createCall with a request containing from, to and an appRef that names the application to run when the callee answers.
This split matters when designing a system around Fonoster. Credentials live with the client, and call logic lives in the application that appRef names, so an outbound call runs the same kind of Autopilot agent or Voice Application that handles inbound calls. Access control sits on top: the feature list names multitenancy, OAuth2 and JWT authentication, and role-based access control. Code written against the earlier gRPC SDK has its own guide, docs/migrating-to-sessions.md, which explains what changed with the session model.
Self-hosting runs a dozen services and needs your host's IP in two variables
Running Fonoster yourself means running its whole telephony stack. The self-host bundle in ops/bundle/compose.yaml starts NATS with JetStream, Postgres, Routr, RTPEngine, the Go Roomr node, AppBridge, MinIO, the API server, Envoy, the dashboard and the hosted Autopilot. Asterisk and InfluxDB, which older deployments used, are gone. The root compose.yaml layers a development file on top that builds from source, with profiles named regions, fakes and tools.
The easy route generates configs, keys and secrets and starts both files:
ops/rebuild/stack upRunning compose directly needs the inputs that script generates:
docker compose --env-file ops/rebuild/.local/.env up -dHTTPS is the bundle's default, using a certificate the stack writes to ops/rebuild/.local/config/tls/, so clients have to trust its ca.pem. In .env.example, ROUTR_EXTERNAL_ADDRS and ROUTR_RTPENGINE_HOST must be set to the host's IP address, which on a cloud server is its public IP. The external address has to be one that all endpoints can reach. ROOMR_PASSWORD and POSTGRES_PASSWORD ship with defaults that must be changed in production. DASHBOARD_API_URL defaults to http://localhost:8449; without the right public URL the dashboard only shows a configuration error. The compose file states that it is the smoke and CI harness, not a development path; developers are pointed at the dev container instead.
Breaking changes are announced and outside contributions are paused
The README opens with a warning block: major upgrades are underway, the team is moving fast, and users should expect breaking changes and some instability for a while. Contributions are paused, though bug reports through the issue template are still welcome.
For someone evaluating Fonoster, this has two direct consequences. First, an integration written today against the session protocol, the CLI or the configuration files may need rework after an upgrade, and there is no stated end date for that period. Second, a team that finds a gap cannot fix it upstream through a pull request for now; it can file a bug, fork, or wait. Organisations that need a supplier who will accept patches, or a frozen interface for a production phone line, should treat this warning as the main fact about the project rather than a footnote.
Three releases in one day on a 0.x version line
Fonoster is still versioned below 1.0. Releases v0.47.0, v0.47.1 and v0.47.2 all shipped on 2026-10-31, and the last push to main was on 2026-11-01. The root package.json uses Lerna with independent versioning across the mods/* and tools/* workspaces, and the release script publishes to the latest dist tag with a version computed by ops/release/next-release.sh.
Independent versioning means @fonoster/ctl, @fonoster/sdk, @fonoster/voice and the other packages do not share one number, so pinning one package does not pin the rest. Combined with the rebuild warning, the safe practice is to record the exact version of every Fonoster package you install and upgrade them together after reading the release notes. Postinstall also runs a Prisma generation step across workspaces, which is one more thing to account for when building from source.
Operator guides for webhooks, call records, providers and regions
Beyond the external docs at docs.fonoster.com, which cover Docker self-hosting and the quickstart, the repository carries its own guides under docs/. docs/try-the-new-platform.md is the local walkthrough. docs/webhooks.md covers workspace webhook events, signatures and retries, and how to move off the older eventsHook setting. docs/call-records.md covers what a call record contains, retention and erasure, redaction and verification. docs/providers.md explains catalog ids, bringing your own keys and deprecation warnings for providers.
Operators get three more: deployment in docs/operators/rebuild.md, regions in docs/operators/regions.md and the provider registry in docs/operators/registry.md. Sign-in methods, sign-up and billing are switched through features.* in config/fonoster.yaml, while the API server and Autopilot read config/fonoster.yaml and config/autopilot.yaml copied from their example files. Anyone handling recorded calls should read the call-records guide before going live, because retention and redaction are decisions the operator owns once the platform runs on their servers.
Editorial conclusion
Fonoster suits a developer who wants phone-line voice agents under an MIT licence, is prepared to run Routr, RTPEngine, Postgres, NATS and the rest of the bundle, and can absorb breaking changes while the platform is rebuilt. It does not suit a team that needs a stable API this quarter or plans to contribute code, since the README pauses contributions. Before committing, run ops/rebuild/stack up on a test host, place a call through an Autopilot YAML agent, and check which release your SDK version pairs with.
Frequently asked questions
Is Fonoster an open-source alternative to Twilio?
Fonoster describes itself as the open-source alternative to Twilio. It is an MIT-licensed platform for building, testing and running voice agents on real phone lines, on Fonoster Cloud or your own servers.
Is Fonoster free?
The Fonoster code is released under the MIT License by Fonoster Inc, and it can be self-hosted with Docker Compose. Fonoster Cloud is the hosted option.
How do I deploy a Fonoster Autopilot agent?
Install the CLI with npm install -g @fonoster/ctl, log in with fonoster workspaces:login, then run fonoster applications:create -f agent.yaml. Point a phone number at the new application to take calls.
Can I contribute to Fonoster right now?
The Fonoster README says contributions are paused during major upgrades, while bug reports are still welcome through the issue template.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/fonoster-fonoster)Star history chart for your README
[](https://hysenlabs.com/projects/fonoster-fonoster)Was this useful?