
CLI-Tool zum Inspizieren und Verwalten von Diensten, die auf Localhost-Ports lauschen.
Entdecken Sie die meistgenutzten Tools unserer Community.
Noch keine Beliebtheitsdaten.
<div align="center">
```
██████ ███ ██████ ██ ██████
██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ████
██ ██ ██ ██ ██ ██ ██ ██
██████ ███ ██ ██ ██ ██ ██ ██
```
Erfahre, was auf deiner Maschine läuft.
</div>
Sonar zeigt alles an, was auf localhost lauscht, und bringt es in Ordnung: Jeder Port
gehört zu einer **Gruppe** – normalerweise das Repository, aus dem er gestartet wurde – und
innerhalb dieser Gruppe zu einem benannten **Dienst**. Starte deine Dev-Server mit
`sonar start`, und das gesamte Projekt wird zu einer einzigen Sache, die du als Baum auflisten,
auf die du warten, die du verfolgen und mit einem einzigen Befehl stoppen kannst. Docker-Container, Compose-
Projekte und Prozesse, die du von Hand gestartet hast, werden ebenfalls erfasst, ohne jegliche
Konfiguration.
```
$ sonar list --tree
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 5173 frontend vite (v5.4) http://localhost:5173
└─ 8000 api uvicorn app:app http://localhost:8000
ungrouped (1 port)
└─ 3000 next-server (v16.1.6) http://localhost:3000
```
## Installation
### Homebrew (macOS / Linux)
```sh
brew install raskrebs/sonar/sonar
```
Homebrew 6 verweigert Formeln aus Drittanbieter-Taps, bis du den Tap einmal vertraust
(`Error: Refusing to load formula raskrebs/sonar/sonar from untrusted tap`):
```sh
brew trust raskrebs/sonar
```
### Installationsskript
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash
```
Lädt die neueste Binärdatei nach `~/.local/bin` herunter und fügt sie bei Bedarf zu deinem PATH hinzu. Starte dein Terminal neu oder führe `source ~/.zshrc` aus.
Unter Windows (PowerShell):
```powershell
irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
Benutzerdefinierter Installationspfad:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_INSTALL_DIR=/usr/local/bin bash
```
Installiere eine bestimmte Version:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_VERSION=vX.Y.Z bash
```
```powershell
$env:SONAR_VERSION="vX.Y.Z"; irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
### Verwendung von Go
```sh
go install github.com/raskrebs/sonar@latest
```
Shell-Vervollständigungen (Tab-Vervollständigung für Portnummern):
```sh
sonar completion zsh > "${fpath[1]}/_sonar" # zsh
sonar completion bash > /etc/bash_completion.d/sonar # bash
sonar completion fish | source # fish
```
## Sechzig Sekunden
Beschreibe, wie dein Projekt läuft, in einer `sonar.yaml` im Repository-Stammverzeichnis,
anstelle einer `dev.sh`:
```yaml
name: my-app
services:
- name: db
cmd: docker compose up db
port: 5432
- name: api
cmd: uv run uvicorn app:app --port ${port}
port: auto
depends_on: [db]
- name: frontend
cmd: npm run dev -- --port ${port} --strictPort
port: auto
depends_on: [api]
env:
VITE_API_URL: ${api.url}
```
Dann starte es:
```sh
sonar start
```
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
✓ api http://localhost:21408 pid 41040 ~/.config/sonar/logs/my-app/api.log
✓ frontend http://localhost:21409 pid 41077 ~/.config/sonar/logs/my-app/frontend.log
3 started
following the logs; Ctrl+C stops the 3 services started here
api | INFO: Uvicorn running on http://127.0.0.1:21408
frontend | VITE v5.4 ready in 312 ms
```
Sonar wählt einen freien Port für jeden `port: auto`-Dienst und teilt jedem Dienst mit,
wo sich die anderen befinden, sodass ein zweiter Worktree neben dem ersten läuft, ohne
dass ein einziger Port kollidiert. `sonar start -d` macht dasselbe im Hintergrund, und
`sonar down` stoppt ihn und gibt die Ports zurück. In einem anderen Terminal:
```sh
sonar list --tree
```
```
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 21408 api uvicorn app:app http://localhost:21408
└─ 21409 frontend vite (v5.4) http://localhost:21409
```
Keine `sonar.yaml`? `sonar start -- npm run dev` führt einen Befehl als benannten
Dienst aus, und `sonar list` und `sonar kill` funktionieren mit allem, was lauscht.
Die unten mit `# check` markierten Beispiele werden bei jedem CI-Lauf gegen einen frischen Build
durch `scripts/readme-check.sh` ausgeführt.
## Befehle
### `sonar list`
```sh
sonar list
sonar list --tree
sonar list --group my-app
sonar list --json
# check
```
```sh
sonar list --stats # CPU, memory, threads, uptime, state
sonar list --health # HTTP health checks
sonar list --filter docker # only Docker ports
sonar list --sort name # port | pid | name | type
sonar list -a # include desktop apps
sonar list -c port,process,group,cpu,mem
sonar list --host user@server # scan a remote machine over SSH
```
Standardspalten sind `port`, `process`, `group`, `container`, `image`,
`containerport`, `url`, wobei `process` den Namen anzeigt, den du dem Port gegeben hast
(`sonar rename`), dann den Dienstnamen, dann das, was erkannt wurde.
Verfügbare Spalten: `port`, `process`, `pid`, `type`, `url`, `group`, `cpu`,
`mem`, `threads`, `uptime`, `state`, `connections`, `health`, `latency`,
`container`, `image`, `containerport`, `compose`, `project`, `user`, `bind`,
`ip`.
Desktop-Apps und Systemdienste, die zufällig lauschen — Figma, Discord,
Spotify, ControlCenter, macOS `.app`-Bundles, `/System/Library/`-Daemons — werden
ausgeblendet, es sei denn, du übergibst `-a`.
### `sonar start`
Starte ein Projekt aus seiner `sonar.yaml`:
```sh
sonar start # every service in the nearest sonar.yaml
sonar start api frontend # only these (they still wait for their dependencies)
sonar start ../other-project # the sonar.yaml in or above another directory
sonar start -d # in the background, like `sonar up`
```
Im Vordergrund startet sonar die Dienste über den Daemon, verfolgt deren
Logs mit dem Dienstnamen vor jeder Zeile und stoppt bei Drücken von Ctrl+C
die Dienste, die es gestartet hat. Ein Dienst, der bereits lief, wird in Ruhe
gelassen, und sonar kehrt von selbst zurück, sobald jeder von ihm gestartete Dienst beendet wurde.
Argumente vor `--` benennen ein Verzeichnis oder Dienste; alles nach `--` ist ein
Befehl. Oder führe einen Befehl als benannten Dienst in einer Gruppe aus:
```sh
sonar start -- npm run dev
sonar start --group my-app --name frontend -- npm run dev
sonar start --port 5173 -- npm run dev # expected port, before it binds
sonar start --detach --name api -- uv run uvicorn app:app
sonar start --list
```
Nichts muss übergeben werden:
- **Group** — `--group`, sonst der `name` in der nächstgelegenen `sonar.yaml`, sonst der Verzeichnisname des Git-Roots (ein Worktree wird zu `repo@worktree`), sonst der Name des aktuellen Verzeichnisses.
- **Name** — `--name`, sonst der `sonar.yaml`-Service, dessen `cmd` übereinstimmt, sonst abgeleitet aus dem Befehl (`npm run dev` → `dev`, `uv run api` → `api`, `python -m uvicorn` → `uvicorn`, `./dev.sh` → `dev.sh`).
- **Port** — `--port` ist ein Hinweis, keine Bindung: Der Lauf wird als `starting` angezeigt, bis der Port tatsächlich lauscht, und der Daemon verwendet ihn, um den Prozess dem Port zuzuordnen.
Das Kind erbt stdin, stdout, stderr, cwd und die Umgebung sowie `SONAR_GROUP`, `SONAR_NAME` und `SONAR_RUN_ID`. Es erhält eine eigene Prozessgruppe, sodass `sonar kill` den gesamten Baum beendet — einen Dev-Server mit seinen Watchern und Workern. Ctrl+C wird weitergeleitet, und sonar beendet sich mit dem Exit-Code des Kindes.
`--detach` kehrt sofort zurück und schreibt die Ausgabe nach `~/.config/sonar/logs/<group>/<name>.log`. `--list` zeigt an, was sonar gestartet hat, und darunter, was seitdem beendet wurde — mit dem Exit-Code und ob es abgestürzt oder gestoppt wurde (`--json` für die maschinenlesbare Form):
```sh
sonar start --list
sonar start --detach --name demo --port 8123 -- sleep 5
sonar start --list --json
# check
```
### `sonar.yaml`
Ein Projekt benennt sich selbst und seine Dienste in einer `sonar.yaml` im
Repository-Stammverzeichnis. Sie ist optional — sonar gruppiert auch ohne sie
nach Git-Stammverzeichnis — und ist dafür gedacht, committet zu werden:
```yaml
name: my-app
services:
- name: db
cmd: docker compose up db
port: 5432
health: /
description: Postgres 17
icon: database
color: "#4f8cc9"
- name: api
cmd: uv run uvicorn app:app --port 8000
cwd: backend
port: 8000
health: /healthz
depends_on: [db]
- name: frontend
cmd: npm run dev
port: 5173
depends_on: [api]
ports: [9229] # ports that belong to this project without a service
```
- `name` — der Gruppenname. Keine Schrägstriche, keine Leerzeichen.
- `cmd`, `cwd`, `port` — wie `sonar start` den Dienst startet. `cwd` ist relativ
zur Datei und darf deren Verzeichnis nicht verlassen.
- `health` — ein HTTP-Pfad, den der Daemon abfragt, während der Dienst läuft, sodass ein
Dienst *läuft*, aber noch nicht *healthy* sein kann. Er meldet `ok`, `fail` oder
`unknown`, mit dem Grund für einen Fehler.
- `description`, `icon`, `color` — freie Metadaten für die Desktop-App; sonar
leitet sie niemals ab.
- `depends_on` — Startreihenfolge. Einen Dienst zu benennen, der nicht in der Datei ist, oder einen
Zyklus, ist ein Fehler; eine ungültige Datei wird einmal gemeldet und stoppt niemals einen Scan.
- `env` — Variablen, die für den Dienst gesetzt werden, wenn sonar ihn startet.
#### `port: auto` und Referenzen
Ein Dienst kann seinen Port sonar überlassen und die anderen durch seine
Umgebung finden, statt ein fest codiertes `localhost:8080` zu verwenden:
```yaml
services:
- name: api
cmd: uv run uvicorn app:app --port ${port}
port: auto
- name: frontend
cmd: npm run dev -- --port ${port} --strictPort
port: auto
depends_on: [api]
env:
VITE_API_URL: ${api.url}
```
`sonar start` beansprucht einen freien Port für jeden `port: auto`-Dienst, den es startet: denselben bei jedem Mal im selben Checkout und einen anderen in jedem anderen Checkout, sodass ein Worktree nie mit dem Haupt-Worktree kollidiert. Der Dienst erhält ihn als `PORT`, `SONAR_PORT` und `${port}`, und er muss ihn verwenden — `PORT` lesen oder `${port}` in seiner Kommandozeile übergeben. Ein Dienst, der bereits läuft, behält seinen Port, sodass ein später gestarteter ihn weiterhin findet. Der Anspruch hinter einem zugewiesenen Port gilt einen Tag ab dem letzten Start; `claims.ttl` ändert das (siehe The daemon).
`${port}` und `${url}` (`http://localhost:<port>`) gehören dem Dienst selbst; `${<service>.port}` und `${<service>.url}` gehören einem anderen. Sie funktionieren in `cmd` und in `env`. Eine Referenz auf einen Dienst, der nicht in der Datei ist, oder auf einen ohne Port, ist ein Fehler beim Laden der Datei. Alles andere zwischen `${` und `}`, wie `${HOME}`, bleibt genau so stehen, wie es geschrieben wurde.
`sonar.yml` wird gelesen, wenn du es so schreibst; `sonar init` schreibt immer `sonar.yaml`. Die Datei war früher die Dotfile `.sonar.yaml`, und dieser Name funktioniert noch: sonar sucht nach `sonar.yaml`, `sonar.yml`, `.sonar.yaml` und `.sonar.yml`, in dieser Reihenfolge, und liest die erste, die es findet. Änderungen gehen zurück in die Datei, die sonar gelesen hat, sodass nichts hinter deinem Rücken umbenannt wird. `sonar doctor` weist auf eine Datei unter dem alten Namen hin, und `sonar doctor --fix` benennt sie um (mit `git mv`, wenn die Datei getrackt wird). Der Daemon überwacht die Projekte, die er kennt, und übernimmt Änderungen an der Datei ohne Neustart. Jede Änderung, die sonar vornimmt — von der Desktop-App, von `sonar groups add`, `rename` und `remove`, von einem Agenten — geht durch den Daemon, der die Datei aus seinem eigenen Syntaxbaum neu rendert, sodass Kommentare, Schlüsselreihenfolge und Layout eine Änderung überleben, die einen Dienst hinzufügt, umbenennt oder entfernt, genauso wie sie eine Metadatenänderung überleben. Die einzige Ausnahme: zusätzliche Leerzeichen, die einen nachgestellten Kommentar ausrichten (`cmd: x # note`), fallen auf eines zusammen, weil die YAML-Bibliothek den Kommentar behält, aber nicht seine Spalte.
#### `sonar env`
Was die Datei auflöst, ist lesbar, ohne etwas zu starten:
```sh
sonar env # every service: port, url and its expanded env
sonar env frontend # one service, as export lines
sonar env --json # for tools
```
```
SERVICE PORT URL ENV
db 5432 http://localhost:5432
api 21408 http://localhost:21408 DB_URL=postgres://localhost:5432/app
frontend 21409 http://localhost:21409 VITE_API_URL=http://localhost:21408
```
Ein `port: auto`-Dienst, der nicht läuft, erhält hier seinen Anspruch, denselben Anspruch, den `sonar start` erhebt, sodass das, was `sonar env` ausgibt, dem entspricht, was ein späterer Start bindet; ein Dienst, der bereits läuft, behält den Port, auf dem er läuft. Benannt, wird ein Dienst als `export`-Zeilen ausgegeben, sodass eine Shell sehen kann, was der Dienst würde:
```sh
eval "$(sonar env frontend)" && npm test
```
Dahinter steht `groups.env` auf dem Daemon, für einen Editor oder einen Agenten, der einen Worktree einrichtet, bevor dessen Dienste existieren.
### `sonar up`
```sh
sonar up # the sonar.yaml at or above this directory
sonar up my-app # a group by name
sonar up --only api,frontend
sonar up --json
```
`sonar up` ist `sonar start -d`, was auch eine Gruppe von überall benennen und
sie auf einem anderen Host starten kann. Es startet jeden Dienst, den die `sonar.yaml`
der Gruppe deklariert, in `depends_on`-Reihenfolge:
ein Dienst wartet auf die Ports, die seine Abhängigkeiten deklarieren, bevor er gestartet wird, und
einer, der bereits lauscht, wird übersprungen. Jeder läuft abgetrennt in seiner eigenen Prozessgruppe,
mit seiner Ausgabe in `~/.config/sonar/logs/<group>/<service>.log`, und mit
der Umgebung der Shell, in der Sie `sonar up` ausgeführt haben, plus `PORT` für einen Dienst
mit einem Port.
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
- api already running
✓ frontend http://localhost:5173 pid 41108 ~/.config/sonar/logs/my-app/frontend.log
2 started, 1 already running
```
Ein Dienst, der nicht startet, wird in einer eigenen Zeile gemeldet und führt dazu, dass der Befehl mit einem von Null verschiedenen Wert beendet wird, unabhängig davon, was sonst noch aufgetreten ist. Beende sie alle wieder mit `sonar down`.
`sonar up` benötigt den Daemon und startet ihn, falls er nicht bereits läuft.
### `sonar down`
```sh
sonar down # the project in the nearest sonar.yaml
sonar down my-app # a group by name
sonar down --only api,worker # only these services
```
Stoppt jeden Dienst des Projekts — jeden Port, auf dem es lauscht, und jeden
Dienst, den sonar dafür gestartet hat, der keinen Port belegt, wie einen Worker — und gibt
die Ports frei, die sonar für seine `port: auto`-Dienste beansprucht hat. `--only` beschränkt all
das auf die genannten Dienste, so wie `sonar up --only` nur einige startet; ein Name,
den die Datei nicht deklariert, ist ein Fehler. `sonar kill -g my-app` stoppt die Ports
und gibt nichts frei.
### `sonar groups` und `sonar init`
```sh
sonar init --dry-run
sonar init --service api:8000:/healthz --service web:5173
sonar groups
sonar groups --json
group=$(basename "$PWD") # sonar init names the group after the directory
sonar groups add "$group" worker --port 9000 --cmd 'uv run worker' --depends-on api
sonar groups rename "$group" worker jobs
sonar groups remove "$group" jobs
# check
```
`sonar groups` listet jede Gruppe auf, die sonar sehen kann, und woher jeder Name stammt:
`manual` (du hast ihn mit `sonar assign` festgelegt), `start` (ein `sonar start`-Lauf),
`file` (eine `sonar.yaml`) oder `auto` (das Git-Root oder das Compose-Projekt).
`sonar groups <name>` zeigt die Ports und Dienste einer Gruppe sowie die Dienste,
die deklariert, aber nicht laufend sind.
`sonar init` schreibt eine `sonar.yaml` im Git-Root aus dem, was es feststellen kann: die
Ports, die gerade innerhalb des Projekts lauschen (Desktop-Apps und Ports unter 1024
ausgenommen), plus das, was eine Compose-Datei oder eine `package.json` direkt deklariert — ein
Dienst pro Compose-Dienst, mit seinem veröffentlichten Port und seinem `depends_on`, und
das `dev`-Skript, das von dem Paketmanager ausgeführt wird, auf den dich deine Lockfile festlegt.
Wo die beiden nicht übereinstimmen, gewinnt der lauschende Port: Er ist ein Beweis, keine
Aussage. Die Datei, die es schreibt, sagt, was es nicht ermitteln konnte.
Nichts anderes wird erkannt. Ein Makefile-Target, eine Procfile-Zeile, ein Entry Point,
der in einem Framework vergraben ist — das sind Vermutungen über dein Repository, und eine Tabelle
daraus würde nie fertig werden. Dieser Teil geht an einen Agenten:
```sh
sonar init --agent # whichever agent is installed
sonar init --agent codex # name one
sonar init --agent claude -- --allow-dangerously-skip-permissions
```
`--agent` öffnet den Coding-Agenten, den du bereits hast, in diesem Terminal, mit der bereits gesendeten Eingabeaufforderung: was sonar weiß, der Entwurf, den es geschrieben hätte, das Format und die Regel, dass er die Datei schreibt und nichts startet. Du siehst zu, wie er das Repository liest und seine Änderungen genau so genehmigt, wie du es immer tust — es ist dein Agent, unter deinen Berechtigungen — und alles nach `--` wird an ihn weitergegeben. sonar kennt `claude`, `codex`, `cursor-agent` und `opencode`; wenn mehrere installiert sind, benenne einen. Wenn der Agent beendet wird, lädt sonar die Datei und gibt die Dienste aus, die sie deklariert, oder warum sie nicht lädt. Ohne Terminal — eine Pipe, CI — gibt `--agent` die Eingabeaufforderung aus, anstatt etwas zu starten.
Es weigert sich, ohne `--force` zu überschreiben, und `--dry-run` gibt die Datei aus, anstatt sie zu schreiben. `--merge` hängt an eine bereits vorhandene Datei an, anstatt sich zu weigern, und `--service name:port[:health]` — wiederholbar — schreibt die von dir benannten Dienste anstelle der gefundenen und behält den Befehl, den es für einen von dir behaltenen Port erraten hat. `--force` und `--merge` schließen sich gegenseitig aus.
`sonar groups add <group> <name> --port N` hängt einen Dienst an die `sonar.yaml` dieser Gruppe an, mit `--cmd`, `--cwd`, `--health`, `--description`, `--icon`, `--color` und einem wiederholbaren `--depends-on` für den Rest. `sonar groups rename <group> <old> <new>` benennt einen überall in der Datei um, einschließlich `depends_on`-Verweisen, und `sonar groups remove <group> <name>` löscht einen und entfernt ihn aus jedem `depends_on`, das ihn nannte. Alle drei verweigern eine Bearbeitung, die die Datei ungültig machen würde — ein doppelter Name, ein Port, den ein anderer Dienst bereits beansprucht, ein Dienst, der nicht vorhanden ist — und keiner von ihnen schreibt ein Byte, bis die gesamte Bearbeitung als gut bekannt ist.
Der Daemon erledigt das Schreiben, weshalb die Datei mit ihren Kommentaren und der Schlüsselreihenfolge intakt zurückkommt, egal ob die Bearbeitung von der CLI, der Desktop-App oder einem Agenten kam. `sonar groups add`, `rename` und `remove` benötigen den Daemon und starten ihn, wenn er nicht bereits läuft; die drei Namen sind Unterbefehle, sodass eine Gruppe, die tatsächlich `add` heißt, mit `sonar groups --json` gelesen wird.
### `sonar kill`
```sh
sonar kill 3000 # SIGTERM, then SIGKILL after 5s
sonar kill 3000 5432 -f # SIGKILL both straight away
sonar kill 3000 --tree # the listener and everything below it
sonar kill --pid 12345 --tree # by process id
sonar kill -g my-app # a whole group, confirms unless -y
sonar kill --all --filter docker -y # every container publishing a port
sonar kill --all --project my-app # one Compose project
sonar kill 3000 --ip 127.0.0.1 # one bind address of several
sonar kill --all --dry-run --json # the plan for the whole machine
```
`--dry-run` nimmt einen beliebigen Selektor entgegen und ändert nichts: Es gibt die Aktionen aus, die der Kill ausführen würde, zuerst die Kindprozesse, und lässt alles weiterlaufen. Von Anfang bis Ende, gegen einen eigenen Listener:
```sh
sonar start --detach --name plan --port 8231 -- sonar map 3000 8231
sonar wait 8231
sonar kill 8231 --dry-run --json # the plan; the mapping keeps running
sonar kill 8231 -y # and now for real
# check
```
Ein positionales Argument wird als Port gelesen und nur dann als PID, wenn
auf dieser Nummer nichts lauscht. `-g` gleicht die aufgelöste Gruppe, ein
Legacy-Run-Tag oder eine ID sowie das Compose-Projekt ohne
Berücksichtigung der Groß-/Kleinschreibung ab.
Ein Prozess, der SIGTERM ignoriert, erhält SIGKILL, sobald der Port nach
`--grace` (5s) noch lauscht; `--no-escalate` schaltet das ab. Kinder werden
vor Eltern signalisiert, sodass ein Baum der Reihe nach abgebaut wird. Docker-Container werden
mit `docker stop` gestoppt und niemals signalisiert. Ein Listener, der von `sonar start` gestartet wurde, wird
immer zusammen mit seiner Prozessgruppe gestoppt.
`--json` gibt eine Zeile pro Prozess aus:
`{port, bind_address, pid, name, method, ok, error}`, wobei `method`
`sigterm`, `sigkill`, `docker_stop`, `map_stop` oder `none` ist. Ein leerer Sweep beendet sich
mit 0; eine unbekannte Gruppe beendet sich mit 1.
### `sonar map`
```sh
sonar map 6873 3002 # also serve the service on 6873 from port 3002
```
Führt einen TCP-Proxy im Vordergrund aus, bis du ihn stoppst. `sonar kill` meldet eine Zuordnung, die es gestoppt hat, als `map_stop`.
### `sonar rename`, `sonar assign`, `sonar history`
```sh
sonar rename 3000 storefront # a name of your own, survives restarts
sonar rename 3000 --clear
sonar assign 3000 my-app # pin a port to a group by hand
sonar assign 3000 --clear
sonar history # everything that came up, went down, restarted
sonar history 3000 --since 24h --limit 20
```
```sh
sonar history --since 1h
sonar history --json
# check
```
Namen und Pins werden in der Datenbank von sonar gespeichert, verschlüsselt nach dem spezifischsten bekannten Merkmal des Ports: dem Lauf (`run:<group>/<name>`), dem Container (`docker:<project>/<service>`), dem Arbeitsverzeichnis und zuletzt der Portnummer. Ein umbenannter Dev-Server behält seinen Namen über Neustarts hinweg; ein Name, der nur an Port 3000 gebunden ist, gilt für alles, was dort antwortet. Diese drei Befehle benötigen den Daemon und starten ihn, falls er nicht läuft.
### Einen Port lesen
```sh
sonar info 3000 # command, user, bind, stats, health
sonar logs 3000 # tail; docker logs for containers
sonar wait 5432 3000 --timeout 60s # block until ready
sonar wait 5432 --http=/health # wait for HTTP 200-399, not just TCP
sonar next 3000 # first free port from 3000
sonar next 3000-3100 -n 3 # three consecutive free ports
sonar graph # who is connected to whom
sonar graph --dot # Graphviz
sonar open 3000 # open in the browser
sonar attach 3000 # shell into the container, or TCP
sonar watch # live view
sonar watch --stats --notify
```
```sh
sonar next 3000
sonar next 3000-3100 -n 3 --json
sonar graph --json
sonar info --help
# check
```
`sonar wait` beendet mit `0` (bereit), `1` (Timeout) oder `2` (unterbrochen), was
es zu dem Element macht, das zwischen dem Starten von etwas und dessen Testen eingefügt wird:
```sh
docker compose up -d
sonar wait 5432 3000 --timeout 60s && npm run migrate && npm run test
```
**Daemon oder direkter Scan.** Jeder Lesebefehl fragt den Daemon, ob einer läuft, weil er die Antwort bereits hat und nicht `lsof` forken muss. Wenn keiner läuft, scannen sie direkt und geben einen Hinweis auf stderr aus, der dies mitteilt. `sonar kill` folgt derselben Regel: Ein erreichbarer Daemon führt das Töten aus, sodass er sofort neu scannt und seine nächste Antwort – und die Port-Historie – bereits weiß, dass der Port weg ist. Weder Lesen noch Töten starten einen Daemon hinter deinem Rücken. `--no-daemon` erzwingt den direkten Scan still und funktioniert bei jedem Befehl:
```sh
sonar list --no-daemon --json
# check
```
### `sonar host`
```sh
sonar host # cpu, load, memory and disk of the machine sonar watches
sonar host --json
```
```sh
sonar host
# check
```
Der Daemon misst seine eigene Maschine im Scan-Takt und veröffentlicht sie als
`localhost`-Zeile der `hosts`-Sammlung des Snapshots: Betriebssystem und Kernel, Uptime, CPU-
Prozent, Load Average, Speicher und die Festplatte, die `/` enthält. CPU-Prozent ist die zwischen zwei Scans geleistete Arbeit, daher ist sie null, bis der Daemon zweimal gescannt hat; ein
Wert, den eine Plattform nicht liefern kann — die Load Average unter Windows, die es dort nicht gibt —
ist null statt null. Jeder Host, der mit `sonar remote add` registriert wurde, tritt derselben Tabelle mit seiner eigenen Last bei. Der Befehl benötigt einen laufenden Daemon: Der
Daemon ist es, der die vorherige Stichprobe hält, gegen die ein Prozentsatz gemessen wird.
GPUs werden unter ihrem Host mit Auslastung und Speicher aufgeführt: aus `ioreg` unter
macOS (Apple-Silicon-Speicher ist unified, daher wird nur angezeigt, was die GPU hält),
und aus `nvidia-smi` oder den sysfs-Zählern von amdgpu unter Linux. Der Daemon liest sie
alle fünf Sekunden im Hintergrund, niemals im Pfad eines Befehls; `gpus` ist null,
wo es keine Quelle gibt (Windows, reines Intel-Linux) und `[]` auf einer Maschine ohne
GPU.
### `sonar remote install`
```sh
sonar remote install [email protected] # same version as this sonar
sonar remote install hetzner --version v0.6.0 # a Host from ~/.ssh/config
sonar remote install deploy@box --no-service # the binary, no daemon
```
Setzt Sonar auf einem Host, zu dem du bereits per SSH verbinden kannst, und startet dort seinen Daemon. Das Release-Archiv wird **auf dem Remote-Host** heruntergeladen und mit einer Prüfsumme verifiziert — nichts wird von dieser Maschine kopiert — und die Binärdatei landet in `~/.local/bin/sonar`, sodass nichts davon Root-Rechte benötigt. Der Daemon läuft als systemd-User-Unit, wo der Host eine hat (`~/.config/systemd/user/sonar.service`), und abgekoppelt, wo nicht; `loginctl enable-linger` wird als Hinweis ausgegeben, wenn die Benutzersitzung beim Logout enden und den Daemon mitnehmen würde.
Die installierte Version ist die Version des Sonar, von dem aus du es ausgeführt hast, sodass beide Enden dasselbe Protokoll sprechen. Ein erneuter Aufruf führt ein In-Place-Upgrade durch und startet den Daemon neu, wodurch Installation und Update derselbe Befehl sind.
Das Ziel wird unverändert an `ssh` übergeben: Ein `Host`-Alias aus `~/.ssh/config` funktioniert, ebenso die von ihm gesetzten `ProxyJump`, `IdentityFile` und `Port`. `--identity` und `--ssh-arg` sind für die Flags da, die eine Konfiguration nicht abdeckt.
### `sonar remote`
```sh
sonar remote add [email protected] # name taken from the target
sonar remote add hetzner [email protected] # or given
sonar remote list # status, latency, version, load
sonar remote remove hetzner
sonar list --host hetzner # that host's ports
sonar list --host "*" # every host, with a HOST column
sonar info 3000 --host hetzner
```
Ein registrierter Host führt denselben Daemon aus, und der Daemon auf dieser Maschine hält
eine SSH-Verbindung zu ihm aufrecht — `ssh <target> sonar daemon stdio`, wobei er
`~/.local/bin` vor dem entfernten `PATH` durchsucht — und multiplext
das, was er meldet, in den Zustand, den jeder Client bereits liest. Nirgendwo lauscht
etwas Neues: Der Socket des entfernten Daemons bleibt privat für den SSH-Benutzer, und Clients
sprechen niemals selbst SSH.
Jede Zeile trägt nun den Host, von dem sie stammt. Lokale Zeilen sagen `localhost` und
behalten die Schlüssel, die sie immer hatten, sodass sich nichts ändert, was sonar heute liest;
entfernte Zeilen sagen den registrierten Namen und werden mit `<host>/<port>:<bind>` verschlüsselt, was
es ermöglicht, dass Port 3000 auf zwei Maschinen zwei Zeilen sind. Ein Abonnent sieht nur
localhost, es sei denn, er fragt nach mehr (`state.subscribe {"hosts": ["*"]}`).
Das Ziel wird unverändert an `ssh` übergeben, sodass `~/.ssh/config`-Aliase, `ProxyJump` und
Identitäten alle gelten; `--ssh-arg`, `--identity` und `--port` decken ab, was eine Konfiguration
nicht abdeckt, und `--remote-bin` benennt ein sonar, das sich woanders befindet. Der Standardbefehl
läuft durch `sh`, sodass ein Windows-Host, dessen sonar vom
PowerShell-Installer stammt, `--remote-bin sonar` benötigt. sonar speichert kein Passwort und keinen Schlüssel. Ein Host, der
verschwindet, behält seine Zeile und seinen Status, während der Daemon es erneut versucht und dabei von einer Sekunde auf
dreißig zurückgeht, solange er registriert bleibt.
`--host` akzeptiert auch weiterhin ein bloßes `user@host`, von dem sonar nichts weiß: Es
fällt auf den agentenlosen `ssh` + `ss`/`lsof`-Scan zurück und gibt einen Hinweis auf
`sonar remote install` aus.
#### Auf einer anderen Maschine handeln
Jeder Schreibvorgang akzeptiert ebenfalls `--host` und tut dort genau das, was er hier tut:
```sh
sonar kill 3000 --host hetzner # stop a port on that machine
sonar kill -g api --host hetzner # a whole group of its services
sonar kill --all --filter docker --host hetzner # its containers
sonar up api --host hetzner # start a group from its sonar.yaml
sonar logs 3000 --host hetzner # tail its output here
sonar rename 3000 storefront --host hetzner # its name, in its database
sonar assign 3000 storefront --host hetzner
```
Der lokale Daemon leitet den Aufruf über die Bridge dieses Hosts weiter und gibt zurück, was der entfernte Daemon geantwortet hat, im selben Envelope, den ein lokaler Aufruf zurückgibt — jede Ergebniszeile gibt an, auf welchem Host sie stattgefunden hat, und das `affected` eines Kills trägt die `<host>/<port>:<bind>`-Schlüssel, die der Stream für diese Zeilen verwendet. Ein Streaming-Befehl streamt: `sonar up --host` gibt jeden Dienst aus, sobald die Gegenseite ihn startet, und Strg-C stoppt die entfernte Arbeit statt nur dieses Terminal.
Da der Schlüssel einer Zeile bereits ihren Host benennt, kann ein Client ihn direkt als Selektor zurückgeben — `{"key": "hetzner/3000:127.0.0.1"}` ist der ganze Selektor, Host inbegriffen. Ein Aufruf wirkt auf eine Maschine; zwei zu benennen ist ein Fehler statt eines halben Kills auf jeder.
Zwei Dinge bleiben lokal. `sonar attach` stellt *dieses* Terminal vor einen Prozess, also verweigert es `--host` und sagt, man solle per ssh hinübergehen und dort anhängen. Und eine Agent-Session ist Zustand, den dieser Daemon hält, also hat `sonar kill --session` keine entfernte Form. Alles andere benötigt den hier laufenden Daemon — er ist der Ort, an dem die Verbindung zur anderen Maschine lebt — und sagt das, statt still diese Maschine zu scannen.
---
[Read more](https://github.com/raskrebs/sonar)