NovaNode Telephony DevKit

See PARTNER_MANUAL.md for the complete lab setup, operation, troubleshooting, and npm release guide. See CHANGELOG.md for release notes.

nn is a terminal development station for the NovaNode Asterisk lab. It combines PBX status, a baresip controller, calls, trunks, AMI events, diagnostics, automated test calls, and Claude/Codex usage in one TUI.

The old NovaNode chat has been removed. The usage dashboard contains Claude Code and Codex CLI only.

Run From This Repo

No installation or sudo is required:

./bin/nn --help
./bin/nn pbx detect
./bin/nn pbx doctor
./bin/nn pbx
./bin/nn pbx phone

Run the first operational lab test with:

./bin/nn pbx test-call

This exercises the established route: baresip → nn-pbx TLS 5061 → extension 3000 → LiveKit SIP → room → bbva-lab-local agent.

To make nn available in the current shell:

export PATH="$PWD/bin:$PATH"
nn pbx doctor

Or link it into a user-owned bin directory:

mkdir -p "$HOME/.local/bin"
ln -sf "$PWD/bin/nn" "$HOME/.local/bin/nn"
export PATH="$HOME/.local/bin:$PATH"

Commands

nn                       Open the PBX TUI
nn usage                 Open the usage tab
nn pbx                   Open the PBX tab
nn pbx setup             Detect, propose, back up, confirm, and configure AMI
nn pbx detect            Inspect Asterisk/PJSIP over SSH
nn pbx doctor            Validate the six lab sections
nn pbx phone             Control baresip on Fedora
nn pbx test-call         Test extension 3000 through LiveKit
nn calls                 Show active channels
nn trunks                Show outbound registrations
nn debug                 Show AMI/debug state

nn-pbx is a convenience alias for nn pbx. novanode remains only as a compatibility alias to nn; it no longer contains chat functionality.

Lab Model

• Fedora Workstation hosts KVM and baresip.
• The nn-pbx Debian VM runs Asterisk 22.10.1 with chan_pjsip.
• Network SIP enters on TLS 5061; UDP 5060 is loopback-only.
• LiveKit uses outbound TLS transport 5062 and an ulaw SIP leg.
• RTP is anchored on Asterisk in 20000-20999/udp with SDES-SRTP.
• Local endpoints are 1001, 1002, and 2000; 3000 routes to LiveKit.
• AMI is restricted to 127.0.0.1:5038 and reached through an SSH tunnel.
• ARI remains disabled.

Setup Safety

nn pbx setup detects before changing anything. It shows a proposal, requires confirmation, backs up manager.conf to manager.conf.novanode-bak, and writes a separate manager_novanode.conf include owned by NovaNode.

It does not modify PJSIP transports, endpoints, the [from-nn] dialplan, RTP settings, or LiveKit configuration.

Secrets are never stored in this repository. Local credentials use ~/.config/novanode/secrets.json with mode 0600, or these environment variables:

export NOVANODE_AMI_SECRET='...'

The baresip phone adapter expects a running baresip process on Fedora with ctrl_tcp listening on loopback port 4444. Configure its Fedora SSH host during nn pbx setup.

Usage Dashboard

./bin/usage
./bin/usage connect
./bin/nn-usage
./bin/nn-usage --summary-tsv
./bin/nn-usage --json

usage is the short alias for nn-usage; both commands have the same options.

Only Claude Code and Codex CLI are queried.

Connect Providers

Open the provider connection hub:

usage connect

Or start a named browser login directly:

usage connect openai personal
usage connect openai work
usage connect claude personal
usage connect manage
usage connect --status

Every profile is isolated with its own CODEX_HOME or CLAUDE_CONFIG_DIR, so personal and work accounts can stay connected at the same time. NovaNode only tracks the accounts you register through usage connect; ambient shell logins to codex or claude outside those profiles are ignored so they never leak into the dashboard. NovaNode stores only profile metadata in ~/.config/novanode/usage-accounts.json. Passwords and OAuth credentials stay inside the provider-owned credential stores.

Connections persist across CLI restarts. The usage dashboard includes only profiles that the official provider CLI currently reports as authenticated; disconnected profiles and expired sessions are excluded from percentages. If a plan does not provide one of the standard windows, the dashboard labels that window not included in this plan instead of treating the account as broken. A temporary fetch failure is also shown separately and never affects the other connected profiles. Open usage connect and choose Sessions to review the login-time CLI version and last-seen time. Removing a profile deletes only that isolated NovaNode-managed provider directory and its cached usage snapshot. Short-lived usage snapshots are discarded after two minutes, so old sessions cannot keep contributing stale percentages.

nn-op — 1Password wrapper (nnop for short)

nn-op (or the shorter nnop) is a project-aware wrapper around the official 1Password CLI (op). It never stores tokens or values itself — every secret operation is delegated to op, which handles authentication, encryption, and the Keychain / 1Password app integration.

cd my-app
nnop                    # arrow-key dashboard

The first-run dashboard starts with Sign in to 1Password. If the account has not been configured on this machine, choose Add a 1Password account; the official op account add wizard securely asks for the sign-in address, email, Secret Key, and account password. NovaNode does not read or persist those credentials. The authenticated session is held only while the dashboard is open.

After authentication, the dashboard offers workspace initialization or shows the current project/app/env and its vault fields. Secrets are hidden by default; press Enter on a row to reveal, C to copy it to the clipboard. The same account setup is also available directly:

nn-op account add
nn-op accounts

Hotkeys from the authenticated project dashboard:

• A — Add a secret (KEY + hidden VALUE, saved straight to the vault)
• I — Import an existing .env file into the vault
• P — Pull the current env to a real .env file (marked as plaintext)
• T — Write a .env.template full of op:// references (safe to commit)
• U — Switch which app/env is current
• R — Refresh
• Q / Esc — Quit

If the directory doesn't have a .novanode.yml yet, the dashboard opens a guide that offers G to run nn-op project init in place.

Security model. Nothing in the vault ever touches disk unless you explicitly run env pull --materialize. The Add / Import flows stream values into op on stdin — they aren't written to a temp file. Clipboard copy uses pbcopy / xclip / wl-copy directly.

Team sync. See WORKFLOWS.md for the full two-sided walkthrough (owner sets up a client vault, teammate clones and gets a working .env in seconds).

Requirements

• Python 3.9+
• OpenSSH client and key-based access to the lab hosts
• A terminal with curses support
• baresip with loopback-only ctrl_tcp for real phone controls
• 1Password CLI (op) for nn-op / nnop (installed via brew install --cask 1password-cli)

Install

npm install -g @nakdev-npm/novanode

The npm installer sets up the Textual UI in a package-local Python environment. If you install from source or use a custom NOVANODE_PYTHON, install textual==8.2.8 in that interpreter to use the interactive dashboard. usage --classic opens the plain-text dashboard without Textual.

Homebrew releases also install nn, nn-pbx, nn-usage, usage, and the novanode compatibility alias.

License

MIT. See LICENSE.