Getting started

Install

The SIP stack (baresip, libre, OpenSSL) is built in — no separate baresip install needed.

Homebrew (macOS / Linux):

brew install davidborzek/tap/ringo-flow

Arch Linux (AUR) — prebuilt, via any AUR helper:

yay -S ringo-flow-bin   # or: paru -S ringo-flow-bin

Nix (flake):

nix profile install github:davidborzek/ringo#ringo-flow

To run scheduled monitors as a systemd service, use the NixOS module.

Enable the binary cache first (cachix use ringo) so this is a download instead of a long build; see ringo-phone’s install notes for NixOS settings and pinning a released version (github:davidborzek/ringo/ringo-flow-v<version>#ringo-flow).

Pre-built binaries for Linux and macOS (x86_64 + arm64) are on the releases page — download, extract and put ringo-flow on your $PATH.

With cargo-binstall — the same prebuilt binary, no compile:

cargo binstall ringo-flow

From crates.io (compiles, needs a C toolchain and CMake):

cargo install ringo-flow

From GitHub (no clone needed):

cargo install --git https://github.com/davidborzek/ringo ringo-flow

From a workspace checkout (no install):

cargo run -p ringo-flow -- run scenario.js

Docker — an image with everything compiled in is published to GHCR on each release; see Running in CI:

docker run --rm --network host -v "$PWD/scenarios:/scn:ro" \
  ghcr.io/davidborzek/ringo-flow:latest run /scn

The pre-built binaries, cargo binstall and cargo install link the opus and spandsp libraries at runtime — install them first (libopus0 libspandsp2 on Debian/Ubuntu, opus spandsp with Homebrew or pacman). Homebrew, the AUR package and Nix pull them in for you.

Homebrew 6.0+ requires third-party taps to be trusted before use. If brew install prompts you to trust the tap, accept it — or trust it up front:

brew tap davidborzek/tap
brew trust --formula davidborzek/tap/ringo-flow

Run a scenario

Credentials and the SIP domain come from the environment (via env(...)), so nothing sensitive lives in the script:

SIP_DOMAIN=example.com A_USER=alice A_PASS=… B_USER=bob B_PASS=… \
  ringo-flow run scenario.js

ringo-flow run scenario.js     # one file
ringo-flow run scenarios/      # a directory (all *.js, recursively)
ringo-flow check scenario.js   # syntax-check only (no SIP traffic)

The exit code is non-zero if any scenario fails.

The frontend follows the file extension, so there is nothing to configure: .js runs on the JavaScript frontend, .rhai on the deprecated Rhai one.

Editor support

Write the type definitions next to your scenarios once, and any editor with TypeScript support checks the whole DSL as you type:

ringo-flow definitions --lang js ringo-flow.d.ts

// jsconfig.json — next to your scenarios
{
  "compilerOptions": {
    "checkJs": true,
    "strict": true,
    "noEmit": true,
    "target": "es2022",
    "module": "esnext",
    "types": []
  },
  "files": ["ringo-flow.d.ts", "scenario.js"]
}

Start each scenario with // @ts-check to get the same errors on the command line via tsc --noEmit. For authoring in real TypeScript, see Writing scenarios.

Useful flags

• --scenario <pattern> — run a subset by name (re: for a regex).
• --tag <tag> / --exclude-tag <tag> — filter by tag (repeatable, comma-separated).
• --env-file FILE — load variables for env(...) (a sibling <scenario>.env is layered on top per file).
• --log [<file>] — write the backend/SIP log to stderr (or a file); off by default.
• --sip-trace [<file>] — trace every SIP request/response to its own destination (stderr, or a file); separate from --log, off by default. A .pcap path writes a capture for sngrep/Wireshark — see Debugging.
• --save-audio — save sent/received WAVs to the working directory.
• --json — emit NDJSON events (for CI).
• -q / -v, --no-color.

See ringo-flow run --help for the full list.