VoxyWatch integration guide

VoxyWatch receives HEP (Homer Encapsulation Protocol) packets — it does not mirror traffic by itself. Your SBC or media server must be configured to send HEP to VoxyWatch's IP and port. This guide covers installation, the ports involved, and how to point the most common SBCs at VoxyWatch.

📦 Full release notes, packages and GPG signatures: github.com/VoxyWatch/publish

Quick install

One command installs everything. It auto-detects your distro (Debian 11+, Ubuntu 20.04+, RHEL / CentOS / Rocky / AlmaLinux 8+) and installs the correct package:

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/publish/main/install.sh | sudo bash

After installation, open the portal at https://YOUR-IP. The default login is admin / voxywatch (you must change it on first login). No license needed to start: the free tier gives you up to 50 concurrent calls with unlimited CDRs. When you outgrow it, buy a license and drop in the .key file.

Activate a license

Get your Hardware ID (needed when purchasing) with node /opt/voxywatch/get-hwid.js, or find it in Settings → License. Then:

# Copy your license file into the config directory
cp voxywatch.key /etc/voxywatch/license.key
chown root:voxywatch /etc/voxywatch/license.key
chmod 640 /etc/voxywatch/license.key

No restart required — the portal picks it up within seconds. Manual packages and GPG verification are documented on GitHub.

Manual install & verification

Prefer to install by hand? Open the latest signed release and download its package, checksum and matching .asc signature. Package names can change, so this page intentionally does not pin a release number.

Verify the package signature (GPG)

Every release is signed. To verify before installing:

# Import the release signing key (first time only)
curl -fsSL https://raw.githubusercontent.com/VoxyWatch/publish/main/voxywatch-release.gpg.pub | gpg --import

# Download the package and its matching .asc file from Releases, then verify
gpg --verify DOWNLOADED_PACKAGE.asc DOWNLOADED_PACKAGE

Signing key fingerprint: 80ED E252 3760 E622 FB97 BC15 4B21 BBC5 F215 26E3 — VoxyWatch (Release Signing Key) <[email protected]>. SHA-256 checksums are in SHA256SUMS on the release page.

What's installed

File layout: /opt/voxywatch/ (binaries, read-only) · /etc/voxywatch/ (config + license key) · /var/lib/voxywatch/ (database, captures & audio — preserved on upgrade).

Manage the services

# Status
systemctl status voxywatch voxywatch-sniffer

# Logs
journalctl -fu voxywatch
journalctl -fu voxywatch-sniffer

# Restart
systemctl restart voxywatch voxywatch-sniffer

Upgrade

The portal shows an update banner when a new version is available — click Update now and it downloads, installs and restarts itself. To upgrade manually, re-run the install command above.

Ports & firewall

SBC integration

VoxyWatch ingests your voice traffic two ways. HEP is tested and supported in production. SIPREC is available through a built-in recording server (SRS) and is currently in active beta. Anything that emits neither can still be captured with the voxywatch-probe.

HEP — tested & supported

Point each platform's HEP exporter at VOXYWATCH_IP:9060 (the port is configurable). Tested: Asterisk, Kamailio, OpenSIPS, FreeSWITCH, RTPEngine, Sansay VSXi, AudioCodes Mediant.

SIPREC — native recording server (beta)

VoxyWatch includes a native SRS (Session Recording Server) implementing RFC 7865/7866. Any tier-1 SBC that speaks SIPREC — Oracle/ACME Packet, Ribbon/Sonus, AudioCodes, Cisco CUBE, Avaya — can stream its recording session straight into VoxyWatch, with no HEP agent or port mirroring. SIP over UDP or TLS, media RTP or SRTP (SDES), stereo caller/callee audio reconstructed from rs-metadata. It runs as a separate service, is OFF by default, and ships with an SBC IP allowlist and anti-DoS limits.

SIPREC is in active beta. Turn on the SRS in Settings → Capture → SIPREC, add your SBC's source IP to the allowlist, and point your SBC's recording profile at the SRS host:port. If you run one of these SBCs, reach out via support ticket to validate on your equipment.

voxywatch-probe — capture from anywhere

VoxyWatch ships with an optional lightweight capture agent, voxywatch-probe (Go + libpcap). It sniffs SIP/RTP/RTCP straight off the NIC and forwards HEP v3 to your VoxyWatch server. Use it when your SBC can't emit HEP natively, or as a drop-in HEPlify replacement.

Install on the PBX/SBC server (passive sniffing, never touches your config):

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/voxywatch-probe/master/install.sh | sudo bash -s -- --server YOUR_VOXYWATCH:9060

The installer detects the architecture, downloads the binary, grants it capture permissions, auto-detects the interface, and leaves it running as a systemd service that starts on boot. Verify with systemctl status voxywatch-probe and journalctl -fu voxywatch-probe — you should see [stats] sip=.. rtp=.. sent=...

