Tech facts
What MonoPbx is made of, what it runs on and how to install it. The short version for decision makers, and the details for administrators.
At a glance
- Architecture
- A SIP back-to-back user agent written in Rust, rtpengine for media, a web console and REST API, PostgreSQL for configuration, Valkey for cache and events, ClickHouse for call history and analytics.
- Signalling
- SIP over UDP, TCP and TLS. SIP over WebSocket for the browser phone.
- Media
- RTP and SRTP through rtpengine, WebRTC for browsers, STUN and TURN for phones behind NAT.
- Codecs
- Opus, G.722, G.711, G.729. AMR and AMR-WB for IMS handsets, with transcoding.
- Several companies
- One install can host many companies. Their data is kept apart row by row in PostgreSQL.
- API
- REST with an OpenAPI document, signed webhooks, an events WebSocket and an MCP server.
- Languages
- Console and apps in nine languages: English, Spanish (Mexico), Portuguese (Brazil), French, German, Italian, Russian, Chinese and Japanese.
Scale
In our lab, one small node carried 600 simultaneous calls with media. No call failed, and call setup took under 150 ms at the 95th percentile. That was measured on one shared development machine, so treat it as an order of magnitude. For your own site, use the sizing calculator. Sizing calculator →
Requirements and supported systems
- Linux package and VM installer
- Ubuntu 24.04 LTS, amd64 or arm64.
- Docker Compose
- Any 64-bit Linux host with Docker 24 or newer and Compose 2.24 or newer.
- Kubernetes
- Version 1.30 or newer. Plain manifests with Kustomize.
- Machine to start
- 2 CPUs, 4 GB RAM, 20 GiB free under /var/lib.
- Network
- A public IP address. A DNS name is optional.
- IMS mode
- Optional. The P-CSCF and the ePDG run on Linux and need CAP_NET_ADMIN. See the IMS section below.
Install on your own server or cloud VM
At any cloud provider or on your own hardware, create an Ubuntu 24.04 virtual machine, open the ports listed below and run the one-line installer. Each method runs the same MonoPbx.
Virtual machine or cloud server
Ubuntu 24.04 LTS
The VM installer sets up a single-node install on a fresh server. The apt package includes it.
VM guide →Linux package
Ubuntu 24.04 LTS
One command installs Docker, the production bundle and a monopbx command, and gets a Let’s Encrypt certificate.
apt guide →Docker Compose
64-bit Linux with Docker 24+
The production bundle with Postgres, Valkey, ClickHouse and rtpengine, for hosts you already manage.
Compose guide →Kubernetes
Kubernetes 1.30+
Plain manifests applied with kubectl apply -k (Kustomize). There is no Helm chart. Read the notes on media through NAT first.
Kubernetes guide →
Linux package, step by step
On a fresh Ubuntu 24.04 server with a public IP, run:
curl -fsSL https://ilinaya.github.io/monopbx-apt/install.sh | sudo bash
Setup asks for an e-mail address for the Let’s Encrypt certificate. Add your own domain too; without --domain the server is named <ip>.sslip.io:
curl -fsSL https://ilinaya.github.io/monopbx-apt/install.sh | sudo bash -s -- --domain pbx.example.com --email you@example.com
Then
- Open the console. The installer finishes by printing your console address and a one-time setup link. Lost it? sudo monopbx setup-url prints a new one.
- Create your account. E-mail, password, then a code from your authenticator app. This is the first administrator of your PBX.
- Your 7-day free trial starts. Everything is switched on. Add a SIP trunk, create extensions, and sign in to MonoPhone with the QR code.
curl -fsSL https://ilinaya.github.io/monopbx-apt/install.sh | sudo bash -s -- --domain pbx.example.com --email you@example.com
==> Prerequisites
==> MonoPbx APT repository: https://ilinaya.github.io/monopbx-apt
signing key verified: 320D C78E FDC8 439C 04F5 FCA6 3E87 FE3D 4C71 5372
==> Installing monopbx (with Ubuntu's docker.io and docker-compose-v2 unless Docker is already installed)
==> monopbx setup --domain pbx.example.com --email you@example.com
…
==> MonoPbx is ready
console: https://pbx.example.com
web softphone: wss://pbx.example.com/sip
SIP: pbx.example.com port 5060 (UDP/TCP), 5061 (TLS)
first admin: open the single-use setup link printed above (.../setup#token=...)
manage: monopbx status | logs | sudo monopbx backup | upgrade | uninstall
Ports
80/tcp | Certificate challenge, redirect to HTTPS |
|---|---|
443/tcp | Console, API, browser phone (wss://…/sip) |
5060 udp+tcp | SIP |
5061/tcp | SIP over TLS |
30000–40000/udp | RTP audio. Without it calls connect but nobody hears anything. |
If ufw is active, setup opens these ports. Open the same ones in your cloud firewall.
IMS mode (VoLTE and VoWiFi)
Optional and off until an administrator switches it on. It turns MonoPbx into the IMS core for your own SIM cards.
- Components
- The PBX engine, an optional P-CSCF role for VoLTE and an optional ePDG (mpbx-epdg) for VoWiFi. They talk over authenticated links on a private network.
- Protocols
- SIP with IPsec (TS 33.203), IKEv2 with EAP-AKA’, Diameter Cx and Rx over TCP or SCTP with optional TLS, HTTP Nudm and N5, SMS over IMS.
- Subscriber data
- Kept in MonoPbx, or in your HSS over Diameter Cx, or in a 5G UDM over Nudm.
- Requirements
- Linux for the P-CSCF and the ePDG, with CAP_NET_ADMIN. A public address and a certificate for the ePDG. SIM keys, or an HSS or UDM that holds them. A media server that can encode AMR if you use mobile codecs.
500, 4500/udp | ePDG: IKEv2 and ESP in UDP (VoWiFi) |
|---|---|
5064, 5065 (defaults) | P-CSCF: SIP from handsets through the IPsec tunnel (VoLTE) |
Diameter peer port, tcp or sctp | Outbound to your HSS or PCRF |
IMS, VoLTE and VoWiFi → · Operator guide →
Security facts
- Recordings and files are encrypted on disk. CRM and provider credentials are sealed with your company key.
- Passkeys, two-factor sign-in, OpenID Connect single sign-on, SCIM and an IP allow-list for administrators. Optional reCAPTCHA on sign-in with your own keys.
- Automatic IP bans on the SIP side and the web side, with one list you can review.
- Geo blocking, allow and deny lists and STIR/SHAKEN on the SIP edge. SRTP can be optional or required per trunk.
- Audit log, change history, and scheduled encrypted backups that restore onto a new host.
- Calls, recordings and history never pass through us. Only the push notification that wakes a phone uses the push relay, and you can install without it.