sonar

Homebrew 6 refuses formulae from third-party taps until you trust the tap once (Error: Refusing to load formula raskrebs/sonar/sonar from untrusted tap):

Install script

Downloads the latest binary to ~/.local/bin and adds it to your PATH if needed. Restart your terminal or source ~/.zshrc.

On Windows (PowerShell):

Custom install location:

Install a specific version:

Using Go

Shell completions (tab-complete port numbers):

Sixty seconds

Prefix the commands in your dev.sh with sonar start:

The group name comes from the repository, so nothing else needs configuring. In another terminal:

And when you are done, stop the whole project — servers, watchers and workers:

Examples below marked # check are executed against a fresh build by scripts/readme-check.sh on every CI run.

Commands

sonar list

Default columns are port, process, group, container, image, containerport, url, where process shows the name you gave the port (sonar rename), then the service name, then what was detected.

Available columns: port, process, pid, type, url, group, cpu, mem, threads, uptime, state, connections, health, latency, container, image, containerport, compose, project, user, bind, ip.

Desktop apps and system services that happen to listen — Figma, Discord, Spotify, ControlCenter, macOS .app bundles, /System/Library/ daemons — are hidden unless you pass -a.

sonar start

Run a command as a named service in a group:

Nothing has to be passed:

• Group — --group, else the name in the nearest .sonar.yaml, else the git root's directory name (a worktree becomes repo@worktree), else the name of the current directory.
• Name — --name, else the .sonar.yaml service whose cmd matches, else inferred from the command (npm run dev → dev, uv run api → api, python -m uvicorn → uvicorn, ./dev.sh → dev.sh).
• Port — --port is a hint, not a binding: the run shows as starting until the port is actually listening, and the daemon uses it to match the process to the port.

The child inherits stdin, stdout, stderr, cwd and environment, plus SONAR_GROUP, SONAR_NAME and SONAR_RUN_ID. It gets its own process group, so sonar kill takes down the whole tree — a dev server with its watchers and workers. Ctrl+C is forwarded, and sonar exits with the child's exit code.

--detach returns immediately and writes the output to ~/.config/sonar/logs/<group>/<name>.log. --list shows what sonar started (--json for the machine-readable form):

.sonar.yaml

A project names itself and its services in a .sonar.yaml at the repository root. It is optional — sonar groups by git root without it — and it is meant to be committed:

• name — the group name. No slashes, no whitespace.
• cmd, cwd, port — how sonar up starts the service. cwd is relative to the file and may not escape its directory.
• health — an HTTP path the daemon polls while the service is up, so a service can be running but not yet healthy. It reports ok, fail or unknown, with the reason for a failure.
• description, icon, color — free-form metadata for the desktop app; sonar never infers them.
• depends_on — start order. Naming a service that is not in the file, or a cycle, is an error; an invalid file is reported once and never stops a scan.