Full SBC compatibility matrix and per-model guides: github.com/VoxyWatch/voxywatch-probe/docs/sbc.

SNMP agent & traps

VoxyWatch embeds its own SNMP agent (v2c + v3) so PRTG, Zabbix, Nagios and similar NMS can poll it and receive edge-triggered traps. The same thresholds drive the header notification bell and the SNMP traps, so they always agree.

What it exposes: 30+ OIDs covering host (CPU, RAM, disk), capture (sources, packets, drops), VoIP KPIs (ASR, NER, MOS, jitter, loss) and bottleneck diagnostics.

Traps are fired only on state transitions (no spam) for: capture loss, sniffer down, no sources, low ASR, low MOS, RTP/kernel drops, disk/RAM/CPU high.

Download the MIB and configure community/v3 credentials in Settings → SNMP. Default port: UDP/161 (agent), UDP/162 (trap destination).

🚨 Incidents & the agentic NOC

Every anomaly VoxyWatch detects — trunk degradation, capture loss, sniffer down, silent HEP sources, system bottlenecks, global traffic drops, low audio retention — becomes a persistent incident with a lifecycle (open → acknowledged → resolved), deduplication (one live incident per problem, no alert storms), an auditable timeline, and stability-based auto-resolve.

A dedicated Incidents tab gives you filters, a detail view, and one-click actions. The open-incident badge appears in the nav and the notification bell.

Autonomous investigation

The moment an incident opens, VoxyWatch investigates by itself — no human, no LLM needed yet: sample failing calls, dominant SIP failure codes, failing IP paths, affected destinations, and whether other trunks degraded at the same time (the local-vs-carrier tell). With an LLM key configured, an AI investigator with live tools produces a structured diagnosis: probable root cause, confidence, scope, recommended action — citing the evidence. Budgeted and cached so it can't run up your token bill.

Runbooks & case memory

VoxyWatch ships with field runbooks (low ASR, packet loss, capture down, traffic drop) that the investigator follows and cites step by step. Add your own as JSON. When you resolve an incident and write down the cause, that resolution becomes institutional memory — the next time the same pattern fires, the diagnosis references it.

Statistical confidence

Declaring CRITICAL requires earning it: a minimum sample of calls, measurement coverage for quality metrics, deviation from the trunk's own baseline, and sustained degradation across consecutive evaluations. Validated against production incidents: −92% critical noise versus naive thresholds — without losing a single record.

Safe remediation

Proposed actions come from a closed, code-level catalog (restart the capture sniffer, recompute baselines — never your SBC), execute only after your explicit approval, and land in the incident timeline with who-approved-what.

📲 Telegram & email notifications

Critical incidents reach your phone with the diagnosis attached and inline action buttons: ✅ Ack · ✔ Resolve · 🔍 Investigate · plus the proposed remediation when one applies.

Per-user setup (2 minutes)

1. Your team creates one Telegram bot for the installation — a guided wizard in Settings → Notifications walks you through it.
2. Each portal user links their own chat with a one-time code — no tokens to share, no chat IDs to hunt down.
3. Each user picks their minimum severity and opts into the scheduled digest.

Every action taken from Telegram is audited under the real portal username and gated by role — viewers receive read-only notifications. An optional NOC-room group chat receives everything.

Email

Incidents can also arrive by email: global SMTP with Gmail / Microsoft 365 presets, a step-by-step in-product guide and a live test button.

Digest

A daily or weekly digest (incidents, trunk health, volume vs the previous period, capacity forecast) lands in Telegram or your webhook on schedule — or on demand via API.

🔗 Model Context Protocol (MCP Gateway)

VoxyWatch embeds a native Model Context Protocol (MCP) server. Connect your local IDE (Cursor, VS Code), desktop assistants (Claude Desktop, Antigravity), or AI agents (LangChain, AutoGen, OpenAI Swarm) directly to your NOC telemetry.

Key Capabilities & Security Guardrails

• 12 Read-Only NOC Tools: Exposes real-time traffic volume, trunk MOS health, active incidents, CDR searches, baseline anomalies, capacity forecasts, and Flash Call evidence.
• Zero Shell or SQL Access: The MCP gateway is strictly sandboxed. It cannot execute terminal commands, modify database records, touch raw PCAPs, or control SBC routing.
• Scoped Authentication: Gated by dedicated MCP API keys or OAuth/JWKS with local audit logging and rate limiting.

Configuration & Setup: Read the step-by-step MCP Gateway Configuration Guide on GitHub ↗ for Cursor, Claude Desktop, and custom AI agent integrations.

Flash Call Detector

Flash Call Intelligence passively detects probable missed-call authentication patterns from originator-side CANCEL timing, 487 responses, unanswered calls, absence of media and destination fan-out.

It always operates as observation in Shadow. VoxyWatch receives signaling through HEP or SIPREC, is agnostic to the SBC brand and has no ability to block, reject, reroute or modify calls. Detection is deterministic, local and does not consume AI tokens.

