# grok-glance A Grok Build plugin that puts a small web dashboard behind a passkey, so you can glance at what your agents are doing from your phone — and tap **approve** or **deny** when one wants to run something risky. Several agents at once is the normal case, not an edge case. It is deliberately small: read-only, plus remote approve/deny. It cannot send prompts, edit files, or drive a session. ``` ┌────────────────────────────┐ │ ● grok-glance 2 working ·│ │ 1 waiting │ ├────────────────────────────┤ │ Waiting on you 62s │ │ Bash · in ●2 remote-grok │ │ rm -rf ./dist │ │ ▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░ │ │ [ Deny ] [ Approve ] │ ├────────────────────────────┤ │ Agents 3 live │ │ All agents 3 │ │ ●1 remote-grok working │ │ Read 4s state.ts +2 │ │ 31 tools now │ │ ●2 remote-grok waiting │ │ Bash 1m rm -rf ./dist │ │ 12 tools 1 failed 4s │ │ ●3 docs-site error │ │ build failed 2m │ ├────────────────────────────┤ │ Activity │ │ ● Read state.ts ●1 14:22 │ │ ● Bash npm test ●3 14:21 │ └────────────────────────────┘ ``` ## Requirements - Node.js 20 or newer, and npm. - Grok Build. - For phone access: [Tailscale](https://tailscale.com/) on both the machine and the phone. See [Why Tailscale](#why-tailscale-and-not-just-the-lan-ip) — a LAN IP genuinely cannot work. ## Install ```sh git clone grok-glance cd grok-glance npm install && npm run build ``` The build produces `dist/server` (the daemon) and `dist/web` (the dashboard). Both are required; the daemon serves the dashboard itself. `hooks/hooks.json` is checked in as-is — nothing about it is generated or machine-specific. The shared secret the hook scripts authenticate with lives in `~/.grok/glance/hook.secret` (mode 0600) and is created by the daemon on first start; it never appears in `hooks.json`. Then register the directory with Grok Build. Plugins are installed from a marketplace catalog, so for a local checkout the shortest path is a one-entry catalog. Create `.grok-plugin/marketplace.json` in a directory that contains your checkout: ```json { "name": "local", "description": "Local plugins", "owner": { "name": "me" }, "plugins": [ { "name": "grok-glance", "description": "Passkey-guarded phone dashboard for Grok Build.", "category": "monitoring", "source": { "type": "local", "path": "./grok-glance" } } ] } ``` …then add that marketplace and install `grok-glance` from Grok Build's `/plugin` interface. Once installed, the daemon starts by itself: the `SessionStart` hook boots it in the background on the first session after installation. ## Get it onto your phone The daemon binds to `127.0.0.1` only and never opens a port to your network. Tailscale Serve publishes it inside your tailnet with real TLS: ```sh tailscale serve --bg 127.0.0.1:8791 tailscale serve status # note the https://..ts.net URL ``` Tell grok-glance which origin it is being served on — this is also the WebAuthn relying-party ID, so it has to be exact: ```sh node bin/glance set-origin https://..ts.net ``` ## Enrol the phone ```sh node bin/glance enroll ``` That prints a URL and an 8-character code, good for 10 minutes, single use: ``` Open this on your phone: https://mybox.tailnet-1234.ts.net/?enroll Enrollment code: K7QM4RTX Valid for: 10 minutes (single use) ``` Open the URL on the phone, type the code, tap **Create passkey**, and confirm with Face ID / a fingerprint / the device PIN. From then on the phone unlocks the dashboard with that passkey and nothing else gets in. Repeat for each device you want. `node bin/glance devices` lists them; `node bin/glance revoke ` removes one (and kills its live session immediately). ## What the dashboard shows - **Agents** — one row per agent whenever there is more than one: badge, workspace, state, what it is running right now, and how long ago it last did anything. Tap one to focus it; tap **All agents** to come back. Ended sessions are folded away behind a toggle. - **Now** — the focused agent: its workspace, state (working / waiting on you / idle / error / ended), the last thing you asked, **every** tool it currently has in flight with a live elapsed timer each, and running counts of tools, failures and denials. - **Activity** — a merged timeline of prompts, tool calls with durations, failures, permission denials, notifications, subagents, compactions, session start/end. Each row is stamped with the badge of the agent it came from; focusing an agent filters it down to that one. - **Pending approvals** — a card per waiting tool call, with the command, which agent is asking, a countdown, and two large buttons. Updates arrive over Server-Sent Events. The server sends whole snapshots rather than deltas, so a phone that slept through twenty events still wakes up showing the truth. ## Several agents at once Watching four agents on a phone is a different problem from watching one, so a few things are not what you might assume: - **Badges, not names.** Labels are workspace basenames, so two agents in the same repo are both "remote-grok". The daemon hands each session a small ordinal in arrival order — `●1`, `●2` — and the dashboard colours everything belonging to that agent with it: its row, its timeline lines, its approval cards. The ordinal survives a daemon restart. - **Sorted by who needs you, then fixed.** Rows are ordered *waiting → error → working → idle → ended*, and ties break on badge. Within a state an agent never changes position, because a list that re-sorts on every event moves the row out from under a thumb already heading for it. - **A chatty agent cannot bury the others.** The event ring is global, but eviction always takes from whichever session currently holds the most of it. One agent in a tight loop trims itself rather than blanking everyone else's history. - **Parallel tool calls are all shown.** An agent runs several tools at once; the focused card lists them and the overview row shows the first with a `+2`. Durations are matched oldest-first per tool name, since hook payloads carry no call id. - **A restart does not lose the roster.** Events carry no workspace root, so the session map is persisted separately (`sessions.json`) and reloaded on boot — otherwise every agent would come back nameless until it happened to speak again. In-flight tools are deliberately *not* restored: they belonged to a process that no longer exists. `glance status` shows the same breakdown from a terminal: ``` sessions : 4 (1 waiting on you, 1 error, 2 working) ``` ## Remote approve / deny Off by default. Turn it on from the phone's settings panel, or: ```sh node bin/glance approval risky # Bash, Write, Edit, MultiEdit, NotebookEdit node bin/glance approval all # every tool call — noisy node bin/glance approval off ``` Defaults worth knowing: | Behaviour | Default | Changeable from the phone | Why | |---|---|---|---| | Only wait when a phone is watching | on | yes | Otherwise a closed browser tab stalls the agent for 90s per tool call. | | On timeout | allow | yes | Flip to *deny* if you would rather fail closed. | | Timeout | 90s | no — edit `config.json` | Also the ceiling: the approval hook gets 125s in `hooks.json`, and the daemon clamps a larger `timeoutMs` down to 90s so the script always outlives its own wait. | | Risky-tool pattern | `^(Bash\|Write\|Edit\|MultiEdit\|NotebookEdit)$` | no — edit `config.json` | Shown on the phone but not editable: a typo'd regex would silently change what gets gated. | **This is a convenience gate, not a security boundary.** Every failure path is fail-open: daemon down, hook timeout, malformed response, port mismatch, a hook secret the daemon no longer recognises — the tool call proceeds. If you need calls actually blocked, use Grok Build's own permission settings. ## CLI `bin/glance` is plain Node with no dependencies. Run it as `node bin/glance `. | Command | What it does | |---|---| | `status` | Running? On which origin, with how many devices? | | `up` | Start the daemon in the background | | `serve` | Run it in the foreground (for debugging) | | `stop` | Stop it | | `logs` | Last 60 lines of the daemon log | | `enroll` | Mint a one-time enrolment code and URL | | `set-origin ` | Set the public https origin and RP ID | | `devices` | List enrolled devices | | `revoke ` | Revoke a device | | `approval ` | Set the approval policy | ## Files and configuration Everything lives in `~/.grok/glance` (mode 0700), or `$GLANCE_HOME` if you set it: | File | Contents | |---|---| | `config.json` | Port, bind host, public origin, RP ID, approval settings | | `credentials.json` | Enrolled passkeys — credential IDs, public keys, counters. No secrets of yours. | | `auth-sessions.json` | Live dashboard sessions, stored as SHA-256 hashes of the cookie tokens | | `secret.key` | 32-byte HMAC key used to sign session cookies | | `admin.token` | Rotated every daemon start; authenticates the CLI | | `hook.secret` | Shared secret the hook scripts present on `/hook/*`. Created once, mode 0600, never rotated — a rotation mid-session would 403 whatever was already in flight. Delete it and the daemon mints a new one on its next start; hooks then need that restart to agree again, which `glance status` will tell you about. | | `events.jsonl` | Append-only event log, one JSON object per line, rotated at 5 MB | | `sessions.json` | The agent roster — label, badge, workspace, state, counts — so a restart comes back with the overview intact. Written debounced, flushed on shutdown; sessions older than 12 hours are dropped on load. | | `daemon.log` | Daemon stdout/stderr | Three environment variables override `config.json`, which is mostly useful for testing a second instance without touching your real one: | Variable | Effect | |---|---| | `GLANCE_HOME` | Where all of the above lives. Read by the daemon, the CLI, and the hook scripts. | | `GLANCE_PORT` | Port to listen on (and, for the CLI and hooks, to talk to) | | `GLANCE_ORIGIN` | Public origin, as if set with `set-origin` — but not persisted | Nothing in `hooks/hooks.json` is machine-specific: the hook scripts read `config.json` themselves, so changing the port or `approval.timeoutMs` needs nothing but a daemon restart. ## Security notes **Network surface.** The daemon listens on `127.0.0.1:8791` and makes no outbound connections of its own. Three classes of caller: | Path | Caller | Authentication | |---|---|---| | `/hook/record`, `/hook/approve` | Grok Build's hooks, from this machine | shared secret from `hook.secret`, plus a refusal of any proxied request | | `/api/*`, `/events` | the dashboard | passkey session cookie + CSRF header | | `/local/*` | the `glance` CLI | rotating admin token from `admin.token` | None of the three trusts the source address, because `tailscale serve` proxies remote traffic to `127.0.0.1` — the daemon cannot tell a local caller from a tunnelled one by address alone. Without the hook secret, anyone who could reach the tunnel could forge timeline events and answer approval prompts on your behalf; `/hook/*` compares the secret in constant time before it reads a body, and additionally refuses any request carrying `x-forwarded-for` or `x-forwarded-proto`, which a local hook process never sends and a tunnelled caller always does. That refusal costs nothing, because no legitimate hook traffic comes through the tunnel: hooks are local processes talking to loopback. It applies **only** to `/hook/*` — the dashboard arrives through `tailscale serve` with those headers on every request and is unaffected. **Session cookie** is `HttpOnly`, `SameSite=Strict`, HMAC-signed, and `Secure` whenever the request arrived over https. Only a SHA-256 hash of the token is stored, compared in constant time. Sessions last 30 days; revoking a device drops its session at once. **Cross-site defence.** Every POST must carry exactly `content-type: application/json`, which is not a CORS-safelisted type, so a hostile page cannot post here without a preflight that is never answered. `/api/*` additionally requires an `x-glance-csrf` header. The pages themselves are served with a strict CSP (`script-src 'self'`, no framing, no form actions) and `no-store`. **User verification is required**, for both enrolment and sign-in: the phone asks for a biometric or PIN every time, so a stolen unlocked phone is not automatically a way in. Passkeys are created as resident keys, so the phone offers the right one without you typing a username. **Rate limits.** Authentication attempts are capped (40 per 5 minutes), enrolment attempts more tightly (12 per 5 minutes, and a code burns itself after 5 wrong guesses). The limiter is keyed globally on purpose: behind a tunnel every request arrives from `127.0.0.1`, so per-IP buckets would be one bucket wearing a hat. **What crosses the wire.** Tool names, truncated arguments, prompt first lines, file paths, durations, and exit statuses — a summary, not a transcript. Known secret shapes are redacted before storage: `sk-`/`rk-`/`pk-` keys, `xai-` keys, GitHub and Slack tokens, AWS access key IDs, JWTs, PEM private-key blocks, `Authorization:`/`Bearer` headers, and `password`/`secret`/`token`/`api_key` assignments. This is a filter, not a guarantee — a secret in an unusual shape will show up in the timeline. Treat the dashboard as being as sensitive as your terminal. **Threat model.** grok-glance assumes the machine it runs on is trusted. It protects against someone else on your tailnet, or a browser tab you left open, reaching the dashboard. It does not protect against a local attacker who can read `~/.grok/glance` — with `admin.token` they can enrol their own device. ### Why Tailscale, and not just the LAN IP? WebAuthn will not run outside a secure context, and — separately — a bare IP address cannot be a relying-party ID. So `http://192.168.1.20:8791` can never hold a passkey, no matter what the browser is willing to render. You need a hostname with valid TLS. Tailscale Serve gives you one for free, with the tunnel closed to everything outside your tailnet. Any other route to a real https hostname works too: set `origin` in `config.json` (or use `set-origin`) to whatever your reverse proxy terminates on. If you put grok-glance behind a proxy reachable from the public internet, the passkey gate is the only thing standing in front of it. Changing the origin changes the RP ID, and **passkeys are bound to the RP ID** — existing devices stop working and must be enrolled again. ## Hook wiring `hooks/hooks.json` subscribes to all 14 lifecycle events and is a plain checked-in file — edit it directly. Every entry is a `command` hook. That is not a style choice: an `http` hook cannot reach this daemon by any route. Grok Build's http runner rejects every scheme but `https`, then **resolves the host** and refuses the resolved address if it is private, link-local or CGNAT (`xai-grok-hooks/src/runner/http.rs`, `validate_hook_url` + `is_blocked_ip`). Plain http on loopback fails the scheme check; the tailnet fails the address check, because `*.ts.net` resolves into `100.64/10` (and `fd7a::/48`, inside the blocked `fc00::/7`). On top of that the runner sends no request header but `Content-Type`, with no configuration surface for one, so such a hook could not authenticate itself even if it could connect. This plugin shipped `http` hooks for a while, and the result was 13 passive hooks failing validation silently on every event. A command hook has none of those problems. It is a local process, so no URL is validated, nothing traverses the tunnel, and it can present the shared secret — hook traffic goes straight to `http://127.0.0.1:8791` and never leaves the machine. So each observed event runs `bin/glance-record.mjs`, which costs a Node start (~40 ms) and POSTs one event. Two entries differ: - `SessionStart` runs `bin/glance-up.mjs`, which is what boots the daemon. - `PreToolUse` is wired **twice** — a recording entry for the timeline, and a second entry matching only `^(Bash|Write|Edit|MultiEdit|NotebookEdit)$` that runs `bin/glance-approve.mjs`. PreToolUse is the only blocking event, and a command hook is the only documented way to return a deny decision; keeping the match narrow means the gate's cost is paid only for calls that could actually need a tap. Its `timeout` is a fixed 125s, and the daemon clamps its own wait to 90s against it (`APPROVAL_MAX_WAIT_MS`) so the script is never killed before it can fail open. The hook scripts use nothing but the Node standard library and always exit 0 unless they are deliberately denying — including when the daemon rejects their token. ## Deliberately omitted Not oversights — decisions: - **Sending prompts or steering the session.** Hooks cannot inject input, so a phone-to-agent channel would need a second transport and a much larger threat model. - **Full transcripts and tool output.** Summaries only. Streaming assistant text through a phone would mean shipping your codebase through it. - **Push notifications.** Needs a VAPID key, a service worker, and a subscription store, for a dashboard you open on purpose. - **Multi-user accounts and roles.** One user, several devices. - **Diff views, file browsing, cost/token charts, log search, session resume.** All out of scope for a glance. - **Editing the risky-tool pattern from the phone.** Shown but not editable: a typo'd regex there would silently change what gets gated. Edit `config.json` instead. ## Licence MIT.