new-grok-glance/ARCHITECTURE.md

grok-glance — architecture

grok-glance is remote control for grok: a self-hosted server plus web UI that mirrors a running terminal session and lets you drive it from a browser — send prompts, interrupt a turn, approve tool calls — without the terminal ceding anything.

It is one Go binary with the frontend embedded, one port, and no database.

   ┌────────────── your machine ──────────────┐        ┌──── anywhere ────┐
   │  grok TUI                                │        │                  │
   │    │                                     │        │                  │
   │    ├── AcpClientRx ──▶ tee ──▶ TUI       │        │                  │
   │    │                    │                │        │                  │
   │    │                    ▼                │        │                  │
   │    │              /rc bridge ═══ WSS ════╪══▶ glance ══ WSS ══▶ browser
   │    │                    │      (ACP)     │   (Go)     (glance     (HeroUI)
   │    └── AcpAgentTx ◀─────┘                │            envelope)   │
   └──────────────────────────────────────────┘        └──────────────────┘

Two links, two protocols, deliberately:

Link	Protocol	Auth	Who dials
grok ↔ glance	ACP over WebSocket, grok as the Agent	Authorization: Bearer <api key>	grok dials out
glance ↔ browser	glance's own JSON envelope	__Host-glance session cookie	browser dials in

---

Why it is shaped this way

grok dials out

grok runs on a laptop, in a devcontainer, on a box behind NAT. glance runs where you can reach it. Making grok the dialer means remote control works without a port forward, a tunnel, or an inbound firewall rule on the machine that holds your source tree — the one place you least want an open port.

The consequence is that glance never initiates: an agent appears when it connects and disappears when it hangs up, and the session list is exactly the set of live sockets.

The roles are inverted relative to the terminal

Inside grok, the TUI is an ACP Client talking to the agent runtime. Over the /rc link grok presents itself as the Agent and glance is the Client.

That inversion is the whole trick. It means glance is a stock ACP client — it receives session/update and session/request_permission, it sends session/prompt and session/cancel — and needs no knowledge of grok's internals to be a second head on the same session. It also means the browser's Stop button is a real session/cancel, not a simulated keypress.

The browser is not an ACP peer

/api/ws speaks a small glance-specific envelope (see Browser protocol), not ACP. Translating once, server-side, keeps three things out of the frontend: JSON-RPC id correlation, the pending-interaction table, and the ring buffer. The browser sends {"type":"prompt", ...} and receives {"type":"frame", ...}; everything that must be exactly right about the ACP conversation is exactly right in one place, in Go, with tests.

No database

Transcript history is a per-agent in-memory ring (4096 frames, internal/hub/ring.go). A reload replays it; a server restart does not. This was a deliberate choice: the alternative is a store of every prompt, file path, diff and command output from every session, on disk, forever, guarded by one TOTP secret. The ring is bounded, unbackupable by construction, and enough for what the UI is actually for — watching the turn that is happening now.

What is persisted is only what cannot be re-derived: the TOTP secret, the cookie signing key, and API key hashes, in ~/.grok/glance/state.json (0600).

---

The grok side (/rc)

Implemented as patches 0003/0004 in the sibling newgrok/ tree. Summarised here because the two halves only make sense together; the authoritative comments are in newgrok/work/crates/codegen/xai-grok-pager/src/rc/.

The tee. The pager already holds an AcpAgentTx (to the agent) and an AcpClientRx (from it). Every inbound message passes through one function, so /rc inserts one call there: mirror a copy to the bridge, return the original untouched. Remote control needs no change to the agent runtime, the session actor, or the shell — which is what makes "does not disturb the session" true rather than aspirational.

Both notification rails are mirrored. Alongside the stable session/update, grok emits ~60 grok-specific variants as x.ai/session_notification — tool-call deltas, subagents, retries, turn boundaries. Forwarding only the standard rail would give glance a transcript with the streaming taken out. _meta (eventId, promptId, chunkId, isReplay) is forwarded verbatim so a viewer can dedup and order the stream the same way the TUI does.

Interactions are raced, not routed. The three reverse-requests a human must answer — session/request_permission, x.ai/ask_user_question, x.ai/exit_plan_mode — carry their own oneshot reply channel. The tee lifts the real sender out, hands the TUI a substitute, forwards a copy to glance, and gives the answer to whichever side replies first. The loser is told to retract its dialog. Neither side is privileged, and no configuration decides who may answer.

Failure is local-only. The bridge is its own task with its own reconnect backoff. If glance is down, unreachable, or killed mid-turn, the terminal session is unaffected — the tee degrades to a plain move the moment the bridge's channel closes.

---

The glance side