.sonar.yml is read if that is how you spell it; sonar init always writes .sonar.yaml. The daemon watches the projects it knows about and picks up edits to the file without a restart. Every edit sonar makes — from the desktop app, from sonar groups add, rename and remove, from an agent — goes through the daemon, which re-renders the file from its own syntax tree, so comments, key order and layout survive an edit that adds, renames or removes a service just as they survive a metadata change. The one exception: extra spaces lining a trailing comment up (cmd: x # note) collapse to one, because the YAML library keeps the comment but not its column.

sonar up

Starts every service the group's .sonar.yaml declares, in depends_on order: a service waits for the ports its dependencies declare before it is started, and one that is already listening is skipped. Each runs detached in its own process group, with its output in ~/.config/sonar/logs/<group>/<service>.log.

A service that fails to start is reported on its own line and makes the command exit non-zero, whatever else came up. Stop them all again with sonar kill -g my-app. sonar up needs the daemon and starts it if it is not already running.

sonar groups and sonar init

sonar groups lists every group sonar can see and where each name came from: manual (you pinned it with sonar assign), start (a sonar start run), file (a .sonar.yaml) or auto (the git root or the Compose project). sonar groups <name> shows one group's ports and services, and the services that are declared but not running.

sonar init writes a .sonar.yaml at the git root from what is listening right now — desktop apps and ports below 1024 left out. It refuses to overwrite without --force, and --dry-run prints the file instead of writing it. --merge appends to a file that is already there instead of refusing, and --service name:port[:health] — repeatable — writes the services you name instead of the ones it found, keeping the command it guessed for a port you kept. --force and --merge are mutually exclusive.

sonar groups add <group> <name> --port N appends a service to that group's .sonar.yaml, with --cmd, --cwd, --health, --description, --icon, --color and a repeatable --depends-on for the rest of it. sonar groups rename <group> <old> <new> renames one everywhere in the file, depends_on references included, and sonar groups remove <group> <name> deletes one and drops it from every depends_on that named it. All three refuse an edit that would leave the file invalid — a duplicate name, a port another service already claims, a service that is not there — and none of them writes a byte until the whole edit is known to be good.

The daemon does the writing, which is why the file comes back with its comments and key order intact whether the edit came from the CLI, the desktop app or an agent. sonar groups add, rename and remove need the daemon and start it if it is not already running; the three names are subcommands, so a group actually called add is read with sonar groups --json.

sonar kill

--dry-run takes any selector and changes nothing: it prints the actions the kill would take, children first, and leaves everything running. End to end, against a listener of your own:

A positional argument is read as a port, and as a pid only when nothing is listening on that number. -g matches the resolved group, a legacy run tag or id, and the Compose project, case-insensitively.

A process that ignores SIGTERM is sent SIGKILL once the port is still listening after --grace (5s); --no-escalate turns that off. Children are signalled before parents, so a tree comes down in order. Docker containers are stopped with docker stop and never signalled. A listener started by sonar start is always stopped together with its process group.

--json prints one row per process: {port, bind_address, pid, name, method, ok, error}, where method is sigterm, sigkill, docker_stop, map_stop or none. An empty sweep exits 0; an unknown group exits 1.

sonar map

Runs a TCP proxy in the foreground until you stop it. sonar kill reports a mapping it stopped as map_stop.

sonar rename, sonar assign, sonar history

Names and pins are stored in sonar's database, keyed by the most specific thing known about the port: the run (run:<group>/<name>), the container (docker:<project>/<service>), the working directory, and the port number last. A renamed dev server keeps its name across restarts; a name pinned to port 3000 alone applies to whatever answers there. These three commands need the daemon and start it if it is not running.

Reading a port

sonar wait exits 0 (ready), 1 (timeout) or 2 (interrupted), which makes it the thing to put between starting something and testing it:

Daemon or direct scan. Every read command asks the daemon if one is running, because it already has the answer and does not have to fork lsof. If none is running they scan directly and print one note on stderr saying so. sonar kill follows the same rule: a reachable daemon does the killing, so it rescans immediately and its next answer — and the port history — already knows the port is gone. Neither reads nor kills start a daemon behind your back. --no-daemon forces the direct scan silently and works on any command:

sonar host

The daemon measures its own machine on the scan cadence and publishes it as the localhost row of the snapshot's hosts collection: os and kernel, uptime, cpu percent, load average, memory and the disk holding /. CPU percent is the work done between two scans, so it is null until the daemon has scanned twice; a figure a platform cannot produce — the load average on Windows, which has none — is null rather than zero. Every host registered with sonar remote add joins the same table with its own load. The command needs a running daemon: it is the daemon that holds the previous sample a percentage is measured against.

sonar remote install

Puts sonar on a host you can already ssh to and starts its daemon there. The release archive is downloaded and checksummed on the remote host — nothing is copied from this machine — and the binary lands in ~/.local/bin/sonar, so none of it needs root. The daemon runs as a systemd user unit where the host has one (~/.config/systemd/user/sonar.service), and detached where it does not; loginctl enable-linger is printed as advice when the user session would end at logout and take the daemon with it.

The version installed is the version of the sonar you ran it from, so the two ends speak the same protocol. Running it again upgrades in place and restarts the daemon, which is what makes an install and an update the same command.

The target goes to ssh untouched: a Host alias from ~/.ssh/config works, and so do the ProxyJump, IdentityFile and Port it sets. --identity and --ssh-arg are there for the flags a config does not cover.

sonar remote

A registered host runs the same daemon, and the daemon on this machine keeps one SSH connection to it — ssh <target> sonar daemon stdio — and multiplexes what it reports into the state every client already reads. Nothing new listens anywhere: the remote daemon's socket stays private to the SSH user, and clients never speak SSH themselves.

Every row now carries the host it came from. Local rows say localhost and keep the keys they always had, so nothing that reads sonar today changes; remote rows say the registered name and are keyed <host>/<port>:<bind>, which is what lets port 3000 on two machines be two rows. A subscriber sees only localhost unless it asks for more (state.subscribe {"hosts": ["*"]}).

The target goes to ssh untouched, so ~/.ssh/config aliases, ProxyJump and identities all apply; --ssh-arg, --identity and --port cover what a config does not. sonar stores no password and no key. A host that goes away keeps its row and its status while the daemon retries, backing off from one second to thirty for as long as it stays registered.

--host also still takes a bare user@host that sonar knows nothing about: it falls back to the agentless ssh + ss/lsof scan and prints a hint to sonar remote install.

Acting on another machine

Every write takes --host too, and does there exactly what it does here:

The local daemon forwards the call over that host's bridge and hands back what the remote daemon answered, in the same envelope a local call returns — every result row says which host it happened on, and a kill's affected carries the <host>/<port>:<bind> keys the stream uses for those rows. A streaming command streams: sonar up --host prints each service as the far side starts it, and Ctrl-C stops the remote work rather than just this terminal.

Because a row's key already names its host, a client can hand one straight back as a selector — {"key": "hetzner/3000:127.0.0.1"} is the whole of a selector, host included. One call acts on one machine; naming two is an error rather than half a kill on each.

Two things stay local. sonar attach puts this terminal in front of a process, so it refuses --host and says to ssh over and attach there. And an agent session is state this daemon holds, so sonar kill --session has no remote form. Everything else needs the daemon running here — it is where the connection to the other machine lives — and says so instead of quietly scanning this machine instead.

sonar up --host needs the group named: the .sonar.yaml at your working directory is a path on this machine, and it is the remote daemon that reads the file and starts the services.

The daemon

One background process scans ports, resolves groups, polls health, keeps the database and streams changes to whoever is subscribed — the CLI, the desktop app, and editors.

SONAR_SOCKET overrides the socket path everywhere, for both the daemon and its clients — useful for a second isolated instance. The socket is created 0600 in a 0700 directory, so only you can talk to it. Only one daemon runs at a time; a socket left behind by a crash is cleaned up on the next start.

The daemon stops on its own after 30 minutes with no clients and no subscribers. Set daemon.idle_timeout in the config file to change that, or 0 to keep it running.

Ports are scanned every 2 seconds while something is changing; when nothing is, the scanner slows itself down to 5 seconds with a subscriber connected and 10 seconds without one. daemon.scan_interval moves that base — minimum 1s — and both ceilings scale with it, so raising it to 5s backs off to 12.5s and 25s rather than pinning the curve at the old caps. daemon.stats_interval is the separate cadence at which cpu, memory and the host load strip refresh while something is subscribed. Both are read when the daemon starts: edit the file, then sonar daemon restart. sonar daemon status prints the values in effect (scan base, stats tick) next to the adaptive interval the scanner is on right now.

A subscriber that asks for include: ["health"] makes the daemon probe every listening port on a slower cadence, not only the services that declare a health: path — those are polled on every tick and reach every subscriber whether or not health was asked for.

Configuration

~/.config/sonar/config.yaml is optional; flags always win.

Invalid values are ignored with a warning and sonar carries on with defaults. Environment overrides that have no config key: SONAR_DB, SONAR_SOCKET, SONAR_NO_HINTS=1 to silence the migration notices below, and SONAR_NO_AUTOSTART=1 to stop any sonar client from starting a daemon it did not find — useful in CI, where a build should never leave a process behind.

sonar's own test suite sets SONAR_NO_AUTOSTART=1 for every test binary and, after the run, looks for a daemon that outlived it. That gate only claims a serve started from the run's private temp root, so two suites running side by side on one machine leave each other's daemons alone; SONAR_TESTENV_GATE_ALL=1 widens it back to every sonar serve anywhere under the temp directory, which is what a CI runner that owns the whole machine wants.

Agents: MCP, skills and hooks

install mcp registers {"command": "sonar", "args": ["mcp"]} and leaves every other server and key in the file alone; running it twice changes nothing, and --uninstall removes exactly what sonar wrote.

sonar mcp is that server: a stdio MCP server built into the binary that gives an agent the daemon's view of the machine. It reads with list_ports and inspect_port, waits with wait_for_port, picks and reserves ports with next_free_port and claim_port, and answers the rest of an agent's questions with tail_logs, health_check, dependency_graph, port_history and list_sessions; actions and resources come next. It starts a daemon if none is running and reconnects on its own if one goes away; its logs go to stderr, because stdout carries the protocol.

install skills writes the bundled skill, which teaches an agent to start servers with sonar start --, to sonar wait instead of sleeping, and to clean up what it started. install hooks adds two Claude Code hooks: one exports SONAR_SESSION so everything a session starts is attributed to it, the other suggests sonar start -- when a bare dev server is about to run (it advises, it never blocks). Both take --scope project|user, --print and --uninstall.

sonar doctor

One command that checks everything sonar depends on and says what to do about whatever is wrong. It is what the desktop app runs during onboarding, and what to run yourself when something is off.

Every check reports ok, warn, fail or skip. skip means there was nothing to look at — Cursor is not installed, the machine has no docker, the socket is a named pipe on Windows — and never counts against you. The exit code is 0 unless something failed, so sonar doctor belongs in a setup script.

--fix applies only the repairs that are safe to make unattended, and asks first unless you pass --yes: it moves an unparseable config.yaml to config.yaml.broken-<timestamp> and writes a fresh template (nothing is ever deleted), restarts a daemon that is not running, and runs the sonar install mcp|skills|hooks command the check names — from the working directory, the way you would type it, so run --fix inside the project you are repairing rather than pointing --project at it. Then it checks again. Anything it will not touch — a shadowing binary on PATH, a skill sonar did not write — is left to you with the exact command in the fix column.

The desktop app calls the same checks over the daemon's daemon.doctor method instead of shelling out. The daemon runs everything it can from its own process; the three checks that are about the CLI binary you invoked (cli_on_path, cli_version_current, daemon_version_matches) come back as skip with a detail saying so.

The desktop app

The Sonar app is the same picture in a window and in the menu bar or system tray: groups down the side, ports in a grid with live stats and health, logs, and the buttons for everything above. It talks to the same daemon, so the CLI and the app never disagree. sonar install desktop installs it and sonar tray launches it.

Until the app ships, macOS release tarballs still carry the old sonar-tray menu bar binary, and sonar tray falls back to it when the app is not installed.

sonar install desktop

The app is in beta and is not signed by Apple yet, so the CLI installs it:

That is the whole tester setup. Sonar fetches a manifest of published builds, picks the one for your machine, checks its sha256 and its size, installs it, and opens it.

This is why the CLI does the download. macOS attaches a quarantine attribute to anything a browser saves, and Gatekeeper refuses to open a quarantined app that Apple has not notarised. A file this CLI downloads never gets the attribute in the first place, so the beta opens with no prompt and no right-click-Open dance. Sonar neither sets nor strips quarantine attributes — there is nothing to strip.

The command needs no network to tell you what it does:

Where it goes:

--dir overrides the directory on both. On Linux, --deb installs the .deb through apt/dpkg instead of the AppImage, where the release publishes one.

The install is atomic: the new app is unpacked beside the old one and swapped in with a rename, so a failed download never leaves you without a working app. If the app is open, sonar refuses rather than replacing a bundle underneath it; --force asks it to quit and waits up to ten seconds.

sonar install desktop records desktop.installed_version and desktop.installed_path in ~/.config/sonar/config.yaml, which is how sonar tray finds an app installed with --dir and how sonar doctor's desktop_installed check knows the version. Where the builds come from is desktop.download_base, overridden by SONAR_DESKTOP_BASE and then by --base — point them at your own build to test one.

sonar relay

The relay is the server side of sonar: one small HTTP service, run by us for the hosted app and published as ghcr.io/raskrebs/sonar-relay so you can run your own. It has nothing to do with the local daemon — sonar serve watches your ports, sonar relay serve answers HTTP for a fleet — and it ships in the same binary only so there is one artefact to deploy.

Today it collects anonymous product telemetry: a batch of named events per install, no paths, no hostnames, no URLs, refused at the door if a value even looks like one. It is the same service that will later terminate exposed tunnels and hold sign-in.

docs/RELAY.md has the routes, the exact validation rules, the storage schema and a one-command deploy behind Caddy on any box with Docker.

Moving from the old commands

The pre-group commands still work and print a single line on stderr saying what replaced them. They go away one minor release from now. SONAR_NO_HINTS=1 silences the notices, and --json output never carries them.

Profiles were a per-machine snapshot of ports; .sonar.yaml is committed with the project. Convert one and read it before you keep it — nothing is written for you:

A profile never recorded how a service starts, so the proposal has ports, names and health paths, and you fill in cmd.

Troubleshooting

Something is wrong with the daemon. sonar daemon log -f while you reproduce it, and sonar daemon status for pid, uptime and scan count. Stop it with sonar daemon stop; every read command keeps working without it.

"daemon unavailable, using direct scan". Nothing is listening on the socket. That is normal — reads do not start a daemon. Run sonar serve -d if you want one.

A socket left over from a crash. sonar daemon path shows it; starting a daemon removes a stale one by itself. If a second daemon refuses to start while the first is gone, sonar daemon restart clears the lock.

Ports are missing from the list. Processes owned by another user are invisible without privileges; sonar says so under the table. Re-run with sudo sonar list to see them. On Linux, ss must be installed (iproute2); on Windows, netstat is used.

A kill did nothing. Docker containers are stopped through the Docker daemon: check docker ps. A process that ignores SIGTERM needs -f, and one supervised by something else (systemd, Compose restart: always) comes back by design — stop the supervisor.

Nothing works and you are not sure why. sonar doctor checks the binary, the config, the daemon, the database and every integration in one go, and prints the command that fixes each thing it finds.

Reporting a bug. Include these, plus the last lines of sonar daemon log:

Supported platforms

• macOS (uses lsof)
• Linux (uses ss)
• Windows (uses netstat)

Grouping needs each process's working directory, and every platform now has one: /proc on Linux, lsof on macOS, and on Windows a read of the process's own PEB. So git-root groups, project_root and cwd-based names work the same everywhere, and sonar init can propose a .sonar.yaml from what is listening on any of the three.

The desktop app is narrower for now: sonar install desktop installs it on macOS (Apple Silicon and Intel) and Linux (x86_64 and aarch64). On Windows the command says the app is not available yet and exits 1.

The one gap is a 32-bit sonar.exe on 64-bit Windows: it cannot read a 64-bit process's memory, so those ports come back without a working directory and fall out of their git-root group. Use the 64-bit build — it reads 64-bit and 32-bit processes alike. Elsewhere, a port whose process denies access (a service running as another user, a protected system process) is simply left without a working directory; the rest of the scan is unaffected.

Contributors

Thanks to everyone who has contributed to sonar!