How SuperGrok Powers Atlas Docs

Atlas's AI features — chat with a document, the Knowledge Pipeline, and AI-assisted comment resolution — are all backed by one personal SuperGrok subscription, reached through a small localhost bridge. This is the full picture: how it's wired, what every AI click actually does on the VPS, and a real bug this design surfaced (and how it got fixed).

The pieces

🧩 Nothing here is a hosted "AI API." It's a personal SuperGrok CLI session, wrapped in a

tiny HTTP service that only Atlas (and nothing else on the internet) can reach.

• The Grok CLI (~/.grok/bin/grok) — a normal terminal tool, authenticated once via

OAuth against the owner's SuperGrok account. Its credentials never leave the box.

• grok-bridge — a small FastAPI service (~/grok-bridge/app.py) running as a systemd

user service on 127.0.0.1:8700. It takes a {prompt, system, web_search} JSON body, shells out to grok -p "<prompt>" --output-format plain, and returns the text. Every request needs a shared-secret header (X-Bridge-Token); a semaphore caps it at 2 concurrent grok processes so the box never gets swamped.

• Atlas's backend (backend/app/ai.py::grok_complete) — the only code allowed to talk to

the bridge. It's called from three places:

• Owner gating — every one of those endpoints checks settings.grok_allows(email, id),

an allowlist (ATLAS_AI_GROK_USER_IDS / ATLAS_AI_GROK_EMAILS in .env). Nobody else who signs up for Atlas can spend a cent — or a token — of this subscription.

• The Telegram bot (@datbrahmbot) is a client of the same pipeline, not a separate AI

integration: a message to the bot just creates a KnowledgeJob row, same as pasting a link into the Knowledge Pipeline panel in the browser.

Does every AI click spawn a new VPS session?

Yes — and it's worth being precise about what that means. grok -p "starts a fresh session by default" (that's from Grok's own docs, not a guess); there's no long-lived agent process sitting around between requests. Every chat message, every knowledge job, every comment resolution is:

1. grok-bridge receives the HTTP call and shells out to grok -p ....
2. That process authenticates from the cached OAuth token, creates a brand-new session

(a fresh entry under ~/.grok/sessions/), runs the one prompt, prints the answer, exits.

1. Nothing is kept warm. The next AI call repeats the whole thing from scratch.

Practically:

• Not a memory problem. Each grok process is short-lived and the bridge's semaphore

caps concurrency at 2, so this can't pile up and starve the box the way a leaked long-running process would.

• It is unbounded disk growth. Every call leaves behind a session file and a chunk of

~/.grok/logs/unified.jsonl (already over a megabyte from normal use). Nothing prunes these automatically today. It's not urgent, but worth a manual sweep occasionally: find ~/.grok/sessions -mtime +30 -delete (adjust the window as needed). Not automated yet — can be turned into a cron job later if it becomes annoying.

The bug: why knowledge jobs kept failing

Before this fix, pasting a GitHub link (or a dolthub.com or x.com link) into the Knowledge Pipeline reliably failed with a cryptic Expecting value: line 1 column 1 (char 0) — a JSON parser choking on a completely empty response.

I reproduced it directly against the CLI, outside of Atlas entirely, to find the real cause rather than guess at one:

• Asking Grok to open and research a specific GitHub URL and produce a knowledge card came

back stopReason: "Cancelled" with an empty response, consistently, whether the request asked for prose or JSON.

• Asking Grok to search the web for the same topic — without opening that page directly —

came back stopReason: "EndTurn" with a full, well-reasoned answer, no restrictions on tokens, tools, or reasoning effort in either case.

• Directly opening github.com pages specifically reproduced the cancellation on repeat

tries; opening a plain page like example.com worked instantly. That points at GitHub (and likely dolthub.com, x.com individual posts) blocking or challenging the direct fetch, and the CLI surfacing that as a silent cancellation instead of a recoverable tool error.

The fix (backend/app/knowledge.py) doesn't cap anything — it just stops asking Grok to open the source page directly. The pipeline now runs two ordinary calls instead of one:

1. Research call — full web search access, asked to write a plain-text brief. The prompt

frames the source URL as a citation to reference, not a page to fetch: "research its topic via web search rather than opening it directly."

1. Format call — no tools, just reshapes that brief into the same card JSON the app

already expects (title, summary cards, key facts, sources).

Verified against the exact URL that was failing in production (github.com/dolthub/dolt): the job now reaches review status with a real, multi-card document instead of failed.

Reliability extras that shipped alongside this

• Retry — a failed job can now be retried from the Atlas UI (a Retry button right on the

failed job card) or from Telegram (/retry, retries the most recent failed job). Previously a failure was a dead end; now it's one tap.

• Failure messages are clearer — an empty AI response is now reported as *"AI returned no

content — try again"* instead of a raw JSON parser exception.

The honest tradeoff

This whole design reuses a personal SuperGrok subscription as a server-side backend for a small web app. That's a known, accepted tradeoff, not an oversight: it's gated hard to the owner's account only, rate-limited at the router, and never exposes the OAuth token past grok-bridge on localhost. It's the right call for a single-user tool built for personal use — just not something that would scale to "let anyone sign up and use AI features."