cmd/glance/main.go     serve | apikey add·list·rm | bootstrap | version
internal/
  acp/       JSON-RPC framing, the ACP subset glance needs, method predicates
  hub/       the live system: agents, browsers, ring buffer, interaction table
  auth/      TOTP enrollment and login, bootstrap gate, cookie signing
  state/     ~/.grok/glance/state.json (0600)
  httpapi/   routing, middleware, the two upgrades, the embedded SPA
web/         Vite + React 19 + Tailwind 4 + HeroUI 3

hub — where everything meets

Hub owns two maps: connected agents by API-key id, and connected browsers. Everything else is per-agent state on Agent (internal/hub/agent.go):

• ring — the replay buffer. Frames are stored exactly as received, bytes unchanged.
• interactions — open reverse-requests, keyed by grok's JSON-RPC id.
• calls — glance's own outstanding requests, keyed by id, each with a buffered reply channel so a late response never blocks the reader goroutine.
• outbound — a bounded queue drained by a single writer goroutine, because coder/websocket permits one concurrent writer and prompts, replies and pings all originate on different goroutines.

Fan-out is unfiltered. Every browser receives every agent's frames. At this scale (a handful of sessions, a handful of viewers) per-browser filtering would be one more thing to get wrong for no measurable gain; the frontend ignores frames for the agent it is not showing.

Backpressure is a disconnect, not a buffer. A browser that cannot keep up fills its 256-frame queue and is dropped; it reconnects into a fresh snapshot. An unbounded queue would turn one slow phone on hotel wifi into the server's memory problem, and a snapshot is cheaper than the backlog it would have replayed anyway.

Turn state is derived, not declared. classifyUpdate reads a single field — update.sessionUpdate — from either rail to decide whether a turn is running. Nothing else in the xAI rail's payload is interpreted, because those ~60 variants are internal to grok and drift with every upstream sync. The stable rail carries correctness; the xAI rail is presentation.

The permission race, end to end

grok ──▶ session/request_permission (id 7) ──▶ glance
                                                 │  ring? no. interactions[7] = …
                                                 └─▶ {"type":"interaction"} to all browsers

  … whichever happens first:

  browser answers  ──▶ Agent.Answer(7)  ──▶ JSON-RPC response id 7 ──▶ grok
                                        └──▶ {"type":"interaction_resolved", by:"browser"}

  terminal answers ──▶ grok sends x.ai/rc/interaction_cancelled(7)
                                        └──▶ {"type":"interaction_resolved", by:"terminal"}

Agent.Answer deletes from interactions under the lock and reports whether it was still there. A false return is not an error — it is the ordinary outcome of losing the race — and the browser that lost is sent by:"elsewhere" with "already handled elsewhere". That is why exactly one JSON-RPC response ever reaches grok for a given id, even when two browsers and a terminal all click at once.

A browser may also decline, which replies to grok with a JSON-RPC error. grok reads that as "glance is not answering this", leaves the terminal's dialog up, and the turn proceeds when the user answers there. Declining is not denying — denying is an ordinary answer with a reject option.

Requests glance will not serve

