iperfex/ivoicetracex repository overview

⁠iVoiceTraceX

A SIP forensic analyzer with a softphone inside it, in a single binary — built for people and for AI agents alike.

• Product: https://www.iperfex.com/productos/ivoicetracex/⁠
• Documentation: https://www.iperfex.com/productos/ivoicetracex/docs/⁠
• Image: iperfex/ivoicetracex:latest — linux/amd64, distroless, ~16.5 MB compressed

The capture is the point: it reads the network passively and shows the SIP dialogs, the RTP and the audio in the browser. It never touches the call, and nothing has to be installed on the PBX.

The phone is there so the call under audit can be your own: the same server is a media gateway between WebRTC (browser) and SIP/RTP (PBX), so you talk and you audit on the same screen and neither one interrupts the other.

Everything the panel does is also exposed to AI agents — Claude, OpenAI, anything that speaks MCP — over the -mcp socket, and to an agent running inside the page over WebMCP. One catalogue, one contract.

Browser (microphone/headset)
    ↕  WebRTC (Opus/RTP over ICE)
iVoiceTraceX  [this image]
    ↕  SIP/RTP
PBX / SIP server

⁠Quick start

A softphone gateway uses SIP/RTP over UDP with high ports announced in the SDP, so host networking is the right answer in almost every case.

docker run -d --name ivoicetracex \
  --network host \
  --user 0 --cap-drop ALL --cap-add NET_RAW \
  -v ivoicetracex-spool:/var/tmp/ivoicetracex \
  iperfex/ivoicetracex:latest \
  -sip-host 192.168.1.100 -sip-user 1001 -sip-pass secret -web :8443 -tls

Then open https://<host-ip>:8443 and accept the self-signed certificate. Wait for the Registered indicator, dial, and use the SIP Trace button to audit the signaling and media of the call in course.

⁠With environment variables instead of flags

docker run -d --network host --user 0 --cap-drop ALL --cap-add NET_RAW \
  --env-file .env iperfex/ivoicetracex:latest

Generate that .env once with the binary itself (ivoicetracex -sip-host … -env) or write it by hand — see the key list below.

⁠docker compose

name: ivoicetracex

services:
  ivoicetracex:
    image: iperfex/ivoicetracex:latest
    container_name: ivoicetracex
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_RAW
    user: "0"            # required — see the warning below
    env_file:
      - .env
    volumes:
      - ivoicetracex-spool:/var/tmp/ivoicetracex

volumes:
  ivoicetracex-spool:

⁠⚠ The capture needs uid 0, not just --cap-add NET_RAW

If the trace is empty inside Docker while the softphone works fine, this is why. Running as a non-root user with --cap-add NET_RAW is not enough. Docker puts the capability in the container's bounding set, but a non-root process only gets it in its effective set through file capabilities on the binary or ambient capabilities from the runtime — and Docker sets neither. The daemon registers, places calls and serves the panel perfectly; the capture is off, with a single SIP capture disabled warning at startup that nobody reads twice.

The base image is distroless/static-debian12:nonroot (uid 65532), so run it with --user 0 and NET_RAW as the only capability — a smaller privilege in practice than the whole default capability set:

--user 0 --cap-drop ALL --cap-add NET_RAW

Verified both ways: as uid 65532 with NET_RAW the daemon logs SIP capture disabled; as uid 0 with NET_RAW and everything else dropped, it logs SIP trace capture running.

⁠Image contents

System dependencies: none. Audio is forwarded in pass-through — the raw RTP payload travels end to end without transcoding — so no codec library is linked. The web panel ships inside the executable, the TLS certificate is generated in memory, and the capture reads straight from a raw packet socket. There is nothing to install, nothing to mount and nothing to configure on the PBX.

There is also a scratch variant of this image with no distribution underneath at all — just the binary, the CA bundle and the timezone database.

⁠Volume: why you want it

/var/tmp/ivoicetracex is the RTP spool. RTP goes to disk by default so each call is kept whole no matter how long it lasts (the bound becomes free disk space instead of RAM). Without a volume the spool dies with the container and the captured audio of past calls goes with it.

⁠Timezone

The image ships tzdata; set TZ or every timestamp is reported in UTC — which is not a crash, it is worse: a trace whose times do not line up with the PBX log you are reading it against.

-e TZ=America/Argentina/Buenos_Aires

⁠Configuration

Only -sip-host, -sip-user and -sip-pass are required; everything else is optional. Precedence: CLI flags > .env next to the binary > environment variables > defaults.

Every flag has an environment-variable equivalent, so the table below reads both ways. The live, authoritative list is docker run --rm iperfex/ivoicetracex:latest -h.

Full reference with a worked example per flag — all 42 of them: Startup options⁠.

⁠Features

Telephony

• SIP registration (REGISTER) with retry and periodic re-registration
• Outgoing (INVITE) and incoming calls (manual answer or auto-answer)
• Outgoing DTMF (RFC 4733) to navigate IVRs
• Audio pass-through without transcoding: Opus, PCMU (ulaw), PCMA (alaw)
• Automatic codec detection (self-call probe) + WebRTC renegotiation
• MWI / voicemail banner (NOTIFY message-summary)
• Mute, real hold (re-INVITE, so the PBX plays MoH), DTMF keypad, auto-answer
• Keyboard shortcuts, synthesized ringtone, desktop notification
• A call survives a browser F5 (it lives in the backend)
• Interface in English, Spanish and Portuguese, switchable in place

SIP analysis — capture options⁠

• Part of the core: one passive capture (SIP + RTP) always running, no flag to turn it on
• In the browser, without interrupting the call in course: SVG ladder, filters, forensic report
• Self-contained capture: no capture agent, no kernel module, nothing on the PBX
• Captured RTP audio playable from the browser; export to pcap / txt / WAV
• Content analysis (level, real silence, longest gap, clipping, in-band DTMF) decoding G.711 and Opus server-side — it catches one-way audio in streams whose loss/jitter/MOS look perfect
• One dialog, one life: signaling, streams, metrics and audio are discarded together

AI control (MCP / WebMCP) — MCP server⁠

• MCP server (-mcp): an AI host drives the softphone and the trace over a local Unix socket
• WebMCP: the same catalog for an agent inside the already-authenticated tab
• Headless audio: the AI talks (injects .wav/.opus) and listens (records both directions to WAV) on a real call, with no browser attached
• 30 tools: call control, state and events, the full SIP trace, captured audio

Media / WebRTC / NAT

• WebRTC ↔ SIP/RTP media gateway
• Built-in local STUN server (default), optional remote STUN and additive TURN

⁠Documentation

Full documentation — https://www.iperfex.com/productos/ivoicetracex/docs/⁠ (available in Spanish, English and Portuguese: add ?lang=en or ?lang=pt).

⁠Usage responsibility