grith daemon

grith dashboard [start | stop | status | pair]

The daemon is the long-running grith process that owns the dashboard server, the shared audit + digest, the reputation table, and the notification dispatcher. See Daemon and thin-client sessions for the "why".

grith daemon and grith dashboard are the same command — use whichever reads better. The examples below use grith dashboard.

Subcommands

grith dashboard start

Start the daemon in the background and print its connection details. The command returns immediately; the daemon keeps running until you stop it.

grith dashboard start

Dashboard started: http://127.0.0.1:3141  (opened in your browser)
  Stop with: grith dashboard stop

On a desktop session grith opens the dashboard in your browser automatically, authorising it without ever printing the token (see Browser authorisation). On a headless / SSH box it prints a one-time pairing link instead:

Dashboard started: http://127.0.0.1:3141
  Open this once to authorise your browser: http://127.0.0.1:3141/#pair=ab12cd…
  Stop with: grith dashboard stop

The dashboard is also auto-started for you when you run grith run or grith exec — those instances idle-shut-down when the session ends, whereas an explicit grith dashboard start persists until grith dashboard stop.

Host and port come from the [server] config (default 127.0.0.1:3141), or per-run via GRITH_SERVER_PORT. The HTTP API is documented in API overview.

grith dashboard status

$ grith dashboard status
Dashboard is running.
  URL:   http://127.0.0.1:3141
  PID:   18123
  Pair:  grith dashboard pair   (authorise a browser)
  Stop:  grith dashboard stop

Prints "Dashboard is not running." (and how to start it) when it's down.

grith dashboard pair

Authorise a browser for the dashboard. Mints a fresh single-use pairing link and either opens it in your browser or prints it for you to open.

$ grith dashboard pair
Opened the dashboard in your browser to authorise this session.

Use it when a browser isn't authorised yet — a new browser, after clearing site data, or a second machine. A once-paired browser keeps working across daemon restarts, so you rarely need this more than once. See Browser authorisation.

grith dashboard stop

Graceful shutdown. The daemon flushes the reputation table, finalises pending audit writes, unregisters sessions (they fall back to standalone), and exits.

grith dashboard stop

Browser authorisation

The dashboard binds loopback-only (127.0.0.1:3141) by default, but reachability on loopback is not treated as authorisation. Browser-facing mutations and sensitive reads (audit, digest, config, session detail, …) require a per-server dashboard token, stored at ~/.config/grith/dashboard.token (0600) and reused across restarts. Low-sensitivity status (/health, /tier, /proxy/status) stays open for zero-config scripting.

You never see or type the token. It reaches your browser one of two ways:

• Auto-open (default, desktop): grith dashboard start / grith run / grith exec open the browser at a #pair= URL that the SPA exchanges for the token, then strips from the address bar. Controlled by server.auto_open_dashboard.
• One-time pairing link (headless / SSH, or auto-open disabled): the CLI prints http://127.0.0.1:3141/#pair=<code>. Open it once; the code is single-use and consumed on first load, so a later screenshot of the link is inert. Run grith dashboard pair any time to mint a fresh one.

If a browser tab shows "This browser isn't authorised…", run grith dashboard pair and reload. See Trust boundaries for the threat model.

What the dashboard shows

• A security-posture hero — total tool calls inspected under Zero Trust, the allow / review / deny split, live agents, and active filters.
• Sessions led by the project name the agent is supervising (from its working directory), with the tool, uptime, and a live indicator.
• A Share stats button that exports a branded PNG of the aggregate posture for socials. The image contains only aggregate counts — never a path, project name, destination, or session detail — so it's safe to post.
• Live evaluation scores, call-type breakdown, the three-phase filter pipeline, the quarantine digest, audit, the session-pinned binary inventory, and listener-rewrite history.

Logs and pid

Path	What
~/.config/grith/dashboard.pid	PID + port of the running dashboard daemon.
~/.config/grith/dashboard.token	Per-server browser auth token (0600). Delete to rotate.
~/.config/grith/daemon.token	Daemon IPC bearer token (0600).
~/.config/grith/config.toml	[server] section controls the daemon's HTTP server.

Running as a system service

For unattended deployments, run the daemon under systemd / launchd / a process supervisor. The shipping unit files are at contrib/systemd/grith.service in the grith repo. See Running as a daemon for the full operations guide.

Restart safety

Restarts are clean on Pro (state is checkpointed before the stop). On community, in-flight digest items are dropped — they were never persistently stored, so a restart auto-denies them via timeout in the calling thin client.

See also

• Daemon and thin-client sessions
• Trust boundaries — the dashboard auth model
• Running as a daemon
• [server] config
• Reverse proxy & TLS