grok drives nothing on this link. An inbound request that is not one of the three interactions gets -32601 Method not found, including fs/* and terminal/*. glance has no filesystem to offer, and a fabricated success would leave grok acting on a lie. (In its default configuration the pager does not advertise those capabilities, so they should not arrive at all; the arm exists because "should not" is not "cannot".)

---

Browser protocol

One JSON object per WebSocket message, in both directions.

Browser → server (internal/hub/browser.go, command):

type	Fields	Meaning
list	—	resend the agent list
subscribe	agent	send a full snapshot of one agent
prompt	agent, text	start a turn
cancel	agent	interrupt the running turn
answer	agent, id, result	answer an interaction
decline	agent, id, reason	hand it back to the terminal

Server → browser (Event): agents, snapshot, frame, interaction, interaction_resolved, notice, error.

Two details that matter:

• prompt and cancel run detached. A prompt does not return until the turn ends, which can be many minutes. Waiting inline would stall the browser's whole command stream — including the Stop button it might need next. They run on their own goroutine under context.WithoutCancel, and progress arrives as mirrored frames like anything else.
• snapshot is authoritative. It carries the ring, the open interactions, the session metadata and the turn state in one message. The frontend replaces state with it rather than merging, which is what makes a reload or a reconnect land on the server's view instead of a half-stale one.

---

Authentication

There is no username and no password. There is one authenticator app and one server.

Bootstrap. On first serve, glance mints a one-time token, prints it with a setup URL, and writes it to ~/.grok/glance/bootstrap.token (0600) — stderr for the terminal case, the file for the systemd case. /api/setup/* answers 404 unless the request carries a valid, unused token, and 404 again once enrollment succeeds. Without that gate, the window between "server starts" and "operator opens the browser" is a race anyone who can reach the port may enter.

Enrollment. /api/setup/begin returns a candidate secret and otpauth:// URI, which the page renders as a QR code. Nothing is persisted until /api/setup/complete verifies a code generated from that secret — a failed QR scan must not be able to lock the operator out of their own server. Success stores the secret, burns the bootstrap token, and issues a session cookie, because you have just proved you hold the authenticator and a login form one second later would ask for the same proof.

Login. Six digits, ±1 time step for clock skew. Failures are rate-limited (8 per 5 minutes, counted globally — the limiter protects the secret, not a user account). Accepted time steps are burned, so a code observed over a shoulder cannot be replayed inside its 30-second window.

Session cookie. __Host-glance — the prefix is a browser-enforced promise of Secure + Path=/ + no Domain, so a sibling host cannot set or overwrite it. The value is <expiry>.<hmac>, signed with a key in state.json: no session table, so a restart does not sign everyone out, and deleting state.json invalidates every outstanding cookie at once. HttpOnly, SameSite=Strict, 12 hours.

API keys. glance apikey add <name> prints glance_sk_… once; only a SHA-256 hash is stored. The key identifies one grok instance, and its id is the agent id — which is why reconnecting with the same key replaces the previous connection instead of accumulating a ghost session in the list.

What this model does not protect against

Stated plainly, because the threat model is small on purpose:

• glance is a remote control for a shell agent. Anyone who can authenticate can approve arbitrary tool calls. It listens on 127.0.0.1 by default; exposing it should be a deliberate act, ideally behind a reverse proxy that terminates TLS.
• No TLS of its own. --insecure-cookie exists for plain-HTTP localhost and is refused on a non-loopback address, because a session cookie without Secure on a real network is a credential in cleartext.
• No account recovery. Losing the authenticator means deleting state.json — which also revokes every API key and session. glance bootstrap refuses to mint a second token once enrolled, since a re-enrollment path is exactly the door the bootstrap gate exists to keep shut.
• One operator. There are no roles, no audit log, and no per-key permissions.

Content-Security-Policy

default-src 'self' with no unsafe-inline for scripts. glance renders agent output — file contents, command output, model text — and none of it is trusted markup. Plan content is rendered as preformatted text rather than parsed as Markdown for the same reason: it avoids shipping a parser and a sanitiser to display text an agent wrote.

---

Frontend

React 19 + HeroUI 3 (react-aria-components) + Tailwind 4, built by Vite into web/dist and embedded with //go:embed all:dist.

• App.tsx gates on /api/status → Setup / Login / Console, and calls useTheme exactly once at the root (each call owns its own state — a second call would desync).
• Console owns the single GlanceSocket, so moving between the session list and a session neither drops the connection nor re-requests a snapshot.
• lib/acp.ts folds frames into a Transcript of seven item kinds (user, assistant, thought, tool, plan, notice, turn-end). Tool calls are updated in place by id, so a streaming tool_call_update refines the card that is already on screen.
• components/PermissionDialog.tsx renders all three interaction types as cards, not modals — a modal that closes itself when the terminal wins the race is more jarring than a card doing the same, and cards stack when several are open.

The response payloads it builds are pinned to grok's Rust types, not guessed: {"outcome":{"outcome":"selected","optionId":…}} for permissions, {"outcome":"approved"} for plan mode, and for questions an {"outcome":"accepted","answers":…} envelope whose map is keyed by question text, in original order, values as arrays of labels, unanswered questions omitted — the exact construction xai-grok-pager/src/views/question_view.rs performs. Getting this wrong does not fail loudly; it fails as an agent that received an answer to a question nobody asked.

An unrecognised interaction method renders its raw params and offers only decline, which is the honest response to a request whose reply shape glance does not know.

---

Testing

internal/hub/hub_test.go drives the hub over real WebSocket connections with a fake grok and fake browsers. The behaviour that matters — an interaction reaching a browser, an answer reaching grok, two sides racing — lives in the interleaving of three goroutines, and a mocked transport would test the mock. It covers the permission round trip, terminal-wins retraction, browser-vs-browser arbitration, decline, ring replay on subscribe, method-not- found, reconnect-replaces-ghost.

internal/httpapi/server_test.go covers the auth boundary: the bootstrap 404, enrollment, rate limiting, cookie forgery, both upgrades, and the SPA fallback's refusal to swallow /api/*.

What tests cannot cover is the race against a real terminal. The end-to-end checklist in CLAUDE.md is not optional.