Use the Fraud view to inspect evidence alongside new destinations, high-risk country growth, short-call storms and international-mix anomalies. See the Flash Call guide for prerequisites and interpretation.

🔒 PCI-DSS audio suppression

VoxyWatch is built for environments that handle payments by phone (call centers, IVRs taking card numbers, etc.). The Probe can drop the RTP of a payment window at the source, so sensitive audio (card / CVV) never leaves the secure environment, never travels the network, never reaches VoxyWatch. This is the strictest option — smallest possible PCI scope.

How it works

The Probe hot-reloads a JSON file listing RTP SSRCs to suppress. Any RTP packet matching a listed SSRC is dropped before being sent to VoxyWatch, ensuring payment data never touches your storage or network.

Typical call-center workflow

When an agent pauses recording in their CRM, the CRM adds the call's RTP SSRC to /etc/voxywatch-probe/pci_suppress.json. The Probe instantly stops sending that stream until resumed.

Full Technical Specification: Read the complete voxywatch-probe PCI-DSS Specification on GitHub ↗ for JSON schemas, hot-reloading rules, and two-layer defense parameters.

Server sizing calculator

Use the interactive calculator below to estimate the hardware you need based on your call volume, whether you capture audio, and retention window. Reference numbers — for production peaks dimension up.

NOC AI copilot

The built-in copilot reads the trunk's current KPIs, alarms, learned baseline and 48h trend, and writes back the probable cause and the NOC action — in plain language. It only explains and recommends; it never touches the SBC.

Bring your own key. Configure your provider in Settings → AI:

• OpenAI — GPT-4o / GPT-4o-mini / o1
• Anthropic — Claude Sonnet / Opus
• Google — Gemini 1.5 / 2.0
• OpenRouter — any model from the OpenRouter catalog
• Ollama (Local LLMs) — Llama 3, Mistral, DeepSeek, or any custom model running locally on-premise without external token costs

Responses are cached server-side to control token spend. The copilot is bilingual (EN / ES) and turned off until you enable it; nothing is sent anywhere by default.

Per-trunk copilot answers one trunk at a time. NOC summary copilot prioritises and groups all alarming trunks across the estate and suggests an action per group.

Integration API /api/v1

Read-only versioned REST API for billing and monitoring systems. Stable public schema, decoupled from internals.

Endpoints: CDR search and single CDR, SIP-trace JSON, PCAP and audio download.

Auth. API keys (hashed at rest) with per-key scopes: cdr:read, trace:read, audio:read. Per-key IP allowlists and rate limits. Errors follow RFC 9457 application/problem+json. OpenAPI spec available from the portal.

Manage keys in Settings → API keys. Example:

curl -H "Authorization: Bearer YOUR_KEY" \
     https://YOUR-VOXYWATCH/api/v1/cdr?from=2026-06-01&to=2026-06-07&carrier=acme

Troubleshooting

VoxyWatch shows no packets

# Are packets even arriving?
tcpdump -i any udp port 9060 -n -c 20

# Is the sniffer running and bound?
systemctl status voxywatch-sniffer
journalctl -u voxywatch-sniffer | grep "UDP\|TCP"

Packets arrive but no SIP data

Check for a HEP version mismatch — set the SBC to HEPv3 (VoxyWatch auto-detects from the magic bytes). If trusted_prefixes is set in Settings, make sure the SBC IP matches, or set it to empty to accept from any source.

No RTP quality stats

RTP quality needs RTCP packets via HEP (low bandwidth, preferred). Enable RTCP on your SBC — for RTPEngine add RTCP to homer-capture; for Asterisk load res_hep_rtcp.so.

Audio reconstruction fails

Reconstruction needs SIPREC RTP streams in the capture and has_audio = true on the CDR. Verify python3 --version and disk space in /var/lib/voxywatch/.

Faturação, pagamentos e cancelamentos

Os pagamentos, os registos de pagamento e os cancelamentos das licenças VoxyWatch são geridos pela Paddle.com, o nosso processador de pagamentos. A Paddle atua como Merchant of Record (MoR) em cada compra.

Para gerir a sua assinatura — cancelar, atualizar o método de pagamento ou descarregar faturas — use o portal de clientes da Paddle:

Abrir o portal de clientes da Paddle

Inicie sessão com o e-mail usado na compra (acesso por link mágico, sem palavra-passe).

Cancelar uma assinatura

Ao cancelar no portal, o cancelamento é agendado para o fim do seu período de faturação atual. A sua licença permanece ativa até à próxima data de renovação e não é renovada depois disso. Nenhum dado é eliminado quando uma licença expira.

Reembolsos

Os pedidos de reembolso são tratados segundo a nossa Política de reembolso. Como a Paddle é o Merchant of Record, os reembolsos são emitidos através da Paddle.