pbx

A terminal UI dashboard for monitoring an Asterisk PBX via AMI (Asterisk Manager Interface).

Features

  • Peers tab (p) — live SIP/PJSIP peer status with IP address, port, type, RTT, and last-change time
  • Calls tab (c) — active channel tracking with state, dialplan app, connected party, and duration
  • Queues tab (q) — queue summary with strategy, callers waiting, available/total agents, completed, abandoned, and average hold time
  • All three tabs update in real time from the AMI event stream
  • Press e or Esc or Ctrl-C to quit; press i for the info modal

Requirements

  • Ruby >= 3.2
  • An Asterisk PBX with AMI enabled

Installation

git clone https://github.com/emilianodellacasa/pbx
cd pbx
bundle install

Usage

bundle exec exe/pbx monitor --host HOST --port PORT --user USER --secret SECRET

All flags are optional and fall back to the values in the config file, then to built-in defaults (127.0.0.1:5038).

Options

Flag Default Description
--host 127.0.0.1 AMI host
--port 5038 AMI port
--user — AMI username
--secret — AMI password
--config, -c — Path to a YAML config file
--debug — Write raw AMI traffic to /tmp/pbx_debug.log

YAML configuration

Create a file (e.g. ~/.pbx.yml) and pass it with -c:

host: pbx.example.com
port: 5038
user: monitor
secret: s3cret

CLI flags override YAML values; YAML values override built-in defaults.

Keyboard shortcuts

Key Action
p Peers tab
c Calls tab
q Queues tab
↑ / ↓ Scroll the active table
i Info modal
e / Esc / Ctrl-C Quit

AMI user setup

The monitor only needs read access — it issues just Login, SIPpeers, PJSIPShowEndpoints, QueueStatus, Events and Logoff, none of which require a write class. A minimal /etc/asterisk/manager.conf entry:

[monitor]
secret = s3cret
read = system,call,agent,reporting,dialplan

system covers peer and endpoint discovery, agent and reporting the queue events, call the channel events and dialplan the Newexten app updates.

Development

bundle exec rspec        # run the test suite
bundle exec standardrb   # check code style
bundle exec standardrb --fix  # auto-fix style violations

Releasing

Releases are published to RubyGems by .github/workflows/release.yml, triggered by pushing a v* tag. The workflow refuses to publish unless the tag matches Pbx::VERSION, the suite and linter pass, and the version is not already on RubyGems.

One-time setup: add a RubyGems API key with the push scope to this repository as the RUBYGEMS_AUTH_TOKEN secret (Settings → Secrets and variables → Actions). The name matches the secret the ruby-asterisk repo already uses; GitHub secrets do not cross repositories, so it has to be added here too even if that token is reused.

To cut a release:

# 1. bump the version
$EDITOR lib/pbx/version.rb
bundle install                     # refresh the version in Gemfile.lock
git commit -am "Release v0.2.0"

# 2. tag and push — pushing the tag is what publishes
git tag v0.2.0
git push origin main --tags

bundle exec rake release (from bundler/gem_tasks) also works for publishing by hand; allowed_push_host in the gemspec keeps either path pointed at rubygems.org.