# Grok Bot 0.18 Reconstructed Documentation
> Technical documentation for the unofficial Grok Bot 0.18 reconstruction: pinned bootstrap, reconstructed Electron/host/coordinator runtimes, inference routing, local Docker sandbox, and macOS packaging.
## Context Links
- [Agent index](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/llms.txt)
- [Human interactive docs](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15)
- [GitHub repository](https://github.com/sashimikun/grok-bot-0.18-reconstructed)
## Repository Metadata
- Repository: sashimikun/grok-bot-0.18-reconstructed
- Generated: 2026-08-24T05:59:56.688Z
- Updated: 2026-08-24T06:02:19.192Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 26
## Page Index
- 01. [Overview](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/01-overview.md) - What this reconstruction exposes, who can run it, the hybrid runtime split, and the first docs routes after clone.
- 02. [Installation](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/02-installation.md) - macOS Apple Silicon prerequisites, Node 26.5.x, Git LFS, Xcode tools, optional Docker, and npm ci.
- 03. [Quickstart](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/03-quickstart.md) - Clone, LFS pull, bootstrap, check, package, and open dist/Grok Bot 0.18 Reconstructed.app with the expected success signal.
- 04. [Reconstruction boundary](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/04-reconstruction-boundary.md) - Compiled source/ runtimes, checksum-pinned shipped renderer, reconstructed bundle id com.anysphere.sand.reconstructed, and ignored src/app/dist hydration.
- 05. [Inference router](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/05-inference-router.md) - SandInferenceProvider ids cursor, claude-code, codex, openrouter; default cursor; local transcript store schemaVersion 2; usage schemaVersion 1.
- 06. [Box runtime](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/06-box-runtime.md) - SandBoxRuntime remote versus local-docker, default remote, coordinator restart on switch, and loopback-only local gateway ownership.
- 07. [Evidence and provenance](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/07-evidence-and-provenance.md) - Pinned 0.18.0 DMG and app.asar SHA-256 identities, evidence-only UI rule, and production bindings that must resolve into source/.
- 08. [Choose an inference provider](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/08-choose-an-inference-provider.md) - Set Settings → Router, persist inferenceProvider, and satisfy Cursor session, Claude Code login, Codex auth.json, or OPENROUTER_API_KEY.
- 09. [Enable the local Docker sandbox](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/09-enable-the-local-docker-sandbox.md) - Toggle Use local Docker VM, start grok-bot-local-vm, wait for http://127.0.0.1:1340/health, and roll back to remote on start failure.
- 10. [Route Grok Bot plugin tools](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/10-route-grok-bot-plugin-tools.md) - listRoutedMcpTools and executeRoutedMcpTool across Claude Code MCP bridge versus Codex/OpenRouter direct tool execution.
- 11. [Bootstrap the pinned runtime](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/11-bootstrap-the-pinned-runtime.md) - npm run bootstrap order: GROK_BOT_018_APP, cached app, LFS DMG, then public URL; verify DMG and app.asar SHA-256; hydrate src/app/dist.
- 12. [Package the macOS app](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/12-package-the-macos-app.md) - npm run package compiles runtimes, patches Settings Router, replaces app.asar, sets reconstructed identity, ad-hoc signs, and verifies.
- 13. [Work on the frontend reconstruction](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/13-work-on-the-frontend-reconstruction.md) - frontend/ is a Vite design workspace; packaged UI stays the patched shipped renderer unless GROK_BOT_RENDERER_SOURCE overrides it.
- 14. [npm scripts](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/14-npm-scripts.md) - Exact package.json commands: bootstrap, check, package, verify, smoke, publication:check, frontend:build, and test globs.
- 15. [Settings schema](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/15-settings-schema.md) - settings.json version 1 fields: inferenceProvider, inferenceRouterUsage, boxRuntime, MCP instruction maps, and atomic persist path.
- 16. [Environment variables](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/16-environment-variables.md) - GROK_BOT_018_APP, GROK_BOT_OUTPUT_APP_NAME, SAND_DISABLE_*, OPENROUTER_API_KEY, SAND_OPENROUTER_MODEL, CODEX_HOME, CLAUDE_CODE_PATH, and binding-manifest overrides.
- 17. [Desktop RPC](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/17-desktop-rpc.md) - window.desktop.agent getInferenceRouter, setInferenceRouter, getBoxRuntime, setBoxRuntime, and secrets upsert/list channels.
- 18. [Local Docker connector](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/18-local-docker-connector.md) - Image, container name, owner label, schema version 6, loopback gateway URL, health probe, and content-addressed host-main.cjs mounts.
- 19. [Provider clients](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/19-provider-clients.md) - Cursor default path, Claude Agent SDK query, Codex Responses at chatgpt.com/backend-api/codex/responses, OpenRouter OpenAI-compatible model default openai/gpt-5.2.
- 20. [Bootstrap failures](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/20-bootstrap-failures.md) - LFS pointer-sized archives, DMG checksum mismatch, missing app.asar files, GROK_BOT_018_APP version mismatch, and hydration checksum errors.
- 21. [Packaging failures](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/21-packaging-failures.md) - Non-darwin package abort, missing renderer patch anchors, ad-hoc codesign retry, xattr quarantine, and verify required ASAR entries.
- 22. [Router and sandbox failures](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/22-router-and-sandbox-failures.md) - Unknown provider, Codex private auth.json, Claude Code not installed, missing OPENROUTER_API_KEY, and unowned grok-bot-local-vm container.
- 23. [Verify and smoke](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/23-verify-and-smoke.md) - npm run verify required ASAR paths and evidence markers; npm run smoke native e2e with 12s timeout; updater guard SAND_DISABLE_* defaults.
- 24. [Preserve original installers](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/24-preserve-original-installers.md) - Git LFS 0.18.0 macOS DMG and Windows setup.exe identities, artifacts.json schemaVersion 1, and shasum -c SHA256SUMS.
- 25. [Publication export](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/25-publication-export.md) - npm run publication:check archive/init/add tree equality, LFS push of installers, and NOTICE/rights review before a public remote.
- 26. [Contributing](https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/26-contributing.md) - Required check and package commands, no generated payloads in Git, do not weaken checksum or signing gates, private security reports.
## Source File Index
- `CONTRIBUTING.md`
- `docs/ARCHITECTURE.md`
- `docs/PUBLISHING.md`
- `frontend/README.md`
- `frontend/src/recovered/features/settings/overlay/router.ts`
- `frontend/src/recovered/features/settings/overlay/view.tsx`
- `frontend/vite.config.ts`
- `manifests/reconstruction/electron-main-production-bindings-manifest.json`
- `NOTICE.md`
- `package.json`
- `PROVENANCE.md`
- `README.md`
- `research-archives/original/0.18.0/artifacts.json`
- `research-archives/original/0.18.0/SHA256SUMS`
- `research-archives/README.md`
- `scripts/apply-third-party-patches.mjs`
- `scripts/audit-ui-provenance.mjs`
- `scripts/bootstrap-runtime.mjs`
- `scripts/build-box-exec-daemon.mjs`
- `scripts/build.mjs`
- `scripts/clean-build.mjs`
- `scripts/lib/build-asar.mjs`
- `scripts/lib/codesign.mjs`
- `scripts/lib/config.mjs`
- `scripts/lib/macos-package-verification.mjs`
- `scripts/lib/router-renderer-patch.mjs`
- `scripts/lib/runtime.mjs`
- `scripts/lib/system-tools.mjs`
- `scripts/native-e2e-check.mjs`
- `scripts/package-macos.mjs`
- `scripts/recover-frontend.mjs`
- `scripts/smoke.mjs`
- `scripts/verify-publication-tree.mjs`
- `scripts/verify.mjs`
- `SECURITY.md`
- `source/box-exec-daemon/main.ts`
- `source/electron-main/box/box-host-connector.ts`
- `source/electron-main/box/local-docker-host-connector.ts`
- `source/electron-main/coordinator/coordinator-executors.ts`
- `source/electron-main/main-edge.ts`
- `source/electron-main/main.ts`
- `source/electron-main/secrets/secrets-ipc.ts`
- `source/electron-preload/main-rpc-runtime.ts`
- `source/electron-preload/preload.ts`
- `source/host/extensions/inference/codex-direct-responses.ts`
- `source/host/extensions/inference/cursor-session.ts`
- `source/host/extensions/inference/provider-session.ts`
- `source/host/extensions/mcp/mcp-service.ts`
- `source/host/extensions/settings/settings-service.ts`
- `source/host/main.ts`
- `source/node-agent-coordinator/inference-router.ts`
- `source/node-agent-coordinator/main.ts`
- `source/node-agent-coordinator/routed-mcp-bridge.ts`
- `source/shared/box-runtime.ts`
- `source/shared/host-settings.ts`
- `source/shared/inference-router.ts`
- `source/shared/local-tool-permission.ts`
- `source/shared/node/inference-router-local.ts`
- `source/shared/node/settings/sand-settings-store.ts`
- `source/shared/rpc/coordinator.ts`
- `source/shared/rpc/main.ts`
- `src/app/package.json`
- `tests/backend-mcp-exec-json.test.mjs`
- `tests/codex-direct-responses.test.mjs`
- `tests/inference-router-transcript.test.mjs`
- `tests/publication-bootstrap.test.mjs`
- `tests/publication-packaging.test.mjs`
- `tests/reconstructed-updater-guard.test.mjs`
- `tests/research-archives.test.mjs`
- `tests/router-settings.test.mjs`
---
## 01. Overview
> What this reconstruction exposes, who can run it, the hybrid runtime split, and the first docs routes after clone.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/01-overview.md
- Generated: 2026-08-24T05:50:51.653Z
### Source Files
- `README.md`
- `package.json`
- `docs/ARCHITECTURE.md`
- `source/electron-main/main.ts`
- `source/host/main.ts`
- `source/node-agent-coordinator/main.ts`
---
title: "Overview"
description: "What this reconstruction exposes, who can run it, the hybrid runtime split, and the first docs routes after clone."
---
`grok-bot-0.18-reconstructed` (`0.18.0-reconstructed.1`) is an unofficial, source-oriented reconstruction of the public Grok Bot **0.18.0** macOS arm64 app. Readable TypeScript under `source/` is compiled into the packaged Electron main, host, coordinator, and local-exec runtimes. The polished UI stays the checksum-pinned shipped renderer, plus a narrow Settings → Router patch. Output is a separately identified, ad-hoc signed bundle: `dist/Grok Bot 0.18 Reconstructed.app` with bundle id `com.anysphere.sand.reconstructed`. The upstream install on disk is never overwritten.
This is a research reconstruction of a compiled product, not Anysphere's original monorepo and not an official Grok Bot release. No upstream source-code license is implied. Complete an independent rights review before any public redistribution.
## Who can run it
Packaging and launch target **macOS on Apple Silicon** only. `npm run package` aborts on non-`darwin` hosts. The Windows x64 `0.18.0` installer is preserved for research identity; it is not a packaging path.
| Requirement | Constraint |
| --- | --- |
| OS / CPU | macOS, Apple Silicon |
| Node | `>=26.5.0 <27` (26.5.x) |
| Native toolchain | Xcode Command Line Tools |
| Git | Git LFS (`git lfs pull` for the pinned DMG) |
| Docker | Optional; required only for `boxRuntime: "local-docker"` |
| Cursor route | Existing Grok Bot / Cursor session |
| Claude Code route | Local Claude Code install and login |
| Codex route | Local ChatGPT / Codex `auth.json` |
| OpenRouter route | `OPENROUTER_API_KEY` (Settings → Router or env) |
`npm run check` (typecheck + `tests/*.test.mjs`) can run without packaging. A working reconstructed app still needs `npm run bootstrap` then `npm run package` on Darwin.
## What this reconstruction exposes
Reconstruction plus a small set of control-plane experiments wired through Settings → Router (`window.desktop.agent`):
| Surface | Default | Persist / store |
| --- | --- | --- |
| `SandInferenceProvider` ids `cursor`, `claude-code`, `codex`, `openrouter` | `cursor` | `settings.json` field `inferenceProvider` |
| Local routed usage (`schemaVersion: 1`) | empty per-provider counters | `inferenceRouterUsage` |
| Routed transcript store | `{ schemaVersion: 2, agents: {} }` | `inference-router-transcript.json` |
| `SandBoxRuntime` `remote` \| `local-docker` | `remote` | `boxRuntime` |
| Grok Bot plugin / MCP tools on non-Cursor routes | coordinator intercept | `listRoutedMcpTools` / `executeRoutedMcpTool` |
Cursor keeps the native Grok Bot inference path. `claude-code`, `codex`, and `openrouter` are handled by `createCoordinatorInferenceRouter` in `source/node-agent-coordinator` before the remote gateway. Usage totals in Settings → Usage & Billing are local activity records, not provider invoices.
The Router page also owns **Use local Docker VM**. Enabling `local-docker` starts owned container `grok-bot-local-vm` (loopback gateway `http://127.0.0.1:1340/health`), then restarts the coordinator. Start failure rolls `boxRuntime` back to `remote`.
## Hybrid runtime split
The packaged app is a hybrid by design: compiled reconstruction for control-plane binaries, pinned 0.18.0 renderer for UI, reconstructed identity for the bundle.
```mermaid
flowchart TB
subgraph ui [Packaged UI]
Renderer["Checksum-pinned shipped renderer"]
Patch["Deterministic Settings → Router patch"]
Frontend["frontend/ Vite workspace — not the packaged UI"]
end
subgraph desktop [Desktop process]
Preload["source/electron-preload"]
Main["source/electron-main startElectronMain"]
Settings["settings.json version 1"]
Secrets["desktop secrets upsert / list"]
end
subgraph control [Coordinator and host]
Coord["source/node-agent-coordinator composeCoordinator"]
Host["source/host main / production SandHost"]
Router["createCoordinatorInferenceRouter"]
end
subgraph providers [SandInferenceProvider]
Cursor["cursor — native path"]
Claude["claude-code"]
Codex["codex"]
OpenRouter["openrouter"]
end
subgraph box [SandBoxRuntime]
Remote["remote — default"]
Docker["local-docker grok-bot-local-vm :1340"]
end
Frontend -.->|"GROK_BOT_RENDERER_SOURCE override only"| Renderer
Renderer --> Patch
Patch --> Preload
Preload --> Main
Main --> Settings
Main --> Secrets
Main --> Coord
Coord --> Host
Coord --> Router
Router --> Cursor
Router --> Claude
Router --> Codex
Router --> OpenRouter
Main --> Remote
Main --> Docker
Host --> Remote
Host --> Docker
```
### Compiled from `source/`
| Tree | Role in the packaged app |
| --- | --- |
| `source/electron-main/` | Window lifecycle, settings/secrets/auth, box connectors, coordinator ownership, RPC (`getInferenceRouter`, `setInferenceRouter`, `getBoxRuntime`, `setBoxRuntime`) |
| `source/electron-preload/` | Trusted bridge to the renderer (`window.desktop.*`) |
| `source/host/` | Turn execution, tools/MCP, settings service, gateway; `main()` is either fail-closed `--box-copy-in` or the long-lived host + gateway |
| `source/node-agent-coordinator/` | Carrier adopt, gateway SSE, transcript/activity, routed MCP bridge, inference router intercept of `sendPrompt` |
| `source/shared/` | `SandInferenceProvider`, `SandBoxRuntime`, `SandSettingsStore` (`SETTINGS_VERSION` 1) |
| `scripts/` | Bootstrap, compile, renderer patch, ASAR replace, ad-hoc sign, verify |
Production binding manifests under `manifests/reconstruction/` must resolve those Electron-main and host ports into `source/`. Bootstrap hydrates ignored `src/app/dist` from the pinned app; that tree is a build input, not authored source.
### Checksum-pinned renderer
The 0.18.0 ASAR did not ship frontend source or source maps. Packaged UI therefore stays the pinned renderer. `scripts/package-macos.mjs` keeps those chunks as the UI authority and installs reconstructed Router UI through a hash-recorded transform (`router` settings tab, provider picker, local Docker toggle, usage rows).
`frontend/` is a Vite design workspace for recovered contracts and clean React. It is **not** the default packaged renderer. `GROK_BOT_RENDERER_SOURCE` can replace `dist/renderer` during ASAR staging; omit it for the patched shipped UI.
### Reconstructed identity
| Identity | Value |
| --- | --- |
| Upstream product | Grok Bot 0.18.0, bundle id `com.anysphere.sand`, Electron 42.1.0 |
| Reconstructed display name | `Grok Bot 0.18 Reconstructed` |
| Reconstructed bundle id | `com.anysphere.sand.reconstructed` |
| Output path | `dist/Grok Bot 0.18 Reconstructed.app` (`GROK_BOT_OUTPUT_APP_NAME` overrides the basename) |
| Signature | Ad-hoc only; upstream Developer ID / notarization is not reused |
| Updater / telemetry defaults at pack | `SAND_DISABLE_UPDATES`, `SAND_DISABLE_SENTRY`, `SAND_DISABLE_TELEMETRY` default to `"1"` if unset |
Pinned artifact identities:
| Artifact | SHA-256 |
| --- | --- |
| `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg` | `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| Original `app.asar` | `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58` |
| Windows x64 `Grok_Bot_0.18.0_Setup.exe` (LFS preserve only) | `464079a15ef5fa8b61ccea8fffcc78f63cfcf6df65fb0ad5e725d8b95f7e437e` |
Evidence-only UI rule: do not invent screens, labels, or interactions to fill an evidence gap. Incomplete renderer mapping stays unmapped.
## First path after clone
Node 26.5.x, Xcode Command Line Tools, Git LFS. Docker only if you will toggle local-docker.
```sh
git clone
cd grok-bot-0.18-reconstructed
git lfs install
git lfs pull
npm ci
```
```sh
npm run bootstrap
```
Resolution order: `GROK_BOT_018_APP` → cached `.cache/runtime/Grok Bot.app` → Git LFS DMG → public URL `https://downloads.cursor.com/grokbot/stable/darwin-arm64/0.18.0/Grok_Bot_0.18.0.dmg`. Bootstrap verifies DMG and `app.asar` SHA-256 and hydrates ignored `src/app/dist`.
Expected log fragment:
```text
Runtime ready: .../.cache/runtime/Grok Bot.app
Checksum-pinned source payload ready: .../src/app/dist (...)
```
```sh
npm run check
npm run package
open "dist/Grok Bot 0.18 Reconstructed.app"
```
`package` compiles runtimes, patches Router settings, replaces `app.asar`, sets `com.anysphere.sand.reconstructed`, ad-hoc signs, and verifies. Success includes:
```text
Packaged application: .../dist/Grok Bot 0.18 Reconstructed.app (...)
```
Optional: `npm run verify` on an existing bundle; `npm run smoke` native e2e with a 12s timeout (`Smoke verification: PASS`).
:::files
repository
├── source/ compiled Electron / host / coordinator / shared
├── frontend/ Vite design workspace (not default packaged UI)
├── scripts/ bootstrap, compile, patch, package, verify
├── manifests/reconstruction/ production bindings that must resolve into source/
├── research-archives/original/0.18.0/ Git LFS 0.18.0 DMG + Windows setup
├── src/app/dist/ ignored; hydrated by bootstrap
├── dist/ ignored; packaged reconstructed .app
└── tests/ publication, router, bootstrap, smoke regressions
:::
Ignored generated trees also include `.cache`, `.build`, `recovered`, and `recovery`. Do not commit them.
## Commands that define the product loop
| Script | What it does |
| --- | --- |
| `npm run bootstrap` | Pin and hydrate the 0.18.0 Electron shell + `src/app/dist` |
| `npm run check` | `typecheck` + `source:typecheck` + `npm test` |
| `npm run package` | `check` then Darwin package / sign / verify |
| `npm run verify` | Required ASAR paths and evidence markers |
| `npm run smoke` | Native e2e against `dist/Grok Bot 0.18 Reconstructed.app` |
| `npm run publication:check` | Clean-export tree equality before a public remote |
| `npm run frontend:build` | Vite build of the design workspace |
## Next
macOS Apple Silicon prerequisites, Node 26.5.x, Git LFS, Xcode tools, optional Docker, and npm ci.
Clone, LFS pull, bootstrap, check, package, and open the reconstructed app with the expected success signal.
Compiled `source/` runtimes, checksum-pinned shipped renderer, bundle id `com.anysphere.sand.reconstructed`, ignored `src/app/dist`.
Provider ids, default `cursor`, transcript `schemaVersion` 2, usage `schemaVersion` 1.
`remote` vs `local-docker`, coordinator restart on switch, loopback-only local gateway.
Pinned DMG and `app.asar` SHA-256 identities, evidence-only UI rule, production bindings.
---
## 02. Installation
> macOS Apple Silicon prerequisites, Node 26.5.x, Git LFS, Xcode tools, optional Docker, and npm ci.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/02-installation.md
- Generated: 2026-08-24T05:53:49.074Z
### Source Files
- `package.json`
- `README.md`
- `scripts/lib/system-tools.mjs`
- `scripts/lib/config.mjs`
- `research-archives/README.md`
- `scripts/apply-third-party-patches.mjs`
---
title: "Installation"
description: "macOS Apple Silicon prerequisites, Node 26.5.x, Git LFS, Xcode tools, optional Docker, and npm ci."
---
The reconstruction is a Node workspace that installs with `npm ci` from `package-lock.json` (`lockfileVersion` 3) and then hydrates a checksum-pinned 0.18.0 macOS arm64 Electron shell. `package.json` names the package `grok-bot-0.18-reconstructed` at `0.18.0-reconstructed.1`, sets `"type": "module"`, and constrains `engines.node` to `>=26.5.0 <27`. `npm ci` also runs `postinstall` (`node scripts/apply-third-party-patches.mjs`). Packaging (`scripts/package-macos.mjs`) throws if `process.platform !== "darwin"`. The pinned DMG is the Git LFS object `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg` (SHA-256 `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb`).
Do not treat this checkout as a cross-platform app factory. The Windows x64 installer is preserved for research identity only. `npm run package` and `npm run smoke` require Darwin; the official shell is a thin arm64 Mach-O (`0xfeedfacf`).
## Supported host
| Constraint | Value | Enforced by |
| --- | --- | --- |
| OS | macOS (`darwin`) | `scripts/package-macos.mjs`, `scripts/package-fidelity-diagnostic.mjs` |
| CPU | Apple Silicon (`arm64`) | Pinned DMG `darwin-arm64/0.18.0`; Mach-O parser in `scripts/lib/macos-shell-invariant.mjs` |
| Node | `>=26.5.0 <27` | `package.json` `engines.node` |
| Package manager | `npm ci` against the committed lockfile | `package-lock.json`, `CONTRIBUTING.md` |
| Bundle identity after package | `com.anysphere.sand.reconstructed` | `scripts/lib/config.mjs` `reconstructedBundleId` |
| Default output app | `dist/Grok Bot 0.18 Reconstructed.app` | `GROK_BOT_OUTPUT_APP_NAME` override, else `reconstructedName` |
`src/app/package.json` still reports upstream product `sand` / `Grok Bot` `0.18.0`. That file is the hydrated app manifest, not the reconstruction workspace identity.
## Prerequisites
| Tool | Required for | Notes |
| --- | --- | --- |
| Node.js 26.5.x (any `26.5.0`–`<27`) | `npm ci`, tests, TypeScript, scripts | README documents 26.5.x; `engines` is the hard range |
| Git LFS | `research-archives/original/**/*.dmg` and `*.exe` | `.gitattributes` `filter=lfs` |
| Xcode Command Line Tools | bootstrap attach, ad-hoc sign, `plutil`, `node-gyp` | Absolute tool paths in `scripts/lib/system-tools.mjs` |
| Docker CLI + a running daemon | optional local box (`local-docker`) | Default box runtime stays `remote` |
| Cursor / Claude Code / Codex / OpenRouter auth | routed inference after launch | Not part of `npm ci` |
Provider sessions are runtime credentials, not install-time packages. Cursor is the default inference provider. Claude Code and Codex reuse existing local logins; OpenRouter needs `OPENROUTER_API_KEY` later.
## Install Node 26.5.x
Confirm the host interpreter before `npm ci`:
```sh
node -v
# expected: v26.5.x (engines: >=26.5.0 <27)
```
`@types/node` is pinned at `26.2.0`. Electron `42.1.0` is a `devDependency` (headers/ABI 146, Electron Node `24.15.0` for native rebuilds). Host Node 26 and the Electron runtime Node 24 are different processes; do not swap the workspace interpreter to 24 to match Electron.
## Xcode Command Line Tools
Bootstrap, package, and verify spawn Apple binaries by absolute path (`shell: false` in `scripts/lib/process.mjs`). Those binaries come from Xcode Command Line Tools:
| Constant | Path | Used for |
| --- | --- | --- |
| `hdiutil` | `/usr/bin/hdiutil` | Attach/detach the 0.18.0 DMG during `npm run bootstrap` |
| `ditto` | `/usr/bin/ditto` | Copy `Grok Bot.app` into `.cache/runtime/` and `dist/` |
| `plutil` | `/usr/bin/plutil` | Read/write `Info.plist` (`CFBundleIdentifier`, URL types, version) |
| `codesign` | `/usr/bin/codesign` | Ad-hoc sign (`--sign -`) and `--verify --deep --strict` |
| `xattr` | `/usr/bin/xattr` | `xattr -cr` on the reconstructed `.app` (clear quarantine) |
| `cp` / `lsof` / `ps` | `/bin/cp`, `/usr/sbin/lsof`, `/bin/ps` | Copy and native smoke/process inspection |
`node-gyp@12.1.0` and `node-addon-api@8.5.0` are workspace `devDependencies`. `postinstall` rewrites `node_modules/tree-sitter/binding.gyp` so Node ≥ 22 uses C++20 (`cxxstd`). Packaging stages tree-sitter via `scripts/build-tree-sitter-node.mjs`. Missing CLT shows up as `hdiutil`/`codesign`/`node-gyp` spawn failures, not as a custom Node error.
If `/usr/bin/hdiutil` or `/usr/bin/codesign` is missing:
```sh
xcode-select --install
xcode-select -p
```
## Git LFS
`.gitattributes` tracks:
```text
research-archives/original/**/*.dmg filter=lfs diff=lfs merge=lfs -text
research-archives/original/**/*.exe filter=lfs diff=lfs merge=lfs -text
```
`artifacts.json` (`schemaVersion` 1) is the size/digest inventory. A pointer-sized file fails `tests/research-archives.test.mjs` with `requires git lfs pull` because `lstat` size must equal `artifact.bytes`.
| Artifact | Bytes | SHA-256 |
| --- | ---: | --- |
| `macos-arm64/Grok_Bot_0.18.0.dmg` | 155793020 | `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| `windows-x64/Grok_Bot_0.18.0_Setup.exe` | 125825552 | `464079a15ef5fa8b61ccea8fffcc78f63cfcf6df65fb0ad5e725d8b95f7e437e` |
If the archived DMG is present but the digest is wrong, `scripts/bootstrap-runtime.mjs` throws `Archived DMG checksum mismatch … Run git lfs pull before bootstrapping.`
## npm ci
`npm ci` is the supported install. It materializes `node_modules/` from `package-lock.json` and sets `hasInstallScript: true`.
`postinstall` / `npm run native:patch` patches only stock SHA-256 inputs:
| Target | Purpose |
| --- | --- |
| `@connectrpc/connect` ESM + CJS `protocol-connect/transport.js` | Set `Content-Length: 0` on empty request bodies |
| `tree-sitter/binding.gyp` | Select C++17 vs C++20 from `npm_config_target` / `process.versions.node` |
Unexpected bytes abort: `Refusing to patch unexpected @connectrpc/connect input …`. Already-patched files are skipped (`patchedSha256`).
Generated trees stay out of Git (`.gitignore`): `node_modules/`, `.cache/`, `.build/`, `dist/`, `src/app/dist/`, `recovered/`.
:::files
repo/
package.json # engines.node >=26.5.0 <27; postinstall
package-lock.json # lockfileVersion 3; npm ci input
scripts/apply-third-party-patches.mjs
scripts/lib/system-tools.mjs
scripts/lib/config.mjs
research-archives/original/0.18.0/
artifacts.json
SHA256SUMS
macos-arm64/Grok_Bot_0.18.0.dmg # Git LFS
windows-x64/Grok_Bot_0.18.0_Setup.exe
src/app/ # package.json checked in; dist/ ignored until bootstrap
node_modules/ # created by npm ci
.cache/runtime/Grok Bot.app # created by bootstrap
dist/ # created by package
:::
## Optional Docker
Local sandbox is not an install gate. `source/electron-main/box/local-docker-host-connector.ts` shells out to `docker` and probes `docker info`. Constants:
| Name | Value |
| --- | --- |
| `LOCAL_DOCKER_BOX_IMAGE` | `public.ecr.aws/k0i0n2g5/cursorenvironments/universal:sand-box-latest` |
| `LOCAL_DOCKER_BOX_CONTAINER` | `grok-bot-local-vm` |
| `LOCAL_DOCKER_GATEWAY_URL` | `http://127.0.0.1:1340` |
| `LOCAL_DOCKER_OWNER_LABEL` | `com.grok-bot.local-vm=1` |
| `LOCAL_DOCKER_SCHEMA_VERSION` | `6` |
If the daemon is down, status is `available: false` with detail `Docker is not running.` or the `docker` spawn error. Default box mode remains `remote`.
## Install the workspace
```sh
git clone
cd grok-bot-0.18-reconstructed
git lfs install
git lfs pull
```
```sh
node -v
uname -m
test -x /usr/bin/hdiutil && test -x /usr/bin/codesign && echo ok
```
`uname -m` must be `arm64`. `node -v` must satisfy `>=26.5.0 <27`.
```sh
npm ci
```
Expect `postinstall` to finish without patch-drift errors. Do not use a floating `npm install` as the documented contributor path.
```sh
(cd research-archives/original/0.18.0 && shasum -a 256 -c SHA256SUMS)
```
Both lines must print `OK`. Optional: `git lfs ls-files` should list both installers.
Optional absolute path to an already-extracted `Grok Bot.app`. When set, bootstrap copies that app with `ditto` instead of attaching the DMG. `CFBundleShortVersionString` must be `0.18.0`.
Optional basename for the packaged app under `dist/`. Default is `Grok Bot 0.18 Reconstructed.app`.
Installation stops at a complete `node_modules/` plus real LFS binaries. Hydrating `src/app/dist` is `npm run bootstrap`. Compiling runtimes and writing the `.app` is `npm run package`.
## Verification
A successful install has Node in range, `npm ci` exit 0, Connect/tree-sitter patches applied, and both research-archive checksums matching `SHA256SUMS`.
```sh
node -e "const e=require('./package.json').engines.node; console.log(process.version, e)"
npm ci
(cd research-archives/original/0.18.0 && shasum -a 256 -c SHA256SUMS)
```
`npm run check` (`typecheck` + `source:typecheck` + `node --test tests/*.test.mjs`) can run after `npm ci` without packaging. The archives test still requires pulled LFS objects.
Contributor minimum after install (from `CONTRIBUTING.md`):
```sh
npm ci
npm run check
npm run frontend:build
```
On macOS, after bootstrap:
```sh
npm run package
npm run verify
```
## Install failures
| Symptom | Cause | Fix |
| --- | --- | --- |
| `engines` / unexpected Node | Interpreter outside `>=26.5.0 <27` | Install Node 26.5.x |
| DMG tens of kilobytes; test `requires git lfs pull` | LFS pointer, not the 155 793 020-byte object | `git lfs install && git lfs pull` |
| `Archived DMG checksum mismatch` | Corrupt or pointer archive | `git lfs pull`, then `shasum -c SHA256SUMS` |
| `Refusing to patch unexpected @connectrpc/connect input` | `node_modules` not lockfile-stock | Delete `node_modules` and re-run `npm ci` |
| `The reconstructed macOS application can only be packaged on macOS.` | `process.platform !== "darwin"` | Use Apple Silicon macOS for package/smoke |
| `Expected Grok Bot 0.18.0, got …` | `GROK_BOT_018_APP` is the wrong app version | Point at 0.18.0 or unset and use the LFS DMG |
| `hdiutil` / `codesign` exited non-zero | Missing CLT or Gatekeeper tool path | `xcode-select --install` |
| `Docker is not running.` | Optional daemon down | Ignore unless enabling local Docker VM |
Do not weaken checksum, bundle-id, or signing checks to get a green install. Those gates are required contributor policy.
## Next
Clone through `npm run package` and open `dist/Grok Bot 0.18 Reconstructed.app`.
`GROK_BOT_018_APP`, cached app, LFS DMG, then public URL; hydrate `src/app/dist`.
LFS identities, `artifacts.json` schemaVersion 1, and `shasum -c SHA256SUMS`.
Optional `grok-bot-local-vm` after Docker is installed and running.
Exact `package.json` commands after `npm ci`.
Pointer-sized archives, checksum mismatch, and hydration errors.
---
## 03. Quickstart
> Clone, LFS pull, bootstrap, check, package, and open dist/Grok Bot 0.18 Reconstructed.app with the expected success signal.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/03-quickstart.md
- Generated: 2026-08-24T05:51:26.446Z
### Source Files
- `README.md`
- `package.json`
- `scripts/bootstrap-runtime.mjs`
- `scripts/package-macos.mjs`
- `scripts/verify.mjs`
- `scripts/lib/config.mjs`
---
title: "Quickstart"
description: "Clone, LFS pull, bootstrap, check, package, and open dist/Grok Bot 0.18 Reconstructed.app with the expected success signal."
---
`npm run bootstrap` then `npm run package` is the supported path from a clone to a launchable macOS app. Bootstrap resolves a checksum-pinned Grok Bot **0.18.0** runtime, hydrates ignored `src/app/dist`, and caches `.cache/runtime/Grok Bot.app`. Package compiles reviewed `source/` runtimes, copies that Electron shell, replaces `app.asar`, sets bundle id `com.anysphere.sand.reconstructed`, ad-hoc signs, and writes `dist/Grok Bot 0.18 Reconstructed.app`. The installed upstream Grok Bot.app is never overwritten.
Packaging aborts unless `process.platform === "darwin"`. The pinned installer is macOS arm64. Node must satisfy `>=26.5.0 <27`.
## Prerequisites
| Requirement | Constraint |
| --- | --- |
| Host | macOS on Apple Silicon |
| Node | `package.json` `engines.node`: `>=26.5.0 <27` |
| Git LFS | Required for `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg` |
| Xcode CLT | Native compile during package (`node-gyp`, tree-sitter, codesign, `hdiutil`, `ditto`, `plutil`, `xattr`) |
| Docker | Optional. First launch defaults `boxRuntime` to `remote` |
Full host setup lives on [Installation](/installation). Docker is only required if you later enable the local sandbox.
## Clone and LFS
```sh
git clone https://github.com/sashimikun/grok-bot-0.18-reconstructed.git
cd grok-bot-0.18-reconstructed
```
```sh
git lfs install
git lfs pull
```
The macOS pin is `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg` at **155,793,020** bytes, SHA-256 `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb`.
```sh
cd research-archives/original/0.18.0 && shasum -a 256 -c SHA256SUMS
```
If `lstat` size is not the pinned byte count, the file is still an LFS pointer. Bootstrap then fails with `Archived DMG checksum mismatch: expected a253ccd8… Run git lfs pull before bootstrapping.`
```sh
npm ci
```
`postinstall` applies third-party patches. Do not commit `.cache/`, `.build/`, `dist/`, or `src/app/dist/`.
## Bootstrap the pinned runtime
```sh
npm run bootstrap
```
This is `node scripts/bootstrap-runtime.mjs`. Resolution order:
```mermaid
flowchart TD
subgraph operator [Operator and archive inputs]
env["GROK_BOT_018_APP"]
lfsDmg["research-archives/.../Grok_Bot_0.18.0.dmg"]
publicUrl["downloads.cursor.com/.../0.18.0/Grok_Bot_0.18.0.dmg"]
end
subgraph cache [Local cache]
cachedApp[".cache/runtime/Grok Bot.app"]
cachedDmg[".cache/downloads/Grok_Bot_0.18.0.dmg"]
end
subgraph hydrate [Checksum-pinned payload]
asar["Contents/Resources/app.asar"]
dest["src/app/dist"]
end
env -->|version must be 0.18.0| cachedApp
cachedApp -->|if already valid| asar
lfsDmg -->|SHA-256 a253ccd8…| cachedDmg
publicUrl -->|fallback fetch| cachedDmg
cachedDmg -->|hdiutil attach Grok Bot.app| cachedApp
asar -->|SHA-256 66654081…| dest
```
| Priority | Source | Gate |
| --- | --- | --- |
| 1 | `GROK_BOT_018_APP` | `CFBundleShortVersionString` must be `0.18.0`; `Contents/MacOS/Grok Bot` and `app.asar.unpacked` must exist |
| 2 | `.cache/runtime/Grok Bot.app` | Same version/completeness check |
| 3 | LFS DMG → `.cache/downloads/Grok_Bot_0.18.0.dmg` | SHA-256 `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| 4 | Public URL `dmgUrl` | Same DMG SHA-256 after download |
Hydration extracts `app.asar` only when its SHA-256 is `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58`, and requires `dist/electron-main/main.cjs`, `dist/host/host-main.cjs`, and `dist/renderer/index.html`.
Absolute path to an existing 0.18.0 `Grok Bot.app`. Skips DMG attach. Still hydrates `src/app/dist` from that app’s `app.asar`.
```text
Using archived release …/research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg
Runtime ready: …/.cache/runtime/Grok Bot.app
Checksum-pinned source payload ready: …/src/app/dist (6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58)
The checksum-pinned app supplies only the Electron shell, ABI-matched native dependencies, and explicitly documented build fallbacks.
```
A later `npm run bootstrap` reuses `.cache/runtime/Grok Bot.app` when it still validates as 0.18.0.
## Check, package, and open
`npm run package` already runs `npm run check` (`typecheck` + `source:typecheck` + `node --test tests/*.test.mjs`). You can run check alone to fail faster.
```sh
npm run check
npm run package
open "dist/Grok Bot 0.18 Reconstructed.app"
```
`npm run package` is `npm run check && node scripts/package-macos.mjs`. That script:
1. Builds the reconstructed ASAR from `source/` plus the checksum-pinned renderer baseline.
2. Copies `.cache/runtime/Grok Bot.app` into `dist/` with `ditto`.
3. Clears quarantine with `xattr -cr` so Gatekeeper does not reject the ad-hoc signature.
4. Replaces `Contents/Resources/app.asar` and `app.asar.unpacked`.
5. Sets `CFBundleIdentifier` to `com.anysphere.sand.reconstructed` and `CFBundleDisplayName` to `Grok Bot 0.18 Reconstructed`.
6. Registers URL scheme `sand` only (inherited aliases such as `grokbot` are removed).
7. Ad-hoc signs, retries once on nested-framework signature races, then `codesign --verify --deep --strict`.
Optional basename under `dist/`. Default output is `dist/Grok Bot 0.18 Reconstructed.app`.
```text
Packaged application: …/dist/Grok Bot 0.18 Reconstructed.app (N native manifest entries, M unpacked runtime files)
```
That `Packaged application:` line is the packaging success signal. `open` then launches the reconstructed bundle, not the original `/Applications` install.
:::files
repo/
research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg # Git LFS pin
.cache/downloads/Grok_Bot_0.18.0.dmg # verified DMG cache
.cache/runtime/Grok Bot.app # ABI-matched Electron shell
src/app/dist/ # hydrated, gitignored
dist/Grok Bot 0.18 Reconstructed.app # launchable output
Contents/Info.plist # com.anysphere.sand.reconstructed
Contents/Resources/app.asar # reconstructed payload
:::
## Optional verify and smoke
These are not required to open the app. `package` already runs an internal reconstructed-package audit.
| Command | What it proves | Success signal |
| --- | --- | --- |
| `npm run verify` | Required ASAR entries, evidence markers (≥1,000 `// src/` lines in hydrated mains), renderer provenance, bundle id, `sand` URL scheme, codesign | `Verified packaged ASAR …` then `Verified N executable clean-source runtimes…` |
| `npm run smoke` | Native e2e against `outputApp`, 12s timeout, isolated user-data dirs, `SAND_DISABLE_UPDATES/TELEMETRY/ANALYTICS=1` | `Smoke verification: PASS` (exit 0). Non-darwin is `prerequisite` (exit 2) |
```sh
npm run verify
npm run smoke
```
`npm run verify -- --app /absolute/path/to/App.app` retargets the audit. Packaged electron-main injects `SAND_DISABLE_UPDATES ??= "1"`, `SAND_DISABLE_SENTRY ??= "1"`, and `SAND_DISABLE_TELEMETRY ??= "1"`; explicit env still wins.
## First launch defaults
The reconstructed app is a hybrid: runtimes from `source/`, UI from the checksum-pinned shipped renderer plus a narrow Settings → Router patch. `frontend/` is a Vite design workspace and is **not** the packaged renderer unless you override that on a later build.
| Surface | Default | Notes |
| --- | --- | --- |
| Inference | `inferenceProvider` `cursor` | Other ids: `claude-code`, `codex`, `openrouter`. Cursor uses the existing Grok Bot/Cursor session |
| Box | `boxRuntime` `remote` | Local Docker is opt-in; leave it off for first launch |
| Identity | `com.anysphere.sand.reconstructed` | Ad-hoc signed; CFBundleName/executable stay `Grok Bot` for helper ABI match |
| Deep link | scheme `sand` | Auth callback target for the reconstructed bundle |
Open **Settings → Router** after launch. Cursor needs no extra key. Claude Code, Codex, and OpenRouter require their own local login or `OPENROUTER_API_KEY` before those providers work.
## Command map
| Script | Implementation | Role in this path |
| --- | --- | --- |
| `npm run bootstrap` | `scripts/bootstrap-runtime.mjs` | Pin, extract, hydrate |
| `npm run check` | frontend + `source/` `tsc`, then `tests/*.test.mjs` | Required gate |
| `npm run package` | `check` then `scripts/package-macos.mjs` | Produce the `.app` |
| `npm run verify` | `scripts/verify.mjs` | Re-audit an existing bundle |
| `npm run smoke` | `scripts/smoke.mjs` | Bounded native launch |
## Quick failure map
| Symptom | Likely cause |
| --- | --- |
| `Archived DMG checksum mismatch` | LFS pointer, not the 155,793,020-byte DMG |
| `DMG checksum mismatch` after download | Public file does not match `dmgSha256` |
| `Expected Grok Bot 0.18.0, got …` | `GROK_BOT_018_APP` or cache is the wrong version |
| `Upstream app.asar checksum mismatch` | Hydration pin `66654081…` failed |
| `Upstream app.asar is missing dist/…` | Incomplete asar |
| `The reconstructed macOS application can only be packaged on macOS.` | Non-darwin `npm run package` |
| Gatekeeper reject of a copied app | Quarantine xattrs; package already runs `xattr -cr` on `outputApp` |
## Next
macOS Apple Silicon, Node 26.5.x, Git LFS, Xcode tools, optional Docker, and `npm ci`.
Full `GROK_BOT_018_APP` / cache / LFS / URL order and SHA-256 gates.
Renderer patch, ASAR replace, reconstructed identity, ad-hoc sign, verify.
Required ASAR paths, evidence markers, 12s native e2e, updater guards.
Settings → Router persistence and Cursor / Claude Code / Codex / OpenRouter auth.
Pointer-sized archives, DMG/asar mismatches, version and hydration errors.
---
## 04. Reconstruction boundary
> Compiled source/ runtimes, checksum-pinned shipped renderer, reconstructed bundle id com.anysphere.sand.reconstructed, and ignored src/app/dist hydration.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/04-reconstruction-boundary.md
- Generated: 2026-08-24T05:51:53.325Z
### Source Files
- `docs/ARCHITECTURE.md`
- `PROVENANCE.md`
- `scripts/lib/config.mjs`
- `scripts/package-macos.mjs`
- `scripts/lib/build-asar.mjs`
- `src/app/package.json`
---
title: "Reconstruction boundary"
description: "Compiled source/ runtimes, checksum-pinned shipped renderer, reconstructed bundle id com.anysphere.sand.reconstructed, and ignored src/app/dist hydration."
---
`npm run package` assembles a **fidelity hybrid** macOS app: reviewed TypeScript under `source/` is compiled into ASAR executables, the UI stays the checksum-pinned 0.18.0 renderer from ignored `src/app/dist/renderer` plus a recorded Settings Router patch, and the finished bundle is identified as `com.anysphere.sand.reconstructed` with an ad-hoc signature. The official 0.18.0 app is a reference-only, SHA-256-pinned input; packaging copies its Electron shell and ABI-matched natives, then replaces `app.asar` so the reconstructed package never ships the official archive or Developer ID signature.
Do not treat reconstructed material as original source or an official Grok Bot build. Upstream bundle ID is `com.anysphere.sand`. Reconstructed builds use `com.anysphere.sand.reconstructed`, ad-hoc signing only, and must not overwrite a machine-installed official app.
## Ownership map
```mermaid
flowchart TB
subgraph tracked["Git-tracked reconstruction"]
SRC["source/ Electron main, host, coordinator, daemons, preloads"]
FE["frontend/ Vite design workspace"]
PKG["src/app/package.json name sand version 0.18.0"]
SCRIPTS["scripts/ bootstrap, compile, patch, package, verify"]
end
subgraph ignored["Ignored hydration"]
DIST["src/app/dist from app.asar SHA-256 66654081…"]
CACHE[".cache/runtime/Grok Bot.app"]
end
subgraph packaged["dist/Grok Bot 0.18 Reconstructed.app"]
SHELL["Electron 42.1.0 shell CFBundleName Grok Bot"]
ASAR["replaced app.asar hybrid runtimes"]
ID["CFBundleIdentifier com.anysphere.sand.reconstructed"]
end
DMG["Pinned 0.18.0 DMG a253ccd8…"] --> CACHE
CACHE --> DIST
DIST --> ASAR
SRC --> ASAR
FE -.->|"not the packaged UI unless GROK_BOT_RENDERER_SOURCE"| ASAR
PKG --> ASAR
SCRIPTS --> packaged
SHELL --> ID
ASAR --> ID
```
Tracked `src/app/package.json` is the app metadata seed (`name`: `sand`, `productName`: `Grok Bot`, `version`: `0.18.0`, `main`: `dist/electron-main/main.cjs`). Generated `src/app/dist/` is gitignored and must be hydrated before compile or package.
## Hybrid runtime split
Default packaging calls `buildFidelityReconstructedAsar()`. Build kind in `dist/reconstruction-build.json` is `fidelity-hybrid-reconstruction`. Renderer mode is `checksum-pinned-artifact-runtime` with artifact root `src/app/dist/renderer`.
| Runtime | Packaged path | Default mode | Source of bytes |
| --- | --- | --- | --- |
| `renderer` | `dist/renderer` | `checksum-pinned-artifact-runtime` | Hydrated shipped UI; Settings Router patch only |
| `electron-main` | `dist/electron-main/main.cjs` | `clean-source` when `manifests/reconstruction/electron-main-production-bindings-manifest.json` validates; else `artifact-fallback` | `source/electron-main/main.ts` or hydrated `main.cjs` plus updater/dev seams |
| `host` | `dist/host/host-main.cjs` | `artifact-fallback` unless `GROK_BOT_HOST_BINDINGS_MANIFEST` binds every required slot into `source/` | `source/host/main.ts` or hydrated `host-main.cjs` |
| `node-agent-coordinator` | `dist/node-agent-coordinator/main.cjs` | `clean-source` | `source/node-agent-coordinator/main.ts` |
| `primary-preload` | `dist/electron-preload/preload.cjs` | `clean-source` | `source/electron-preload/runtime/primary.ts` |
| `dev-controls-preload` / `webview-preload` / `vnc-preload` | matching `preload-*.cjs` | `clean-source` | `source/electron-preload/runtime/` |
| `electron-dev-controls` | `dist/electron-dev-controls/main.cjs` | `clean-source` | `source/electron-dev-controls/main.ts` |
| Host workers | `agent-store-worker.cjs`, `transcript-mirror-worker.cjs`, `box-store-vacuum-worker.cjs`, `search-index-worker.cjs` | `clean-source` | matching `source/host/**` entries |
| `box-exec-daemon` | `dist/box-exec-daemon/main.cjs` | `clean-source` | `source/box-exec-daemon/cli.ts` |
| `local-exec-daemon` | `dist/local-exec-daemon/main.cjs` | `clean-source` | `source/local-exec-daemon/main.ts` |
| `electron-runtime-dependencies` | `dist/deps` | `artifact-runtime` | Unpacked 0.18.0 `app.asar.unpacked/dist/deps` |
| `native-runtime-tools` | `dist/native` | `artifact-runtime` | Unpacked 0.18.0 `dist/native` |
| `node-runtime-dependencies` | `dist/node-deps` | `generated-runtime` | Local Node ABI tree-sitter rebuild |
| `electron-shell` | `Contents/Frameworks/Electron Framework.framework` | `artifact-runtime` | Pinned 0.18.0 `.app` via `ditto` |
Clean overlays replace coordinator, daemons, preloads, workers, and `dist/node-deps`. Fidelity packaging **does not** overlay `dist/renderer` from `frontend/`. Artifact-fallback copies of recovered source land at `dist/recovered-source/electron-main/main.cjs` and `dist/recovered-source/host/host-main.cjs` only while those runtimes stay in fallback mode; a clean activation **removes** that recovered-source entry.
A separate source-aware path (`buildReconstructedAsar`) can classify the renderer as `clean-source` from `frontend/src/main.tsx`. `npm run package` does not use that path; `tests/publication-packaging.test.mjs` asserts the default packager imports `buildFidelityReconstructedAsar`.
## Ignored `src/app/dist` hydration
`npm run bootstrap` (`scripts/bootstrap-runtime.mjs`) is the only supported way to populate the compile input.
Absolute path to an existing Grok Bot 0.18.0 `.app`. Takes precedence over cache and DMG.
Resolution order:
1. `GROK_BOT_018_APP` → cache with `ditto` to `.cache/runtime/Grok Bot.app`
2. Existing `.cache/runtime/Grok Bot.app` if `CFBundleShortVersionString` is `0.18.0`
3. Git LFS DMG `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg`
4. Public URL `https://downloads.cursor.com/grokbot/stable/darwin-arm64/0.18.0/Grok_Bot_0.18.0.dmg`
Required identities:
| Input | Expected SHA-256 |
| --- | --- |
| DMG | `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| `Contents/Resources/app.asar` | `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58` |
Hydration extracts the ASAR into a temp dir, requires these files, then replaces **only** `src/app/dist`:
- `dist/electron-main/main.cjs`
- `dist/host/host-main.cjs`
- `dist/renderer/index.html`
`.gitignore` lists `/src/app/dist/`. Do not commit hydrated payloads, `.cache/`, `.build/`, or `dist/`.
```sh title="Hydrate the pinned 0.18.0 payload"
git lfs pull
npm run bootstrap
```
```text title="Expected bootstrap signal"
Runtime ready: …/.cache/runtime/Grok Bot.app
Checksum-pinned source payload ready: …/src/app/dist ()
The checksum-pinned app supplies only the Electron shell, ABI-matched native dependencies, and explicitly documented build fallbacks.
```
## Checksum-pinned renderer
The 0.18.0 ASAR shipped optimized production chunks, not authored frontend source or source maps. Packaged UI authority is that inventory, recorded as `dist/renderer-artifact-provenance.json` (`schemaVersion` 1, `mode` `checksum-pinned-artifact-runtime`, `upstreamAppAsarSha256` equal to the pinned ASAR digest, per-file SHA-256 list).
The only default UI transform is `applyOriginalRendererRouterPatch`:
- Finds exactly one Settings registry chunk and one panel chunk under staged `dist/renderer/assets/*.js`
- Inserts Settings tab `router` / label `Router`
- Records `dist/renderer-router-extension.json` (`mode` `original-renderer-settings-extension`, features `settings-router-provider`, `settings-local-docker-vm`, `usage-current-provider`)
- Stores original and patched byte counts and SHA-256 for those chunks
Evidence-only rule: recovered UI may express only behavior with an inspectable artifact anchor. Do not invent screens, routes, controls, or labels to fill gaps. `frontend/` is a readable Vite workspace and typecheck/build target; it is not the packaged renderer.
Optional path (resolved from the repo root) whose `index.html` replaces staged `dist/renderer` inside `buildAsar` **before** the fidelity overlay. Overlay still leaves the renderer as artifact-runtime, then the Settings patch runs. The override must still contain the original registry and panel anchors or packaging throws `Expected one original Settings registry and panel chunk`.
## Reconstructed macOS identity
`scripts/package-macos.mjs` aborts unless `process.platform === "darwin"`. It `ditto`s the cached 0.18.0 app, clears quarantine with `xattr -cr`, swaps `app.asar` / `app.asar.unpacked`, then rewrites Info.plist.
| Key | Reconstructed value | Constraint |
| --- | --- | --- |
| `CFBundleIdentifier` | `com.anysphere.sand.reconstructed` | `npm run verify` fails on any other ID |
| `CFBundleDisplayName` | `Grok Bot 0.18 Reconstructed` | Fork display name |
| `CFBundleName` / `CFBundleExecutable` | `Grok Bot` | Electron helper names stay ABI-matched to 0.18 |
| `CFBundleURLTypes` | scheme `sand` only | Inherited aliases such as `grokbot` are removed |
| `ElectronAsarIntegrity` | removed | Stale official integrity metadata is a verify failure |
| Signature | ad-hoc, `--deep --strict` | Official Developer ID / notarization is not retained |
| Default output | `dist/Grok Bot 0.18 Reconstructed.app` | Override with `GROK_BOT_OUTPUT_APP_NAME` |
Packaging also proves the official reference (`verifyOfficialMacReference`) still hashes to the pinned shell and ASAR, then proves the reconstructed package **does not** copy that official `app.asar` or signed Mach-O shell.
Related identity constants in `scripts/lib/config.mjs`: `fidelityBundleId` `com.anysphere.sand.reconstructed.fidelity` (fidelity app) and diagnostic IDs `com.anysphere.sand.reconstructed.fidelity.diagnostic.build*`. Those are not the default package ID.
## Production bindings must resolve into `source/`
Clean host and Electron-main activation is fail-closed. Binding modules must live under reviewed `source/`. Forbidden roots:
- `src/app/`
- `recovered/source-capsules/`
- `dist/deps/`
- `.build/app/`
Overrides:
Binding manifest path. Default, when present: `manifests/reconstruction/electron-main-production-bindings-manifest.json`.
Host binding manifest. Unset leaves host in `artifact-fallback` until every required slot binds and runner-turn evidence is `supported`.
Packaged clean activations embed `dist/electron-main-production-bindings.json` / `dist/host-production-bindings.json` with status `validated-clean-source` and empty forbidden input/output graphs. `dist/runtime-composition-audit.json` must match `runtimeComposition` in `dist/reconstruction-build.json`. Clean runtimes must not reach immutable `src/app` evidence.
## Packaging-only safety seams
When Electron main stays on the hydrated artifact, packaging prepends a reconstructed updater guard (idempotent) and enables explicit runtime seams:
```js
process.env.SAND_DISABLE_UPDATES ??= "1";
process.env.SAND_DISABLE_SENTRY ??= "1";
process.env.SAND_DISABLE_TELEMETRY ??= "1";
```
`??=` keeps caller-supplied values. `GROK_BOT_RECONSTRUCTED_DEV=1` (and `GROK_BOT_BUILD_DEV_APP=1` for the dev product name / `sandLab`) can open packaged DevTools and skip the single-instance lock; those seams require exact upstream string anchors or the build throws.
## Commands and verification
```sh
npm run bootstrap # hydrate ignored src/app/dist
npm run check # frontend + source typecheck and tests
npm run package # darwin-only fidelity hybrid app
npm run verify # required ASAR entries, renderer inventory, bundle ID, codesign
```
`npm run verify` additionally requires at least 1,000 surviving `// src/` evidence markers in hydrated `electron-main` + `host` mains, forbids renderer `.map` files, and requires ASAR paths including `/dist/renderer/index.html`, `/dist/reconstruction-build.json`, and `/dist/runtime-composition-audit.json`. For `checksum-pinned-artifact-runtime`, every packaged `dist/renderer/**` file must match the embedded SHA-256 inventory except the hash-recorded Router patch chunks.
- Missing runtime: `Missing 0.18.0 runtime. Run npm run bootstrap first.`
- Version mismatch on `GROK_BOT_018_APP`: `Expected Grok Bot 0.18.0`
- DMG or `app.asar` digest mismatch (including LFS pointer-sized archives)
- Hydration missing `dist/electron-main/main.cjs`, `dist/host/host-main.cjs`, or `dist/renderer/index.html`
- `npm run package` on non-darwin
- Settings patch anchors missing or duplicated after a renderer override
- Verify: unexpected `CFBundleIdentifier`, leftover `ElectronAsarIntegrity`, missing `sand` URL scheme, official ASAR copied into the reconstructed app
## Next
GROK_BOT_018_APP, cache, LFS DMG, public URL, and src/app/dist hydration checks.
Compile runtimes, patch Settings Router, replace app.asar, ad-hoc sign, verify.
frontend/ is a Vite workspace; packaged UI stays the patched shipped renderer unless GROK_BOT_RENDERER_SOURCE is set.
Pinned DMG and app.asar identities, evidence-only UI rule, production bindings into source/.
---
## 05. Inference router
> SandInferenceProvider ids cursor, claude-code, codex, openrouter; default cursor; local transcript store schemaVersion 2; usage schemaVersion 1.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/05-inference-router.md
- Generated: 2026-08-24T05:51:38.839Z
### Source Files
- `source/shared/inference-router.ts`
- `source/node-agent-coordinator/inference-router.ts`
- `source/host/extensions/inference/provider-session.ts`
- `source/electron-main/main-edge.ts`
- `frontend/src/recovered/features/settings/overlay/router.ts`
- `tests/inference-router-transcript.test.mjs`
---
title: "Inference router"
description: "SandInferenceProvider ids cursor, claude-code, codex, openrouter; default cursor; local transcript store schemaVersion 2; usage schemaVersion 1."
---
The inference router is the shared `SandInferenceProvider` selection that decides whether a turn uses the Cursor-hosted agent path or a reconstructed direct provider. The four ids are `cursor`, `claude-code`, `codex`, and `openrouter`. Missing or invalid values resolve to `cursor`. The packaged Settings → Router page writes the selection through `window.desktop.agent.setInferenceRouter`, persists `inferenceProvider` on `settings.json` (`version: 1`), records usage as `inferenceRouterUsage` with `schemaVersion: 1`, and stores non-Cursor conversation tails in `inference-router-transcript.json` with `schemaVersion: 2`.
Cursor remains the default and is not intercepted. Direct providers (`claude-code`, `codex`, `openrouter`) own `sendPrompt`, merge local transcript tails, and execute Grok Bot plugin tools through `listRoutedMcpTools` / `executeRoutedMcpTool`.
## Provider ids
| Id | Settings label | Auth surface | Turn path | Plugin tools |
| --- | --- | --- | --- | --- |
| `cursor` | Cursor | Existing Grok Bot / Cursor session | Native host inference session | Native Grok Bot tools and plugins |
| `claude-code` | Claude Code | Local Claude Code CLI login | Claude Agent SDK `query` | HTTP MCP bridge `grok_bot_plugins` |
| `codex` | Codex | Private `~/.codex/auth.json` ChatGPT tokens | Direct Responses at `https://chatgpt.com/backend-api/codex/responses` | Direct tool-execution loop |
| `openrouter` | OpenRouter | `OPENROUTER_API_KEY` (env or `box-secrets.json`) | OpenAI-compatible `https://openrouter.ai/api/v1` | Direct tool-execution loop |
Shared type:
```ts title="source/shared/inference-router.ts"
export const SAND_INFERENCE_PROVIDERS = ["cursor", "claude-code", "codex", "openrouter"] as const;
export type SandInferenceProvider = (typeof SAND_INFERENCE_PROVIDERS)[number];
```
`isSandInferenceProvider` is the only accepted setter check. `setInferenceRouter` throws `Unknown inference provider.` for any other string.
## Runtime ownership
```mermaid
flowchart TB
subgraph ui [Renderer]
RouterPanel["Settings → Router"]
UsagePanel["Settings → Usage & Billing"]
DesktopAgent["window.desktop.agent"]
end
subgraph main [Electron main]
GetSet["getInferenceRouter / setInferenceRouter"]
SettingsStore["SandSettingsStore settings.json"]
LocalStatus["getLocalInferenceCliStatus"]
end
subgraph coordinator [Node agent coordinator]
Dispatch["createCoordinatorInferenceRouter.dispatch"]
Transcript["inference-router-transcript.json"]
RemoteGW["gatewayClient.dispatchCommand"]
end
subgraph host [Host]
TurnShell["turn-run-shell / createHostInference"]
CursorPath["createCursorSandInference"]
ProviderSession["runRoutedProviderText"]
end
RouterPanel --> DesktopAgent
UsagePanel --> DesktopAgent
DesktopAgent --> GetSet
GetSet --> SettingsStore
GetSet --> LocalStatus
GetSet -->|"syncHostSettingsToBox({ inferenceProvider })"| host
Dispatch -->|"provider === cursor"| RemoteGW
Dispatch -->|"provider !== cursor and sendPrompt"| ProviderSession
Dispatch --> Transcript
TurnShell -->|"inferenceProvider === cursor"| CursorPath
TurnShell -->|"else"| ProviderSession
```
Three layers read the same `settings.json` field:
- Electron main for Settings RPC and local CLI status.
- Host `SettingsService` / `SandSettingsStore` for `createHostInference` and `turn-run-shell`.
- Coordinator `createCoordinatorInferenceRouter` for intercepting renderer `sendPrompt` before the remote gateway.
Cursor turns stay on the original host inference client. Direct providers replace that session with `createProviderPromptSession` / `runRoutedProviderText`.
## Select and persist a provider
Packaged UI does **not** use the frontend design-workspace key `settings.router-provider.v1`. Packaging tests require the shipped renderer patch to call desktop RPC instead.
One of `cursor`, `claude-code`, `codex`, `openrouter`. Default when unset: `cursor`.
:::endpoint GET getInferenceRouter
Read the current route, usage snapshot, and local CLI status.
**Channel:** `window.desktop.agent.getInferenceRouter()` → main-edge `getInferenceRouter`
**Returns:** `{ provider, usage, local }`
- `provider` — stored `inferenceProvider`, coerced with `isSandInferenceProvider`, else `cursor`
- `usage` — host `inferenceRouterUsage` when reachable, else the local settings copy
- `local` — `{ codex, "claude-code" }` installation/auth probes
`openrouter` status is not in `local`; the Router panel checks the secrets list for `OPENROUTER_API_KEY`.
:::
:::endpoint POST setInferenceRouter
Persist a provider id and mirror it into host settings.
**Channel:** `window.desktop.agent.setInferenceRouter(provider)` → main-edge `setInferenceRouter` with `{ provider }`
**Behavior:**
1. Reject unknown ids with `Unknown inference provider.`
2. Write `inferenceProvider` through `SandSettingsStore.setInferenceProvider`.
3. Call `syncHostSettingsToBox({ inferenceProvider })`. Host sync failure is swallowed; the local write still stands.
4. Return `{ provider, usage, local }` using host usage when the sync response includes it.
The patched Router panel then dispatches `sand-router-provider-changed` with that payload.
:::
```js title="Renderer"
await window.desktop.agent.setInferenceRouter("codex");
```
```json title="getInferenceRouter / setInferenceRouter"
{
"provider": "codex",
"usage": {
"schemaVersion": 1,
"providers": {
"cursor": { "requests": 0, "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": null },
"claude-code": { "requests": 0, "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": null },
"codex": { "requests": 3, "inputTokens": 1200, "outputTokens": 400, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": "2026-08-24T12:00:00.000Z" },
"openrouter": { "requests": 0, "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": null }
}
},
"local": {
"codex": { "installed": true, "authenticated": true, "executablePath": "/opt/homebrew/bin/codex" },
"claude-code": { "installed": false, "authenticated": false, "executablePath": null }
}
}
```
`settings.json` lives under the Sand data root (`SAND_DATA_ROOT`, else `/sand-data`, else `~/.grokbot` for production `sand`). Writes are atomic (`settings.json..tmp` then rename). Host `setHostSettings` only accepts a provider that passes `isSandInferenceProvider`.
The Vite `frontend/` overlay still round-trips `{ schemaVersion: 1, provider }` under `settings.router-provider.v1` for the design workspace. That key is not the packaged persistence path.
## Direct-provider intercept
Coordinator dispatch order:
1. `reactToMessage` — toggle a local `by: "me"` reaction on a stored entry if one exists; emit `transcript` `updated`.
2. Transcript reads (`getAgentTranscriptTail`, `openAgentTail`, `getAgentTranscriptWindow`) when provider is not `cursor` — remote entries plus projected local entries, sliced to `limit` (default `500`).
3. `sendPrompt` when provider is not `cursor` — handle locally and return `{ accepted: true, clientNonce, provider }` immediately. Turns for the same `agentId` are serialized on an in-process queue.
4. Otherwise `{ handled: false }` so the remote gateway runs.
```mermaid
sequenceDiagram
participant Renderer
participant Coordinator as createCoordinatorInferenceRouter
participant Transcript as inference-router-transcript.json
participant Host as runRoutedProviderText
participant Gateway as gatewayClient
Renderer->>Coordinator: sendPrompt({ agentId, prompt, richText, clientNonce })
alt provider is cursor
Coordinator->>Gateway: dispatchCommand(sendPrompt)
else provider is claude-code, codex, or openrouter
Coordinator->>Transcript: append user t{n}u
Coordinator->>Renderer: transcript appended + agents thinking pulse
Note over Coordinator: wait 1200 ms for composing row
Coordinator->>Host: runRoutedProviderText + onTextDelta
Host-->>Coordinator: streamed text then final content
Coordinator->>Transcript: append assistant t{n}s0
Coordinator-->>Renderer: { accepted, clientNonce, provider }
end
```
Local turn constraints:
| Rule | Value |
| --- | --- |
| Required args | Non-empty `agentId` and `prompt` |
| Optional args | `richText` (string), `clientNonce` (else a new UUID) |
| Turn ids | Next `t{n}` after max of remote and local `/^t(\d+)(?:u\|s\d+)$/` ids |
| User projection | `{ kind: "message", id: "t{n}u", role: "user", ... }` |
| Assistant projection | `{ kind: "send-message", id: "t{n}s0", message: { type: "text", content } }` |
| Activity pulse | `currentActivity: { kind: "thinking" }` every 250 ms until the turn settles |
| Composing delay | 1200 ms before the first assistant stream so the shipped transcript can show composing |
| Failure | Assistant row `Router error: ` |
## Local transcript store
Path: `/inference-router-transcript.json`
Mode: `0o600` temp file, then rename
Parser: `parseInferenceRouterTranscriptStore` — any root whose `schemaVersion` is not `2` or whose `agents` is not an object becomes `{ schemaVersion: 2, agents: {} }`
```json title="inference-router-transcript.json"
{
"schemaVersion": 2,
"agents": {
"": [
{
"provider": "codex",
"role": "user",
"content": "@Gmail what's new?",
"richText": "{\"type\":\"doc\",...}",
"id": "t1u",
"clientNonce": "nonce-1",
"timestampMs": 123,
"reactions": [{ "emoji": "👍", "by": "me" }]
},
{
"provider": "codex",
"role": "assistant",
"content": "...",
"id": "t1s0",
"timestampMs": 456
}
]
}
}
```
Required. Any other version is discarded.
Per-agent tails. Each agent is truncated to the last 200 valid entries on parse and on append.
Cursor rows are never stored here.
Optional. Must be a string; object carriers are dropped. Used to keep structured MCP mention docs across reload.
Malformed rows are skipped, not migrated. `richText` that is not a string rejects the whole entry.
## Usage store
`inferenceRouterUsage` on `settings.json` is `schemaVersion: 1` and always has all four provider keys.
```ts title="SandInferenceRouterUsageProvider"
{
requests: number;
inputTokens: number;
outputTokens: number;
cacheReadTokens: number;
cacheWriteTokens: number;
lastUsedAt: string | null;
}
```
`SandSettingsStore.recordInferenceUsage` increments `requests` by 1, adds finite non-negative token counts (rounded), and sets `lastUsedAt` to `new Date().toISOString()`. Direct providers record from streamed usage; the Cursor host path records from `extendedUsage` on the wrapped executor.
These counters are local activity records. They are not a provider invoice. The patched Usage & Billing page shows **Tracked activity** for the current route plus any provider with `requests > 0`, and still mounts the original Cursor usage panel when the current route is `cursor`.
## Provider clients
Direct turns share this system prompt:
> You are Grok Bot, a warm, concise desktop assistant. You are running inside Grok Bot, not inside Codex CLI or Claude Code. The tools supplied with this request are Grok Bot's already-connected plugins and accounts.
| Provider | Client | Model default | Credential check | Tool max steps |
| --- | --- | --- | --- | --- |
| `claude-code` | `@anthropic-ai/claude-agent-sdk` `query` | `SAND_CLAUDE_MODEL` if set, else Claude Code default | `resolveClaudeCodeCliPath()` must find a binary | 8 with MCP URL, else 1 |
| `codex` | `streamCodexDirectResponses` | `SAND_CODEX_MODEL`, else `model` in `config.toml`, else `gpt-5.4` | Regular non-symlink `auth.json` with mode bits `0o077 == 0`, `auth_mode === "chatgpt"`, and access/refresh/id/account tokens | 8 with tools, else 1 |
| `openrouter` | `@ai-sdk/openai` `streamText` | `SAND_OPENROUTER_MODEL` or `openai/gpt-5.2` | `OPENROUTER_API_KEY` from env, else `box-secrets.json` | 8 with tools, else 1 |
`claude-code` MCP: coordinator starts `createRoutedMcpBridge` on `127.0.0.1:/mcp/` and passes that URL as `mcpServers.grok_bot_plugins`. Allowed tools: `mcp__grok_bot_plugins__*`. `persistSession` is `false`.
`codex` / `openrouter`: coordinator lists tools with `listRoutedMcpTools` and executes with `executeRoutedMcpTool` (`providerIdentifier`, `name`, `toolName`, `args`, `toolCallId`, `agentId`).
Codex HTTP uses `Authorization: Bearer ` and `ChatGPT-Account-Id`. A `401` refreshes against `https://auth.openai.com/oauth/token` and rewrites `auth.json` atomically at mode `0o600`.
## Local CLI status
`getLocalInferenceCliStatus()` is what Settings shows as Ready / Sign in / Not installed.
| Probe | `installed` | `authenticated` | Path resolution |
| --- | --- | --- | --- |
| `codex` | `auth.json` exists | Usable ChatGPT token file (same privacy rules as the executor) | `CODEX_PATH`, `~/.local/bin/codex`, `~/.codex/bin/codex`, `PATH`, Homebrew paths. The CLI binary is **not** on the request path. |
| `claude-code` | Resolved `claude` binary | `~/.claude/.credentials.json` exists **or** `ANTHROPIC_API_KEY` is non-empty | `CLAUDE_CODE_PATH`, `~/.local/bin/claude`, `~/.claude/local/claude`, `PATH`, Homebrew paths |
`CODEX_HOME` overrides the Codex home used for `auth.json` and `config.toml` (default `~/.codex`).
## Errors the router emits
| Condition | Message |
| --- | --- |
| Unknown `setInferenceRouter` id | `Unknown inference provider.` |
| Direct `sendPrompt` missing `agentId` or `prompt` | `Local inference routing requires an agentId and prompt` |
| OpenRouter key missing | `OpenRouter needs OPENROUTER_API_KEY. Add it in Settings → Router.` |
| Claude Code binary missing | `Claude Code is not installed. Install and sign in to Claude Code, then reopen Grok Bot.` |
| Codex `auth.json` not a private regular file | `Codex login credentials must be a private direct regular file.` |
| Codex not ChatGPT-signed-in | `Codex is not signed in with ChatGPT. Run \`codex login\`, then reopen Grok Bot.` |
| Codex refresh failed | `Codex login expired and could not be refreshed. Run \`codex login\` again.` |
| Claude Code query without a success result | `Claude Code ended without a result.` or joined `final.errors` |
Failed direct turns still persist an assistant `Router error: …` row so the shipped transcript can show the failure.
## Verification
Router identity and intercept wiring are asserted by:
- `tests/router-settings.test.mjs` — recovered overlay ids, default `cursor`, unknown preference falls back to `cursor`
- `tests/inference-router-transcript.test.mjs` — schemaVersion 2 `richText` round-trip; object `richText` dropped
- `tests/publication-packaging.test.mjs` — desktop RPC, `settings.json` sync, transcript merge methods, MCP bridge bind `127.0.0.1`, Codex Responses URL, OpenRouter base URL, 1200 ms composing delay
## Next
Set Settings → Router, persist `inferenceProvider`, and satisfy Cursor, Claude Code, Codex, or OpenRouter credentials.
Cursor default path, Claude Agent SDK query, Codex Responses, OpenRouter model `openai/gpt-5.2`.
`listRoutedMcpTools` and `executeRoutedMcpTool` across the Claude Code MCP bridge versus Codex/OpenRouter direct execution.
`settings.json` version 1 fields including `inferenceProvider` and `inferenceRouterUsage`.
`window.desktop.agent` `getInferenceRouter` / `setInferenceRouter` and secrets channels.
Unknown provider, private `auth.json`, missing Claude Code, missing `OPENROUTER_API_KEY`.
---
## 06. Box runtime
> SandBoxRuntime remote versus local-docker, default remote, coordinator restart on switch, and loopback-only local gateway ownership.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/06-box-runtime.md
- Generated: 2026-08-24T05:51:13.115Z
### Source Files
- `source/shared/box-runtime.ts`
- `source/electron-main/box/local-docker-host-connector.ts`
- `source/electron-main/box/box-host-connector.ts`
- `source/electron-main/main-edge.ts`
- `source/shared/node/settings/sand-settings-store.ts`
---
title: "Box runtime"
description: "SandBoxRuntime remote versus local-docker, default remote, coordinator restart on switch, and loopback-only local gateway ownership."
---
`SandBoxRuntime` is the persisted computer-host mode for Grok Bot. It is a closed enum of `remote` and `local-docker`. The default is `remote`. Settings → Router → Computer exposes a **Use local Docker VM** switch that calls `window.desktop.agent.setBoxRuntime`. On a successful switch, main-edge starts or stops `grok-bot-local-vm`, then `boxRecovery.restartCoordinator()` so the next gateway connect follows the stored mode. Start or stop failure writes the opposite mode back and does not restart the coordinator.
Inference routing (`inferenceProvider`) and box runtime (`boxRuntime`) share the Router settings page but are independent. Changing Cursor / Claude Code / Codex / OpenRouter does not change where the computer runs.
## Runtime ids
| Id | Default | Computer host | Gateway |
|---|---|---|---|
| `remote` | yes (`DEFAULT_SAND_BOX_RUNTIME`) | Cursor-brokered Sand box, or `SAND_HOST_GATEWAY_URL` when that env is set | Broker `gatewayUrl` (plus token / network token / VNC when the broker supplies them) |
| `local-docker` | no | Owned Docker container `grok-bot-local-vm` | `http://127.0.0.1:1340` with a local bearer token |
`isSandBoxRuntime` accepts only those two strings. Any other `setBoxRuntime` payload fails with `Unknown box runtime.`
## Persistence
`SandStoredSettings` is `settings.json` version `1`. `boxRuntime` is optional. `SandSettingsStore.getBoxRuntime()` returns the stored value or `remote`. `setBoxRuntime` writes the field through the store’s atomic temp-file persist (`settings.json..tmp` then rename).
Sibling files next to `settings.json` (same directory):
| Path | Purpose |
|---|---|
| `local-docker-vm.json` | Gateway token (`schemaVersion: 1`, 32-byte hex, mode `0o600`) |
| `local-docker-credential/inference.json` | Optional Cursor inference token for the VM (`accessToken`, `expiresAtMs`, mode `0o600`) |
| `local-docker-runtime/-/` | Content-addressed `host-main.cjs` and `box-exec-daemon/main.cjs` bind mounts |
Invalid JSON, a non-`1` `version`, or a non-enum `boxRuntime` loads as empty settings, so the mode falls back to `remote`.
## Desktop RPC
Both methods require the Sand app window top frame (`createMainEdgeTrust` denial: `The main edge is only accessible from the Sand app window's top frame.`).
Preload surface:
```ts
window.desktop.agent.getBoxRuntime()
window.desktop.agent.setBoxRuntime(mode)
```
Main-edge contract (`source/shared/rpc/main.ts`): `getBoxRuntime` args `none`; `setBoxRuntime` args `object`.
`remote` or `local-docker`. Required on `setBoxRuntime`.
Persisted mode after the call. On start/stop failure this is the reverted opposite of the requested mode, and the RPC throws.
Always the local Docker probe, even when `mode` is `remote`.
`LocalDockerStatus`:
| Field | Type | Meaning |
|---|---|---|
| `available` | `boolean` | `docker info` succeeded |
| `running` | `boolean` | Container process is running |
| `ready` | `boolean` | Owned container is running **and** `GET http://127.0.0.1:1340/health` with the stored bearer token returned OK |
| `containerName` | `string` | Always `grok-bot-local-vm` |
| `image` | `string` | Expected `public.ecr.aws/k0i0n2g5/cursorenvironments/universal:sand-box-latest`, or the inspected image if a container already exists |
| `detail` | `string` | Operator-facing status string |
Typical `detail` values: `Docker is not running.`, `Ready to create the local VM.`, `Container grok-bot-local-vm exists but is not owned by Grok Bot.`, `Local Docker VM is ready.`, `Container is starting.`, `Local Docker VM is stopped.`
The packaged Settings Router panel (`RBoxRuntime` from the original-renderer patch) initializes at `{ mode: "remote", status: null, error: null, busy: true }`, then hydrates from `getBoxRuntime`. Toggle copy: remote = `Shell, files and computer use run on Grok Bot's remote computer.`; local = `status.detail` or `Shell, files and computer use run in a Docker container on this Mac.`
## Switch lifecycle
```mermaid
sequenceDiagram
participant UI as Settings Router RBoxRuntime
participant Edge as main-edge setBoxRuntime
participant Store as SandSettingsStore
participant Docker as startLocalDockerBox / stopLocalDockerBox
participant Coord as boxRecovery.restartCoordinator
UI->>Edge: setBoxRuntime({ mode })
Edge->>Store: persist requested mode
alt mode is local-docker
Edge->>Docker: startLocalDockerBox(settingsPath)
else mode is remote
Edge->>Docker: stopLocalDockerBox()
end
alt start or stop throws
Edge->>Store: persist opposite mode
Edge-->>UI: throw (no coordinator restart)
else start or stop succeeds
Edge->>Coord: restartCoordinator()
Coord->>Coord: active.restart()
Edge-->>UI: { mode, status }
end
```
Coordinator restart is the same path as `forceReconnectGateway`. Production wiring is `coordinator.restartCoordinator()` → `active?.restart()`. After restart, `createSettingsRoutedHostConnector.connect()` reads `settings.getBoxRuntime()` again:
- `local-docker` → `ensureLocalDockerBox` (single-flight `ensureInFlight`)
- otherwise → the inner remote connector (`BrokeredHostConnector`, or `EnvDescriptorHostConnector` when `SAND_HOST_GATEWAY_URL` is set)
`SAND_HOST_GATEWAY_URL` applies only while the stored mode is `remote`. `local-docker` still owns connect, recreate, and force-recreate.
## Connector routing
```mermaid
flowchart TB
subgraph ui [Packaged Settings UI]
Toggle["Use local Docker VM"]
end
subgraph rpc [Desktop RPC appWindow]
Get["getBoxRuntime"]
Set["setBoxRuntime"]
end
subgraph persist [Settings]
Json["settings.json boxRuntime"]
end
subgraph router [createSettingsRoutedHostConnector]
Route{"getBoxRuntime()"}
end
subgraph remote [Remote host]
Env["EnvDescriptorHostConnector SAND_HOST_GATEWAY_URL"]
Broker["BrokeredHostConnector ensureSandBox"]
Fast["Gateway descriptor fast path"]
end
subgraph local [Local Docker owner]
Ctr["grok-bot-local-vm"]
Gw["127.0.0.1:1340"]
end
subgraph coord [Coordinator]
Restart["restartCoordinator"]
end
Toggle --> Set
Get --> Json
Set --> Json
Set --> Restart
Restart --> Route
Route -->|"local-docker"| Ctr
Ctr --> Gw
Route -->|"remote"| Env
Route -->|"remote, URL unset"| Broker
Broker --> Fast
```
Production binds this router in `createProductionCoordinatorGatewayBinding` and in `main-production-services` as `rawRemoteConnector`. Recreate / reset:
| Mode | Recreate | Force recreate |
|---|---|---|
| `remote` | Broker `recreateSandBox`; missing method throws `Remote computer recreation is unavailable.` | Broker `forceRecreateSandBox`; missing method returns `{ status: "rejected", reason: "Remote computer reset is unavailable." }` |
| `local-docker` | `docker restart grok-bot-local-vm`, wait for gateway, `{ status: "started-untrackable" }` | `docker rm --force grok-bot-local-vm` (ignore “no such container”), recreate, `{ status: "started-untrackable" }` |
Local Docker never returns a trackable migration `operationId`. Remote recreate can return `{ status: "started", operationId }` when the broker supplies one.
## Loopback-only local gateway
The local VM is created only when the name `grok-bot-local-vm` is free or already labeled `com.grok-bot.local-vm=1`. Schema version is `"6"`. Published ports bind host loopback only:
`127.0.0.1:1337`, `1339`, `1340`, `6080`, `6081`, `8790`.
Inside the container the gateway binds `SAND_GATEWAY_BIND_HOST=0.0.0.0` and `SAND_HOST_PORT=1340`. Host health checks use the loopback URL, not a LAN address.
:::endpoint GET /health Local Docker gateway readiness
The coordinator treats the VM as ready only when this probe succeeds with the token from `local-docker-vm.json`. Timeout is 2 seconds. Overall start wait is 180 seconds (`Local Docker VM did not expose its gateway within three minutes.`).
```http
GET http://127.0.0.1:1340/health
Authorization: Bearer
```
:::
Ownership and replacement rules:
- Unowned container with the same name: status `ready: false`; start throws `Local Docker VM cannot use grok-bot-local-vm: an unowned container already has that name.`; stop throws `Refusing to stop unowned container grok-bot-local-vm.`
- Unexpected image: start throws; the operator must remove the container before changing images.
- Schema version, `com.grok-bot.local-vm.host-sha256`, or missing inference-credential label when a credential was issued: `docker rm --force` then recreate.
- Stock VM refusal: if reconstructed `host/host-main.cjs` or `box-exec-daemon/main.cjs` cannot be staged, start throws and does not launch the image.
Optional readonly binds when those directories exist: `~/.codex` → `/root/.codex`, `~/.claude` → `/root/.claude`. Named volumes `grok-bot-local-vm-workspace` and `grok-bot-local-vm-data` persist workspace and box data across container replace.
Image, labels, mounts, and health details live on the local Docker connector page. Operator steps (Docker daemon, toggle, rollback) live on Enable the local Docker sandbox.
## Remote connector notes
When mode is `remote` and `SAND_HOST_GATEWAY_URL` is unset, `BrokeredHostConnector.connect()` calls `ensureSandBox`. Empty `gatewayUrl` throws `SandBoxHostConnectError`. Access denials map to the gateway access-denied marker. A `SAND_BOX_BLOCKED` automation hint holds reconnect for `retry-after` or 60 seconds, capped at 15 minutes. `SAND_CLIENT_UPDATE_REQUIRED` notes a backend update requirement. `SAND_HOST_GATEWAY_TOKEN` and `SAND_HOST_GATEWAY_NETWORK_TOKEN` apply only to the env-descriptor path.
## Failure modes
| Condition | Persist | Coordinator | Error / status |
|---|---|---|---|
| Unknown `mode` | unchanged | not restarted | `Unknown box runtime.` |
| Docker daemon missing while selecting `local-docker` | rolled back to `remote` | not restarted | `Local Docker VM is selected, but Docker is unavailable: …` |
| Unowned `grok-bot-local-vm` | rolled back to `remote` on start; stop also refuses | not restarted on throw | Unowned-container errors above |
| Gateway not ready in 3 minutes, or container exits first | rolled back to `remote` | not restarted | Timeout or `Local Docker VM stopped before its gateway became ready.` plus last 80 log lines |
| Stop `local-docker` → `remote` fails | rolled back to `local-docker` | not restarted | `Could not stop the local Docker VM: …` |
| Success | requested mode | `restartCoordinator()` | `{ mode, status }` with `status.ready` reflecting `/health` |
The Settings toggle stays `busy` during the RPC. On throw it restores the previous UI mode and shows `error`.
## Related pages
Toggle Use local Docker VM, wait for loopback health, and roll back to remote on start failure.
Image, owner labels, schema version 6, published ports, and content-addressed host mounts.
getBoxRuntime, setBoxRuntime, and the rest of window.desktop.agent.
settings.json version 1, including boxRuntime and atomic persist.
Unowned grok-bot-local-vm and other sandbox start failures.
---
## 07. Evidence and provenance
> Pinned 0.18.0 DMG and app.asar SHA-256 identities, evidence-only UI rule, and production bindings that must resolve into source/.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/07-evidence-and-provenance.md
- Generated: 2026-08-24T05:53:50.077Z
### Source Files
- `PROVENANCE.md`
- `NOTICE.md`
- `frontend/README.md`
- `manifests/reconstruction/electron-main-production-bindings-manifest.json`
- `tests/publication-bootstrap.test.mjs`
- `scripts/audit-ui-provenance.mjs`
---
title: "Evidence and provenance"
description: "Pinned 0.18.0 DMG and app.asar SHA-256 identities, evidence-only UI rule, and production bindings that must resolve into source/."
---
The reconstruction treats the public Grok Bot **0.18.0** macOS arm64 release as an immutable product specification. `scripts/lib/config.mjs` pins `upstreamVersion` to `0.18.0`, `dmgSha256` to `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb`, and `upstreamAsarSha256` to `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58`. Bootstrap, hydration, packaging, and `npm run verify` reject any other DMG or `app.asar` identity. Recovered UI and Electron-main production bindings may express only behavior that those artifacts still contain.
## Pinned 0.18.0 identities
| Identity | Value |
| --- | --- |
| Product | Grok Bot |
| Version | `0.18.0` |
| Upstream bundle ID | `com.anysphere.sand` |
| Reconstructed bundle ID | `com.anysphere.sand.reconstructed` |
| Electron | `42.1.0` |
| macOS DMG | `https://downloads.cursor.com/grokbot/stable/darwin-arm64/0.18.0/Grok_Bot_0.18.0.dmg` |
| DMG SHA-256 | `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| DMG size | `155793020` bytes |
| Original `app.asar` SHA-256 | `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58` |
| Windows installer | `https://downloads.cursor.com/grokbot/stable/win32-x64/0.18.0/Grok_Bot_0.18.0_Setup.exe` |
| Windows SHA-256 | `464079a15ef5fa8b61ccea8fffcc78f63cfcf6df65fb0ad5e725d8b95f7e437e` |
| Windows size | `125825552` bytes |
| Preservation manifest | `research-archives/original/0.18.0/artifacts.json` (`schemaVersion` `1`) |
The original application was Developer ID signed and notarized by Anysphere Incorporated. Reconstructed builds use `com.anysphere.sand.reconstructed`, are ad-hoc signed only, and do not retain or claim the upstream signature.
Git LFS preserves both installers. `artifacts.json` is the machine-readable inventory; `SHA256SUMS` is the `shasum -c` companion.
:::files
research-archives/original/0.18.0/
├── artifacts.json
├── SHA256SUMS
├── macos-arm64/Grok_Bot_0.18.0.dmg
└── windows-x64/Grok_Bot_0.18.0_Setup.exe
:::
```sh
git lfs install
git lfs pull
(cd research-archives/original/0.18.0 && shasum -a 256 -c SHA256SUMS)
```
No upstream source-code license is implied. Do not present reconstructed material as original source or an official build. The LFS installers remain subject to their own terms and are not covered by any license applied to reconstructed code. Complete an independent rights review before public redistribution.
## Provenance layers
Checksums, UI catalogs, and production bindings are separate fail-closed layers. A green typecheck does not substitute for any of them.
```mermaid
flowchart TB
subgraph installers [Pinned public installers]
DMG["Grok_Bot_0.18.0.dmg dmgSha256"]
EXE["Grok_Bot_0.18.0_Setup.exe artifacts.json"]
end
subgraph payload [Hydrated immutable payload]
ASAR["Contents/Resources/app.asar upstreamAsarSha256"]
DIST["src/app/dist electron-main / host / renderer"]
end
subgraph reviewed [Reviewed reconstruction]
SOURCE["source/"]
FRONTEND["frontend/"]
MANIFEST["manifests/reconstruction/ electron-main-production-bindings-manifest.json"]
CATALOG["frontend/manifests/ ui-evidence-anchors.json"]
end
DMG --> ASAR
ASAR --> DIST
DIST -->|"artifactAnchor needles"| MANIFEST
DIST -->|"immutable renderer claims"| CATALOG
MANIFEST -->|"module must resolve under source/"| SOURCE
CATALOG -->|"exact UI claim in cleanPath"| FRONTEND
```
## Bootstrap and hydration gates
`npm run bootstrap` (`scripts/bootstrap-runtime.mjs`) locates a 0.18.0 app, then hydrates ignored `src/app/dist` from its `app.asar`.
Order: `GROK_BOT_018_APP` (copied into `.cache/runtime/Grok Bot.app`), then the cached app, then the LFS DMG, then `dmgUrl`. `validateRuntimeApp` requires `CFBundleShortVersionString` `0.18.0`, `Contents/MacOS/Grok Bot`, and `Contents/Resources/app.asar.unpacked`.
Cached and downloaded DMGs must equal `dmgSha256`. An archived LFS pointer or drifted file fails with `Archived DMG checksum mismatch: expected a253ccd8…`. A public download that does not match is deleted as `*.partial` and fails with `DMG checksum mismatch`.
`hydrateSourcePayloadFromAsar` hashes the ASAR against `upstreamAsarSha256` (overrideable only in tests via `expectedSha256`). Mismatch throws `Upstream app.asar checksum mismatch`. The archive must contain `dist/electron-main/main.cjs`, `dist/host/host-main.cjs`, and `dist/renderer/index.html` before `dist/` is copied to `src/app/dist`.
Absolute path to an installed 0.18.0 `Grok Bot.app`. Version mismatch aborts before hydration.
Optional schemaVersion 1 binding manifest. Defaults to `manifests/reconstruction/electron-main-production-bindings-manifest.json` when that file exists. A residual-only manifest cannot override the sixteen reviewed `source/` providers.
Success log:
```text
Checksum-pinned source payload ready: /src/app/dist (6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58)
```
Packaged artifact-renderer provenance must also carry `upstreamAppAsarSha256` equal to that digest. `npm run verify` rejects a drifted provenance identity.
## Evidence-only reconstruction rule
The immutable release is the product specification. Recovered source may express only behavior supported by at least one inspectable artifact anchor:
- emitted code or source-path markers
- extracted capsules / source maps
- shipped strings, assets, or CSS
- renderer DOM signatures
- IPC / RPC contracts
- repeatable observation of the shipped runtime
The rule is strict for the renderer. Do not invent or redesign a screen, route, control, label, selector, state, or interaction to fill an evidence gap. A clean abstraction or test seam is acceptable only when it preserves artifact-derived semantics and does not add product behavior. When evidence is incomplete, record the uncertainty and leave the feature unmapped or evidence-only.
Passing `npm run typecheck` / `npm run frontend:build` is not proof of provenance. Speculative UI is a release-blocking defect.
The shipped renderer is optimized production bundles, not authored frontend source or source maps. `frontend/` is a partial evidence-backed reconstruction and Vite design workspace. Packaged builds retain the pinned renderer and apply only a narrow, hash-recorded Settings Router transform unless `GROK_BOT_RENDERER_SOURCE` overrides the renderer source.
Comments beginning with `@evidence` (or `@artifact-evidence`) are provenance annotations, not imports. `scripts/audit-ui-provenance.mjs` accepts annotation paths only under:
- `src/app/`
- `recovered/frontend/`
- `recovered/source-capsules/`
- `frontend/manifests/`
## UI evidence catalog and auditor
`frontend/manifests/ui-evidence-anchors.json` is `schemaVersion` `1` with an `entries` array. Each entry names one clean file and exact anchors.
Allowed catalog `category` values: `visible-string`, `selector`, `route`, `dom-signature`, `asset`.
Each anchor must:
- use an exact value (no wildcards, newlines, or prose such as `see shipped`)
- point `artifact` at immutable `src/app/` evidence (not the clean file or the catalog)
- occur at the declared artifact location
- match an extracted UI claim in the named `cleanPath`
- if `registry` is set, name a reviewed registry: `recovered/frontend/reports/features.json`, `frontend/manifests/semantic-symbols.json`, `frontend/manifests/component-names.json`, `frontend/manifests/conversation-evidence.json`, or `frontend/src/production/evidence.ts`
Auditor inputs (`UI_AUDIT_INPUTS`):
| Role | Path |
| --- | --- |
| Anchor catalog | `frontend/manifests/ui-evidence-anchors.json` |
| Clean roots | `frontend/src/recovered`, `frontend/src/production`, plus `frontend/src/main.tsx` |
| Immutable renderer | `src/app/dist/renderer` |
| Production evidence registry | `frontend/src/production/evidence.ts` |
| Optional recovered trees | `recovered/source-capsules/manifest.json`, `recovered/frontend/app`, `recovery/full-app-coverage.json` |
```sh
node scripts/audit-ui-provenance.mjs [--json] [--include-audits] [--include-dev] [--source=substring] [--limit=N] [--fail-on=high|medium]
```
`--fail-on=high` exits `1` when `summary.high > 0`. `--fail-on=medium` also fails on medium findings.
High-severity codes include `missing-module-provenance`, `unanchored-visible-string`, `unanchored-route`, `invalid-evidence-annotation`, `catalog-anchor-not-in-artifact`, `catalog-self-or-nonimmutable-reference`, and `catalog-vague-anchor`. Distinctive reconstructed selectors matching `/^\.(?:sand-|grok-|recovered-)/` are high; other unanchored selectors are medium.
When a full recovered workspace is present, `scripts/renderer-production-build.mjs` requires `ui.summary.catalogErrors === 0` and `ui.summary.findings === 0` plus renderer closure covering **5** composed feature surfaces and **11** shipped routes. On the publication tree it instead validates the checked-in catalog against the closure report and omits `recovered/` registries.
`npm run verify` still requires at least **1,000** surviving `// src/` evidence source markers across hydrated `dist/electron-main/main.cjs` and `dist/host/host-main.cjs`.
## Electron-main production bindings
Clean Electron-main activation is fail-closed on sixteen slots. The checked-in map is `manifests/reconstruction/electron-main-production-bindings-manifest.json` (`schemaVersion` `1`).
`tests/publication-bootstrap.test.mjs` requires every `module` to match `^\.\./\.\./source/` relative to that manifest directory, resolve under repository `source/`, and exist on disk.
Activation (`scripts/electron-main-production-activation.mjs`) additionally:
- requires `classification` `generated-source` | `third-party` | `native` and `access` `call` | `value`
- requires every `artifactAnchor.artifact` to be `src/app/dist/electron-main/main.cjs` with an integer `line` and the exact needle from `electronMainProductionBindingEvidence`
- forbids generated-source modules under `src/app/`, `recovered/source-capsules/`, `dist/deps/`, and `.build/app/`
- validates the export with an esbuild import of the named symbol
- writes packaged provenance to `dist/electron-main-production-bindings.json`
A full sixteen-slot manifest is accepted for compatibility. A partial residual manifest must not overlap the reviewed inventory. Missing slots return `incomplete-evidence-derived-manifest`; there is no default or native fallback.
| `path` | `export` | `access` | Needle |
| --- | --- | --- | --- |
| `adapters.secureStorage` | `createElectronProductionSecureStorageBinding` | `call` | `initializeSecureStorage();` |
| `adapters.settings` | `createElectronProductionSettingsBinding` | `call` | `var sandSettingsStore = new SandSettingsStore(` |
| `adapters.attachmentGateway` | `createElectronProductionAttachmentGatewayBinding` | `call` | `attachments: createAttachmentEdgePort({` |
| `adapters.mainRpc` | `createElectronProductionMainRpcBinding` | `call` | `const mainEdge = serveMainEdge({` |
| `adapters.updaterInstaller` | `createElectronProductionUpdaterInstallerBinding` | `call` | `updateService = createUpdateServiceWiring({` |
| `adapters.mediaProtocol` | `createElectronProductionMediaProtocolBinding` | `call` | `registerSandMediaProtocol();` |
| `adapters.accountOAuth` | `createElectronProductionAccountOAuthBinding` | `call` | `var cursorAuthWiring = createCursorAuthWiring({` |
| `adapters.experiments` | `createElectronProductionExperimentsBinding` | `call` | `var experimentsRuntime = createExperimentsRuntime({` |
| `adapters.mcpOAuth` | `createProductionMcpOAuthAdapter` | `call` | `var mcpRuntime = createMcpRuntime({` |
| `adapters.telemetry` | `createElectronProductionTelemetryBinding` | `call` | `desktopTelemetry = await SandDesktopStructuredLogTelemetry.create({` |
| `adapters.notifications` | `createElectronProductionNotificationsBinding` | `call` | `const osNotificationManager = new SandOsNotificationManager({` |
| `adapters.coordinator` | `createElectronProductionCoordinatorBinding` | `value` | `const createCoordinatorSession = () => createCoordinatorRuntime({` |
| `adapters.ipc` | `createElectronProductionIpcBinding` | `call` | `registerSecretsIpc({` |
| `startup` | `createElectronProductionStartupBinding` | `call` | `var desktopStartup = createDesktopStartupTracker({` |
| `parseAllowedExternalUrl` | `parseAllowedExternalUrl` | `value` | `function parseAllowedExternalUrl(value)` |
| `reportFailure` | `reportDesktopEdgeFailure` | `value` | `function reportDesktopEdgeFailure(area, leg, error6)` |
`npm run verify` requires packaged `dist/electron-main-production-bindings.json` (and the host analog) to have `status` `validated-clean-source`, empty `executableGraph.forbiddenInputs` / `forbiddenOutputReferences`, and no binding `module` containing `src/app`, `dist/deps`, or `recovered/source-capsules`.
Hydration checksum test: `hydrateSourcePayloadFromAsar(..., { expectedSha256: "0".repeat(64) })` must reject with `/checksum mismatch/`.
## Rights and publication
`NOTICE.md` states this tree is an unofficial reconstruction, not affiliated with or endorsed by Anysphere, Cursor, xAI, or SpaceX. Absence of the original binary payload from Git does not by itself make the reconstruction safe to redistribute. `npm run publication:check` is the archive/init/add tree gate before a public remote; it does not replace a rights review.
## Next
Compiled `source/` runtimes, checksum-pinned shipped renderer, and `com.anysphere.sand.reconstructed`.
`npm run bootstrap` order, DMG/`app.asar` SHA-256 checks, and `src/app/dist` hydration.
Git LFS 0.18.0 identities, `artifacts.json` schemaVersion 1, and `shasum -c SHA256SUMS`.
`frontend/` as a Vite design workspace; packaged UI stays the patched shipped renderer.
Required ASAR paths, evidence markers, and packaged binding provenance.
Tree equality, LFS installer push, and NOTICE/rights review before a public remote.
---
## 08. Choose an inference provider
> Set Settings → Router, persist inferenceProvider, and satisfy Cursor session, Claude Code login, Codex auth.json, or OPENROUTER_API_KEY.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/08-choose-an-inference-provider.md
- Generated: 2026-08-24T05:51:28.441Z
### Source Files
- `source/host/extensions/inference/provider-session.ts`
- `source/shared/node/inference-router-local.ts`
- `source/electron-main/main-edge.ts`
- `scripts/lib/router-renderer-patch.mjs`
- `frontend/src/recovered/features/settings/overlay/router.ts`
- `tests/router-settings.test.mjs`
---
title: "Choose an inference provider"
description: "Set Settings → Router, persist inferenceProvider, and satisfy Cursor session, Claude Code login, Codex auth.json, or OPENROUTER_API_KEY."
---
The packaged app’s **Settings → Router** panel selects a `SandInferenceProvider` (`cursor`, `claude-code`, `codex`, `openrouter`), persists it as `inferenceProvider` on `settings.json` version `1` (default `cursor`), and uses that value for new turns. The overlay is injected at package time into the checksum-pinned renderer. `window.desktop.agent.setInferenceRouter(provider)` writes the store and mirrors `{ inferenceProvider }` into the box; it does not validate credentials. Auth is checked when a turn runs.
The Vite workspace under `frontend/` models the same four ids and a local key `settings.router-provider.v1`. Packaged UI does not use that key. Preference for the running app is `inferenceProvider` in host `settings.json`.
## Prerequisites
- A packaged reconstructed app (`npm run package` applies the Settings registry and Router panel patches).
- For `claude-code` or `codex`, the matching local login on this Mac (no extra API key in Settings).
- For `openrouter`, an OpenRouter key in the environment or saved through **Settings → Router**.
## Choose a provider
In the packaged app, open Settings and select **Router** (`id: "router"`, icon `git-branch`). The panel loads `window.desktop.agent.getInferenceRouter()` and listens for `sand-router-provider-changed`.
Use the **Provider** dropdown (`aria-label="Routing provider"`). Allowed values: `cursor`, `claude-code`, `codex`, `openrouter`. Unknown ids fail with `Unknown inference provider.` and the previous selection is restored in the overlay.
Confirm the **Account** / **OpenRouter account** row:
| Provider | Ready signal |
| --- | --- |
| `cursor` | Status **Signed in** (Cursor session already attached to Grok Bot) |
| `claude-code` | **Ready** (CLI found and login present) |
| `codex` | **Ready** (usable private `auth.json`) |
| `openrouter` | Key saved: placeholder **Replace saved key**, or `OPENROUTER_API_KEY` in the process environment |
If Claude Code or Codex is missing, the row shows **Not installed** or **Sign in with claude** / **Sign in with codex login**. Install or log in, then reopen Grok Bot so `getLocalInferenceCliStatus()` refreshes.
The next agent turn reads `SandSettingsStore.getInferenceProvider()`. `cursor` stays on the Cursor session path. Any other id uses `createProviderPromptSession(provider)`.
Changing the dropdown only persists the id. A turn against `claude-code`, `codex`, or `openrouter` without a usable login or key fails at request time, not at save time.
The same Router page includes **Use local Docker VM**. That toggle is `boxRuntime`, not `inferenceProvider`. See [Enable the local Docker sandbox](/enable-local-docker).
## Provider ids
| `inferenceProvider` | Label | Auth surface | New-turn path |
| --- | --- | --- | --- |
| `cursor` | Cursor | Existing Grok Bot / Cursor session | Host Cursor session (`createSession`) |
| `claude-code` | Claude Code | Claude Code CLI + login | `@anthropic-ai/claude-agent-sdk` `query` |
| `codex` | Codex | ChatGPT tokens in Codex `auth.json` | Direct HTTP to `https://chatgpt.com/backend-api/codex/responses` (CLI not on the request path) |
| `openrouter` | OpenRouter | `OPENROUTER_API_KEY` | OpenAI-compatible `https://openrouter.ai/api/v1` |
Default. Overlay description: “Use your signed-in Cursor account.” Status is always **Signed in**; the Router panel does not probe Cursor auth. Tools stay on native Grok Bot plugins.
Resolve the `claude` executable, then sign in.
Search order for the CLI: `CLAUDE_CODE_PATH`, `~/.local/bin/claude`, `~/.claude/local/claude`, `PATH`, `/opt/homebrew/bin/claude`, `/usr/local/bin/claude`.
Status **authenticated** when `~/.claude/.credentials.json` exists or `ANTHROPIC_API_KEY` is non-empty. A turn still requires the executable; missing CLI throws `Claude Code is not installed. Install and sign in to Claude Code, then reopen Grok Bot.`
Optional model: `SAND_CLAUDE_MODEL`. Plugin tools go through the Grok Bot MCP bridge (`mcp__grok_bot_plugins__*`).
Grok Bot reads tokens and calls ChatGPT itself. The `codex` binary is only used for install/status.
Auth file: `$CODEX_HOME/auth.json` if `CODEX_HOME` is set, otherwise `~/.codex/auth.json`. The file must be a regular file (not a symlink) with no group/other bits (`mode & 0o077 === 0`). Required fields: `auth_mode === "chatgpt"` and non-empty `tokens.access_token`, `refresh_token`, `id_token`, `account_id`.
Otherwise: `Codex login credentials must be a private direct regular file.` or `Codex is not signed in with ChatGPT. Run \`codex login\`, then reopen Grok Bot.`
401 responses refresh at `https://auth.openai.com/oauth/token` and rewrite `auth.json` atomically (`mode 0o600`). Model: `SAND_CODEX_MODEL`, else `model` in `config.toml`, else `gpt-5.4`. Reasoning: `SAND_CODEX_REASONING_EFFORT` or `model_reasoning_effort` in that TOML (`minimal` \| `low` \| `medium` \| `high` \| `xhigh`).
Credential: `process.env.OPENROUTER_API_KEY`, else `OPENROUTER_API_KEY` in `box-secrets.json`. Missing key: `OpenRouter needs OPENROUTER_API_KEY. Add it in Settings → Router.`
Save from the overlay with `window.desktop.secrets.upsert({ OPENROUTER_API_KEY })` (`sand:secrets-upsert`). Environment wins over the secrets file.
Model: `SAND_OPENROUTER_MODEL` or `openai/gpt-5.2`. Tools run in the Grok Bot execution loop (`maxSteps` 8 when tools are present).
## Persist path
```mermaid
flowchart TB
subgraph renderer [Packaged Settings overlay]
Panel["RRouterPanel Provider dropdown"]
Event["sand-router-provider-changed"]
end
subgraph electron [Electron main edge]
GetIR["getInferenceRouter"]
SetIR["setInferenceRouter"]
Local["getLocalInferenceCliStatus"]
end
subgraph store [Host settings]
File["settings.json version 1"]
Field["inferenceProvider"]
Usage["inferenceRouterUsage schemaVersion 1"]
end
subgraph turns [Next turn]
Cursor["cursor createSession"]
Routed["createProviderPromptSession"]
end
Panel --> SetIR
SetIR --> Field
Field --> File
SetIR -->|"syncHostSettingsToBox best-effort"| File
GetIR --> Field
GetIR --> Usage
GetIR --> Local
GetIR --> Panel
SetIR --> Event
Field -->|"cursor"| Cursor
Field -->|"claude-code, codex, openrouter"| Routed
```
Stored on `settings.json`. Allowed: `cursor` \| `claude-code` \| `codex` \| `openrouter`. Omitted or invalid values load as `cursor`. Atomic write: `settings.json..tmp` then `rename`.
Typical packaged path is `~/.grokbot/settings.json` (`getSandProductionRootDir`). Overrides: absolute `SAND_DATA_ROOT`, or `SAND_USER_DATA_DIR` / `--user-data-dir` (then `sand-data/settings.json`). Unpackaged variant uses `~/.cursor//settings.json`.
`setInferenceRouter` always updates the local store first. `syncHostSettingsToBox({ inferenceProvider })` failures are swallowed; the RPC still returns the local provider, usage, and CLI status.
## Desktop RPC
Preload: `window.desktop.agent.getInferenceRouter()` and `window.desktop.agent.setInferenceRouter(provider)` (`setInferenceRouter` args: `{ provider }`).
:::endpoint GET getInferenceRouter
Load current route, local usage, and Claude/Codex CLI status.
**Returns**
Current `inferenceProvider`, or `cursor` if the store value is not a known id.
Box copy of `inferenceRouterUsage` when readable, else the local store. `schemaVersion` is `1`.
`installed`, `authenticated`, `executablePath` for Codex and Claude Code.
:::
:::endpoint POST setInferenceRouter
Persist a provider id.
**Body**
Must pass `isSandInferenceProvider`. Otherwise the edge throws `Unknown inference provider.`
**Returns** the same `{ provider, usage, local }` shape as get.
:::
```js title="Renderer overlay"
const current = await window.desktop.agent.getInferenceRouter();
const next = await window.desktop.agent.setInferenceRouter("openrouter");
window.dispatchEvent(new CustomEvent("sand-router-provider-changed", { detail: next }));
await window.desktop.secrets.upsert({ OPENROUTER_API_KEY: key });
```
```json title="getInferenceRouter / setInferenceRouter"
{
"provider": "openrouter",
"usage": {
"schemaVersion": 1,
"providers": {
"cursor": { "requests": 0, "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": null },
"claude-code": { "requests": 0, "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": null },
"codex": { "requests": 0, "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": null },
"openrouter": { "requests": 0, "inputTokens": 0, "outputTokens": 0, "cacheReadTokens": 0, "cacheWriteTokens": 0, "lastUsedAt": null }
}
},
"local": {
"codex": { "installed": true, "authenticated": true, "executablePath": "/opt/homebrew/bin/codex" },
"claude-code": { "installed": true, "authenticated": true, "executablePath": "/opt/homebrew/bin/claude" }
}
}
```
Routed system prompt (Claude, Codex, OpenRouter) states the process is Grok Bot, not Codex CLI or Claude Code, and that connected plugins are already available.
## Environment and secrets
| Variable | Role |
| --- | --- |
| `OPENROUTER_API_KEY` | Preferred OpenRouter credential |
| `SAND_OPENROUTER_MODEL` | OpenRouter model id; default `openai/gpt-5.2` |
| `CLAUDE_CODE_PATH` | Explicit `claude` executable |
| `ANTHROPIC_API_KEY` | Counts as Claude Code **authenticated** for status only |
| `SAND_CLAUDE_MODEL` | Optional Claude Agent SDK model |
| `CODEX_HOME` | Directory for `auth.json` and `config.toml` (default `~/.codex`) |
| `CODEX_PATH` | Codex CLI path for status only |
| `SAND_CODEX_MODEL` | Codex model override |
| `SAND_CODEX_REASONING_EFFORT` | Codex reasoning override |
| `SAND_DATA_ROOT` / `SAND_USER_DATA_DIR` | Host settings root |
## Usage & Billing
**Usage & Billing** is patched to `RRouterUsage`. It lists the current provider plus any provider with `requests > 0`. Counters (`requests`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `lastUsedAt`) are local activity, not a provider invoice. `cursor` still renders the original Cursor usage panel (`Na`) under the router summary.
## Verify
After a successful set, reopen **Settings → Router**: the dropdown matches the saved id, **Usage for \** tracks that provider, and a new chat turn follows Cursor vs `createProviderPromptSession`.
- `Unknown inference provider.` — RPC `provider` not in `SAND_INFERENCE_PROVIDERS`.
- `Claude Code is not installed. Install and sign in to Claude Code, then reopen Grok Bot.`
- `Claude Code ended without a result.` / `Claude Code failed ().`
- `Codex login credentials must be a private direct regular file.`
- `Codex is not signed in with ChatGPT. Run \`codex login\`, then reopen Grok Bot.`
- `Codex login expired and could not be refreshed. Run \`codex login\` again.`
- `OpenRouter needs OPENROUTER_API_KEY. Add it in Settings → Router.`
Full failure catalog: [Router and sandbox failures](/router-failures).
## Next
Provider ids, default `cursor`, transcript `schemaVersion` 2, usage `schemaVersion` 1.
Cursor path, Claude Agent SDK, Codex Responses URL, OpenRouter default `openai/gpt-5.2`.
`settings.json` version 1, `inferenceProvider`, usage, atomic persist.
`getInferenceRouter`, `setInferenceRouter`, secrets upsert/list.
Claude Code MCP bridge vs Codex/OpenRouter direct tool execution.
Computer toggle on the same Router page.
---
## 09. Enable the local Docker sandbox
> Toggle Use local Docker VM, start grok-bot-local-vm, wait for http://127.0.0.1:1340/health, and roll back to remote on start failure.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/09-enable-the-local-docker-sandbox.md
- Generated: 2026-08-24T05:53:07.603Z
### Source Files
- `source/electron-main/box/local-docker-host-connector.ts`
- `source/shared/box-runtime.ts`
- `source/electron-main/main-edge.ts`
- `source/electron-main/box/box-host-connector.ts`
- `scripts/lib/router-renderer-patch.mjs`
- `source/shared/node/settings/sand-settings-store.ts`
---
title: "Enable the local Docker sandbox"
description: "Toggle Use local Docker VM, start grok-bot-local-vm, wait for http://127.0.0.1:1340/health, and roll back to remote on start failure."
---
Settings → Router → **Computer** owns the local sandbox. The **Use local Docker VM** switch calls `window.desktop.agent.setBoxRuntime` with `mode` `"local-docker"` or `"remote"`. Main persists `boxRuntime` in `settings.json`, starts or stops container `grok-bot-local-vm`, waits for `GET http://127.0.0.1:1340/health` with the stored gateway token, then restarts the coordinator. A start or stop failure writes the opposite `boxRuntime` and does not restart the coordinator. Default remains `"remote"`.
Docker Desktop (or another local `docker` daemon) is optional at install time and required only for this toggle. Inference provider choice is independent: Cursor, Claude Code, Codex, and OpenRouter keep their own auth paths.
## Prerequisites
- Packaged reconstructed macOS app (the connector refuses a stock image host if `host-main.cjs` and `box-exec-daemon/main.cjs` are missing).
- Docker daemon reachable as the `docker` CLI (`docker info`).
- Loopback ports `1337`, `1339`, `1340`, `6080`, `6081`, and `8790` free on `127.0.0.1`.
- No unowned container already named `grok-bot-local-vm`.
The run uses `--platform linux/amd64`. On Apple Silicon, Docker must be able to pull and run that image. The connector binds published ports to `127.0.0.1` only.
## Enable
Open the app, then **Settings → Router**. The switch lives in the **Computer** card (`aria-label` `Use local Docker VM`, `role="switch"`).
Off copy: `Shell, files and computer use run on Grok Bot's remote computer.`
On copy: `status.detail` from `getBoxRuntime`, or `Shell, files and computer use run in a Docker container on this Mac.`
The renderer sets local UI state to `"local-docker"` and `busy: true`, then:
```ts
window.desktop.agent.setBoxRuntime("local-docker")
```
Preload forwards `{ mode }`. Main rejects any other string with `Unknown box runtime.`
`setBoxRuntime` writes `boxRuntime: "local-docker"` first, then `startLocalDockerBox`. That path:
1. Ensures a 32+ character hex token in `local-docker-vm.json` next to `settings.json`.
2. Stages content-addressed `host-main.cjs` and `box-exec-daemon/main.cjs` under `local-docker-runtime/-/`.
3. Requires `docker info`.
4. Creates or starts `grok-bot-local-vm` with owner label `com.grok-bot.local-vm=1` and schema version `6`.
5. Polls `http://127.0.0.1:1340/health` with `Authorization: Bearer ` every 1s, 2s probe timeout, 180s overall.
Ready status: `Local Docker VM is ready.`
On success, main calls `boxRecovery.restartCoordinator` and returns `{ mode, status }`. The switch stays on. The coordinator then connects through the settings-routed host connector to `http://127.0.0.1:1340` instead of the remote broker.
```json title="setBoxRuntime enable"
{ "mode": "local-docker" }
```
```json title="setBoxRuntime success"
{
"mode": "local-docker",
"status": {
"available": true,
"running": true,
"ready": true,
"containerName": "grok-bot-local-vm",
"image": "public.ecr.aws/k0i0n2g5/cursorenvironments/universal:sand-box-latest",
"detail": "Local Docker VM is ready."
}
}
```
## Disable
Turn the same switch off. Main writes `boxRuntime: "remote"`, then `stopLocalDockerBox`:
- Missing or already stopped container: no-op.
- Owned running container: `docker stop grok-bot-local-vm`.
- Running **unowned** container: throws `Refusing to stop unowned container grok-bot-local-vm.`, reverts `boxRuntime` to `"local-docker"`, and does not restart the coordinator.
Stop does **not** `docker rm` the container or delete volumes `grok-bot-local-vm-workspace` and `grok-bot-local-vm-data`. Success still restarts the coordinator so later `connect()` uses the remote host connector.
## Persist and RPC
`SandBoxRuntime` is `"remote" | "local-docker"`. `DEFAULT_SAND_BOX_RUNTIME` is `"remote"`. Invalid `boxRuntime` values in `settings.json` are dropped; load then returns the default.
Stored on `SandStoredSettings` version `1`. Written atomically via a pid-scoped temp file next to `settings.json`.
`setBoxRuntime` argument. Must pass `isSandBoxRuntime`.
Persisted runtime after a successful start or stop.
`available`, `running`, `ready`, `containerName`, `image`, `detail` from `getLocalDockerStatus`.
`getBoxRuntime` returns the stored mode plus a live Docker inspect/health snapshot. It does not start the VM.
```mermaid
sequenceDiagram
participant UI as Settings Router
participant Edge as setBoxRuntime
participant Store as settings.json
participant VM as grok-bot-local-vm
participant Health as 127.0.0.1:1340/health
participant Coord as Coordinator
UI->>Edge: mode local-docker
Edge->>Store: boxRuntime = local-docker
Edge->>VM: docker run or start
loop every 1s up to 180s
Edge->>Health: GET /health Bearer token
alt response.ok
Edge->>Coord: restartCoordinator
Edge-->>UI: mode + LocalDockerStatus
else container exited
Edge->>Store: boxRuntime = remote
Edge-->>UI: throw
end
end
```
## What the container does
Image: `public.ecr.aws/k0i0n2g5/cursorenvironments/universal:sand-box-latest`.
| Fact | Value |
| --- | --- |
| Name | `grok-bot-local-vm` |
| Gateway | `http://127.0.0.1:1340` |
| Health | `GET /health`, Bearer `SAND_GATEWAY_TOKEN` |
| Owner label | `com.grok-bot.local-vm=1` |
| Schema label | `com.grok-bot.local-vm.schema-version=6` |
| Restart policy | `unless-stopped` |
| Auto-update | `SAND_BOX_AUTO_UPDATE=0` |
| Gateway bind in-box | `SAND_GATEWAY_BIND_HOST=0.0.0.0`, `SAND_HOST_PORT=1340` |
Host mounts are read-only content-addressed files, not the stock image copies. Optional read-only binds of `~/.codex` → `/root/.codex` and `~/.claude` → `/root/.claude` apply when those directories exist. Published ports are loopback-only.
After a successful toggle, coordinator `connect()` may still call remote `issueInferenceCredential` with a 3s timeout. If a token arrives, the connector can replace the container so it mounts `local-docker-credential/inference.json`. Toggle-on `startLocalDockerBox` itself does not wait for that credential.
Computer recreate while local: `docker restart grok-bot-local-vm`, then wait for health (`started-untrackable`). Force recreate: `docker rm --force`, then create again.
## Status strings
| Condition | `available` | `running` | `ready` | `detail` |
| --- | --- | --- | --- | --- |
| `docker info` fails | `false` | `false` | `false` | CLI output, or `Docker is not running.` |
| No container | `true` | `false` | `false` | `Ready to create the local VM.` |
| Name taken, label missing | `true` | inspect | `false` | `Container grok-bot-local-vm exists but is not owned by Grok Bot.` |
| Running, health OK | `true` | `true` | `true` | `Local Docker VM is ready.` |
| Running, health not OK | `true` | `true` | `false` | `Container is starting.` |
| Owned, stopped | `true` | `false` | `false` | `Local Docker VM is stopped.` |
## Failure and rollback
Optimistic UI flips the switch immediately. If `setBoxRuntime` throws, the renderer restores the previous mode and shows `error.message`.
Main rollback: failed `"local-docker"` → persist `"remote"`; failed `"remote"` → persist `"local-docker"`. Coordinator restart runs only after start/stop succeeds.
| Error | Typical cause |
| --- | --- |
| `Unknown box runtime.` | `mode` is not `"remote"` or `"local-docker"`. |
| `Local Docker VM is selected, but Docker is unavailable: …` | Daemon not running or `docker` missing. |
| `Local Docker VM cannot use grok-bot-local-vm: an unowned container already has that name.` | Name collision; connector will not take over. |
| `Local Docker VM container uses unexpected image …` | Existing owned container image ≠ pinned image. |
| `The reconstructed runtime is unavailable … refusing to start a stock local VM.` | `host-main.cjs` / `box-exec-daemon/main.cjs` not next to the compiled main. |
| `Could not create` / `Could not start` / `Could not replace` | `docker run` / `start` / `rm --force` non-zero. |
| `Local Docker VM stopped before its gateway became ready.` | Container exited during the 180s wait; last 80 log lines attached. |
| `Local Docker VM did not expose its gateway within three minutes.` | Process still running, `/health` never OK. |
| `Refusing to stop unowned container grok-bot-local-vm.` | Disable path while a foreign container is running. |
Replace (rm + recreate) happens when schema ≠ `6`, host SHA-256 label mismatches the staged `host-main.cjs`, or an inference credential is present but the container lacks `com.grok-bot.local-vm.inference-credential=1`.
```sh
docker inspect grok-bot-local-vm --format '{{index .Config.Labels "com.grok-bot.local-vm"}} {{index .Config.Labels "com.grok-bot.local-vm.schema-version"}}'
docker logs --tail 80 grok-bot-local-vm
```
Health from the host needs the token in `local-docker-vm.json` beside `settings.json` (`schemaVersion: 1`).
## Next
`SandBoxRuntime` values, default `remote`, and coordinator restart on switch.
Image, labels, schema 6, mounts, and loopback gateway.
Unowned `grok-bot-local-vm` and other router/sandbox errors.
`getBoxRuntime` / `setBoxRuntime` on `window.desktop.agent`.
---
## 10. Route Grok Bot plugin tools
> listRoutedMcpTools and executeRoutedMcpTool across Claude Code MCP bridge versus Codex/OpenRouter direct tool execution.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/10-route-grok-bot-plugin-tools.md
- Generated: 2026-08-24T05:54:15.074Z
### Source Files
- `source/node-agent-coordinator/routed-mcp-bridge.ts`
- `source/node-agent-coordinator/inference-router.ts`
- `source/shared/rpc/coordinator.ts`
- `source/electron-main/coordinator/coordinator-executors.ts`
- `source/host/extensions/mcp/mcp-service.ts`
- `tests/backend-mcp-exec-json.test.mjs`
---
title: "Route Grok Bot plugin tools"
description: "listRoutedMcpTools and executeRoutedMcpTool across Claude Code MCP bridge versus Codex/OpenRouter direct tool execution."
---
When `inferenceProvider` is `claude-code`, `codex`, or `openrouter`, a non-Cursor `sendPrompt` is handled in the node-agent coordinator. That turn lists already-connected Grok Bot plugins with `listRoutedMcpTools` and runs model-selected tools with `executeRoutedMcpTool`. Cursor turns do not use this intercept: they keep the native host MCP executor.
Routed plugin tools are the plugins and HTTP/SSE accounts already installed in Grok Bot. The model is instructed not to ask the user to reconnect those plugins or supply API keys for them.
## Prerequisites
Install and authenticate plugins in the shipped Plugins UI. Routed providers reuse that catalog; they do not start a separate MCP config for Claude Code, Codex, or OpenRouter.
Set Settings → Router to `claude-code`, `codex`, or `openrouter`. `cursor` (default) skips this routing path.
Claude Code must be installed and signed in. Codex needs a private `auth.json` under `CODEX_HOME` or `~/.codex`. OpenRouter needs `OPENROUTER_API_KEY` in the environment or Settings → Router secrets.
## How a routed turn uses plugins
On `sendPrompt`, `createCoordinatorInferenceRouter` queues one turn per `agentId`, then:
1. Lists tools (or starts the Claude Code HTTP MCP bridge that lists them on `tools/list`).
2. Calls `runRoutedProviderText` with either `mcpServerUrl` (Claude Code) or `{ tools, executeTool }` (Codex and OpenRouter).
3. Forwards each tool call over desktop control RPC as `executeRoutedMcpTool`.
4. Closes the Claude Code bridge in `finally`.
Coordinator `dispatchRemote` sends those two methods through Electron control commands, not through the host gateway. Missing desktop wiring throws `Desktop MCP routing is unavailable.`
```mermaid
flowchart TB
subgraph Renderer["Renderer"]
Send["sendPrompt"]
end
subgraph Coordinator["node-agent-coordinator"]
Router["createCoordinatorInferenceRouter"]
Bridge["createRoutedMcpBridge\nhttp://127.0.0.1:<port>/mcp/<uuid>"]
Direct["runRoutedProviderText\ntools + executeTool"]
end
subgraph Desktop["electron-main control RPC"]
Exec["listRoutedMcpTools\nexecuteRoutedMcpTool"]
Mgr["createSandDesktopMcpManager"]
end
subgraph Backend["Cursor dashboard MCP"]
List["listSandMcpTools"]
Call["executeSandMcpTool"]
end
Send --> Router
Router -->|"provider === claude-code"| Bridge
Router -->|"codex or openrouter"| Direct
Bridge -->|"JSON-RPC tools/list and tools/call"| Exec
Direct --> Exec
Exec --> Mgr
Mgr --> List
Mgr --> Call
```
Coordinator RPC contract:
| Method | Args | Reply |
| --- | --- | --- |
| `listRoutedMcpTools` | none | array |
| `executeRoutedMcpTool` | object | record |
Telemetry domain for both methods is `plugins`.
## Provider execution modes
| Provider | Tool surface | Max tool steps | Executor |
| --- | --- | --- | --- |
| `claude-code` | Loopback MCP HTTP server `grok_bot_plugins` | `maxTurns` 8 when the bridge URL is set, else 1 | Claude Agent SDK `query` with `tools: ["mcp__grok_bot_plugins__*"]`, `strictMcpConfig: true`, `permissionMode: "default"`, `persistSession: false` |
| `codex` | Direct function tools on `https://chatgpt.com/backend-api/codex/responses` | `maxSteps` 8 when tools exist, else 1 | `streamCodexDirectResponses` with `tool_choice: "auto"` and `parallel_tool_calls: true` |
| `openrouter` | AI SDK `tool()` set | `maxSteps` 8 when tools exist, else 1 | `streamText` against `https://openrouter.ai/api/v1`, model `SAND_OPENROUTER_MODEL` or `openai/gpt-5.2` |
| `cursor` | Native host MCP (`getTools` / `SandMcpExecutor`) | n/a on this path | Not intercepted |
The coordinator binds `createRoutedMcpBridge` only for `claude-code`. The server listens on `127.0.0.1` with an ephemeral port and a UUID path secret.
- Accepts `POST /mcp/` only. Other methods/paths return 404.
- Body limit is 1,048,576 bytes (413 if exceeded). Invalid JSON returns 400.
- `initialize` reports `protocolVersion: "2025-03-26"`, `serverInfo.name: "grok-bot-plugins"`, `capabilities.tools.listChanged: false`.
- `tools/list` calls `listRoutedMcpTools` and caches tools by `name`.
- `tools/call` looks up that cache and calls `executeRoutedMcpTool` with the selected tool, `arguments`, a new `toolCallId`, and the current `agentId`.
- Unknown names return MCP `{ isError: true, content: [{ type: "text", text: "Unknown Grok Bot plugin tool: …" }] }`.
Read-only annotations are a name/description heuristic (`read`, `search`, `list`, … without `send`, `create`, `delete`, …): `readOnlyHint` / `idempotentHint` versus `destructiveHint` / `openWorldHint`.
For `codex` and `openrouter`, the coordinator loads `listRoutedMcpTools` once per turn and passes the array into `runRoutedProviderText`.
Each definition needs a non-empty `name` and `inputSchema` (or `parameters`). The model calls the Grok Bot `name`. Execution always goes back through `executeRoutedMcpTool` with:
- `providerIdentifier`
- `name`
- `toolName`
- `args`
- `toolCallId`
- `agentId`
Codex continues the Responses stream with `function_call_output` using the exact `call_id`. Unknown names become `{ isError: true, error: "Unknown Grok Bot tool: …" }`. Missing `executeTool` when Codex requests a tool throws `Codex requested a tool but Grok Bot did not provide an executor.`
Shared system text (`GROK_ROUTER_SYSTEM_PROMPT`) states the process is Grok Bot, not Codex CLI or Claude Code, and that supplied tools are already-connected plugins.
## RPC and wire shapes
### `listRoutedMcpTools`
No arguments. Desktop implementation is `listRoutedTools()` on `createSandDesktopMcpManager`: a warmed snapshot from `createMcpToolsDiscovery().getTools()`, or a live discovery if the snapshot is still empty. Discovery starts at manager construction; failures report desktop-edge `routed-tools-warm`.
Grok Bot tool id the model calls (also the Claude MCP tool name).
MCP server / account identifier (HTTP backend uses this as `serverIdentifier`).
Provider-native tool name (used for disable checks and custom-instruction lookup).
Optional. The Claude bridge defaults to `` `${toolName} via ${providerIdentifier}` ``.
JSON Schema. The Claude bridge falls back to `{ type: "object", additionalProperties: true }`.
Host gateway listing (also used by `refreshMcp` with `routedAction: "list-tools"`) maps protobuf `inputSchema.toJson()` when present and merges `listConnectedBackendTools()` with discovery, first `name` wins.
### `executeRoutedMcpTool`
Server identifier of the installed plugin/account.
Grok Bot tool id. HTTP backend execution sends this field as `toolName` to `executeSandMcpTool`.
Native tool name. Disable lists in `settings.json` `mcpDisabledToolsByServerId` match this value.
JSON arguments. Nested protobuf-like values with `toJson()` are flattened before backend serialization.
Call id. The Claude bridge generates a UUID when Claude omits one.
Current agent. Passed as MCP exec audit identity; backend `agentId` defaults to `""` if omitted.
```json title="executeRoutedMcpTool"
{
"providerIdentifier": "user-Gmail",
"name": "gmail_search",
"toolName": "search_threads",
"args": { "query": "in:inbox", "pageSize": 1 },
"toolCallId": "call-1",
"agentId": "agent-1"
}
```
Backend `executeSandMcpTool` requires a protobuf `Struct`. Routed JSON is converted with `Struct.fromJson` at `createDashboardSandBackendMcpExec` so Connect never receives a plain object. List timeout is 60s; execute timeout is 180s (`3 * MCP_SDK_REQUEST_TIMEOUT_MS`). Deadline exceeded returns a timeout error that warns the connector may already have applied the call.
MCP results from the Claude bridge unwrap `{ result: { case: "success", value } }` into MCP `content` (`text` / `image`) plus optional `structuredContent`. Non-success cases become `{ isError: true, content: [{ type: "text", text }] }`.
## Where tools actually run
Desktop discovery is the path the coordinator uses:
| Transport | List | Execute from routed providers |
| --- | --- | --- |
| HTTP / SSE | Cursor `listSandMcpTools` | Cursor `executeSandMcpTool` |
| Box stdio | Desktop `boxMcpExec.listTools` returns servers with `tools: []` | Desktop stub: `MCP tools run on Grok Bot's computer, not the desktop app (tool "…").` |
HTTP/SSE plugins are the tools routed providers can call. Stdio servers still run on the box for Cursor-native turns, not through this desktop RPC.
Disabled tools (`mcpDisabledToolsByServerId`) are omitted from lists. Execute of a disabled `toolName` returns `Tool "" is disabled for "".` Successful results may prepend the server's custom instruction note from `mcpCustomInstructionsByServerId` (fallback: legacy `mcpCustomInstructions` by display name).
Tool cache TTL is 24 hours (`MCP_TOOLS_CACHE_TTL_MS`). Full discovery deadline is 120 seconds.
The host process also registers gateway commands `listRoutedMcpTools` / `executeRoutedMcpTool` and `refreshMcp` aliases `list-tools` / `execute-tool`. Those host helpers are not what the inference router calls for a routed turn.
## Failure modes
| Condition | Behavior |
| --- | --- |
| Desktop MCP adapters unset | `Desktop MCP routing is unavailable.` |
| Claude Code CLI missing | `Claude Code is not installed. Install and sign in to Claude Code, then reopen Grok Bot.` |
| Codex `auth.json` not a private regular file | `Codex login credentials must be a private direct regular file.` |
| Missing OpenRouter key | `OpenRouter needs OPENROUTER_API_KEY. Add it in Settings → Router.` |
| Backend list failure | `Backend MCP tool discovery failed: …` |
| Backend execute timeout | Timeout message after 180s; retry only if the connector call is safe to repeat |
| HTTP server unknown here | `MCP server "" is not available here. HTTP/SSE servers execute on the backend and stdio servers run on Grok Bot's computer; …` |
| Routed `sendPrompt` throws | Coordinator appends `Router error: …` as an assistant transcript row |
`cursor` does not list or execute plugins through this coordinator path. Switching Router away from Cursor is what attaches Grok Bot plugins to Claude Code, Codex, or OpenRouter.
## Related pages
Provider ids, transcript store, and the `sendPrompt` intercept that owns this tool routing.
Persist `inferenceProvider` and satisfy Cursor, Claude Code, Codex, or OpenRouter login.
Claude Agent SDK, Codex Responses, and OpenRouter OpenAI-compatible clients used after tools are listed.
`mcpCustomInstructions*`, `mcpDisabledToolsByServerId`, and `inferenceProvider`.
Control-channel shape used by coordinator `listRoutedMcpTools` / `executeRoutedMcpTool`.
Unknown provider, missing Claude Code, private Codex `auth.json`, and OpenRouter key errors.
---
## 11. Bootstrap the pinned runtime
> npm run bootstrap order: GROK_BOT_018_APP, cached app, LFS DMG, then public URL; verify DMG and app.asar SHA-256; hydrate src/app/dist.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/11-bootstrap-the-pinned-runtime.md
- Generated: 2026-08-24T05:54:05.953Z
### Source Files
- `scripts/bootstrap-runtime.mjs`
- `scripts/lib/runtime.mjs`
- `scripts/lib/config.mjs`
- `tests/publication-bootstrap.test.mjs`
- `research-archives/original/0.18.0/artifacts.json`
- `research-archives/README.md`
---
title: "Bootstrap the pinned runtime"
description: "npm run bootstrap order: GROK_BOT_018_APP, cached app, LFS DMG, then public URL; verify DMG and app.asar SHA-256; hydrate src/app/dist."
---
`npm run bootstrap` runs `node scripts/bootstrap-runtime.mjs`. That script materializes a checksum-pinned Grok Bot **0.18.0** macOS arm64 Electron app into `.cache/runtime/Grok Bot.app`, then extracts `Contents/Resources/app.asar` into ignored `src/app/dist` after verifying the ASAR SHA-256. Later packaging (`npm run package`) copies that hydrated `src/app` tree and refuses to start without the cached 0.18.0 runtime.
Bootstrap is a local, content-addressed input step. It does not choose an inference provider, start Docker, or write `dist/Grok Bot 0.18 Reconstructed.app`.
## Prerequisites
| Requirement | Why bootstrap needs it |
| --- | --- |
| macOS Apple Silicon | The pinned installer is `darwin-arm64`. Extraction uses `/usr/bin/hdiutil`, `/usr/bin/ditto`, and `/usr/bin/plutil`. |
| Node `>=26.5.0 <27` | `package.json` `engines.node` |
| Git LFS | Preserved DMG at `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg` |
| `npm ci` | `@electron/asar` is used to unpack `app.asar` |
```sh
git lfs install
git lfs pull
npm ci
npm run bootstrap
```
Optional: skip the DMG path by pointing `GROK_BOT_018_APP` at an already installed `Grok Bot.app` whose `CFBundleShortVersionString` is `0.18.0`.
## Resolution order
The script picks **one** runtime source, then always hydrates `src/app/dist` from that app's `app.asar`.
```mermaid
flowchart TD
start([npm run bootstrap]) --> env{"GROK_BOT_018_APP set?"}
env -->|yes| copyEnv["ditto into .cache/runtime/Grok Bot.app"]
env -->|no| cachedApp{".cache/runtime/Grok Bot.app exists?"}
cachedApp -->|yes| validateCached["validateRuntimeApp"]
cachedApp -->|no| dmg["downloadDmg"]
dmg --> cachedDmg{".cache/downloads/Grok_Bot_0.18.0.dmg matches pin?"}
cachedDmg -->|yes| attach
cachedDmg -->|no| lfs{"LFS archive exists?"}
lfs -->|yes| verifyLfs["SHA-256 then copy to cache"]
lfs -->|no| fetchUrl["GET dmgUrl → .partial → rename"]
verifyLfs --> attach["hdiutil attach Grok Bot.app"]
fetchUrl --> attach
attach --> copyDmg["ditto into .cache/runtime/Grok Bot.app"]
copyEnv --> hydrate
validateCached --> hydrate
copyDmg --> hydrate["hydrateSourcePayloadFromRuntime"]
hydrate --> asarPin{"app.asar SHA-256 == upstreamAsarSha256?"}
asarPin -->|yes| dest["replace src/app/dist"]
asarPin -->|no| failAsar["throw checksum mismatch"]
```
### 1. `GROK_BOT_018_APP`
Absolute or relative path to a `Grok Bot.app` bundle. The value is trimmed; empty/whitespace is ignored.
When set, bootstrap never downloads a DMG. It validates the path, deletes any previous `.cache/runtime/Grok Bot.app`, and copies the bundle with `/usr/bin/ditto`.
### 2. Cached app
If the env var is unset and `.cache/runtime/Grok Bot.app` already exists, bootstrap only re-validates that copy.
### 3. Cached DMG, then LFS, then public URL
If no cached app exists, `downloadDmg()` fills `.cache/downloads/Grok_Bot_0.18.0.dmg`:
1. Reuse the cached DMG when its SHA-256 already matches the pin. A mismatched cache file is deleted.
2. If `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg` exists, hash it. On match, copy it into the cache. On mismatch, throw and tell you to `git lfs pull`.
3. Otherwise `fetch()` the public URL with `redirect: "follow"`, write `.cache/downloads/Grok_Bot_0.18.0.dmg.partial` at mode `0o600`, verify SHA-256, then rename into the cache. A failed HTTP response or digest mismatch deletes the partial file.
The Windows `setup.exe` in the same archive is **not** a bootstrap input.
### 4. Extract `Grok Bot.app` from the DMG
`hdiutil attach -readonly -nobrowse -mountpoint` mounts the cached DMG under a temp directory named `grok-bot-018-mount-*`. Bootstrap copies `/Grok Bot.app` into the runtime cache, then detaches and removes the mountpoint.
## Pinned identities
Constants live in `scripts/lib/config.mjs` and must match `research-archives/original/0.18.0/artifacts.json` (`schemaVersion` `1`) for the macOS artifact.
| Pin | Value |
| --- | --- |
| `upstreamVersion` | `0.18.0` |
| `dmgUrl` | `https://downloads.cursor.com/grokbot/stable/darwin-arm64/0.18.0/Grok_Bot_0.18.0.dmg` |
| `dmgSha256` | `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| `upstreamAsarSha256` | `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58` |
| macOS archive bytes | `155793020` |
Independent check of the LFS files (not performed by bootstrap itself):
```sh
(cd research-archives/original/0.18.0 && shasum -a 256 -c SHA256SUMS)
```
`tests/research-archives.test.mjs` also requires each installer byte length to equal `artifacts.json` `bytes`. A Git LFS pointer file fails that size check.
## Runtime validation
`validateRuntimeApp()` runs on every accepted app (env copy, cache hit, or DMG extract):
| Check | Path / tool |
| --- | --- |
| Version | `plutil -extract CFBundleShortVersionString raw Contents/Info.plist` must equal `0.18.0` |
| Executable | `Contents/MacOS/Grok Bot` must be a file |
| Unpacked natives | `Contents/Resources/app.asar.unpacked` must be a directory |
Failure messages:
- `Expected Grok Bot 0.18.0, got at `
- `Incomplete Grok Bot runtime at `
Packaging later calls `resolveRuntimeApp()`. If `GROK_BOT_018_APP` is unset and the cache is missing, it throws `Missing 0.18.0 runtime. Run \`npm run bootstrap\` first.`
## Hydrate `src/app/dist`
`hydrateSourcePayloadFromRuntime()` hashes `Contents/Resources/app.asar` as raw bytes. The digest must equal `upstreamAsarSha256`. It then:
1. Extracts the archive under `.cache/source-payloads/grok-bot-018-*`.
2. Requires these files to exist as regular files:
- `dist/electron-main/main.cjs`
- `dist/host/host-main.cjs`
- `dist/renderer/index.html`
3. Deletes `src/app/dist` if present and copies only the archive's `dist/` tree there (`dereference: false`, timestamps preserved).
4. Deletes the temporary extract directory.
Checked-in `src/app/package.json` is not replaced. `/src/app/dist/` and `/.cache/` are gitignored; do not add the hydrated tree.
Hydration is the shipped renderer and compiled payload, not `frontend/`. Packaged UI stays this checksum-pinned `dist/renderer` unless a later packaging override is set.
`tests/publication-bootstrap.test.mjs` asserts a matching SHA-256 hydrates `dist/renderer/index.html` and that a wrong `expectedSha256` rejects with `/checksum mismatch/`.
## Paths and outputs
:::files
repo/
├── research-archives/original/0.18.0/
│ ├── artifacts.json
│ ├── SHA256SUMS
│ └── macos-arm64/Grok_Bot_0.18.0.dmg # Git LFS
├── src/app/
│ ├── package.json # checked in
│ └── dist/ # hydrated, gitignored
└── .cache/
├── downloads/Grok_Bot_0.18.0.dmg
├── runtime/Grok Bot.app
└── source-payloads/grok-bot-018-*/
:::
```sh
npm run bootstrap
```
```text
Using archived release .../research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg
Runtime ready: .../.cache/runtime/Grok Bot.app
Checksum-pinned source payload ready: .../src/app/dist (6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58)
The checksum-pinned app supplies only the Electron shell, ABI-matched native dependencies, and explicitly documented build fallbacks.
```
When the LFS file is absent and the cache is empty, the first log line is `Downloading https://downloads.cursor.com/grokbot/stable/darwin-arm64/0.18.0/Grok_Bot_0.18.0.dmg` instead of `Using archived release`.
## What packaging consumes next
`scripts/lib/build-asar.mjs` copies the whole `src/app` directory (including hydrated `dist/`) into `.build/app`, then overlays ABI-matched `deps` and `native` trees from the cached app's `app.asar.unpacked`. The bootstrap console line is literal: the cached app is the Electron shell, native ABI, and documented fallbacks—not reconstructed TypeScript under `source/`.
## Failures bootstrap throws
| Symptom | Typical cause | What to do |
| --- | --- | --- |
| `Archived DMG checksum mismatch ... Run git lfs pull` | Pointer-sized or corrupt LFS object | `git lfs pull`, then `shasum -a 256 -c SHA256SUMS` |
| `DMG checksum mismatch` after download | Truncated or substituted URL payload | Delete `.cache/downloads/Grok_Bot_0.18.0.dmg*` and retry |
| `Download failed: HTTP ` | Public URL unavailable | Use LFS or `GROK_BOT_018_APP` |
| `Expected Grok Bot 0.18.0, got …` | Wrong app behind `GROK_BOT_018_APP` or stale cache | Point at 0.18.0 or remove `.cache/runtime` |
| `Incomplete Grok Bot runtime` | Missing `Contents/MacOS/Grok Bot` or `app.asar.unpacked` | Re-extract from the pinned DMG |
| `Upstream app.asar checksum mismatch` | ASAR is not the 0.18.0 pin | Do not bypass the hash; replace the runtime |
| `Upstream app.asar is missing dist/…` | Archive contents incomplete | Fail closed; do not hand-copy files into `src/app/dist` |
Full failure catalog: [Bootstrap failures](/bootstrap-failures).
## Next
Compile reconstructed runtimes, replace app.asar, ad-hoc sign, and verify.
LFS pointers, checksum mismatches, version errors, and missing ASAR files.
artifacts.json schemaVersion 1, LFS DMG/EXE identities, SHA256SUMS.
Ignored src/app/dist hydration versus compiled source/ runtimes.
---
## 12. Package the macOS app
> npm run package compiles runtimes, patches Settings Router, replaces app.asar, sets reconstructed identity, ad-hoc signs, and verifies.
- Page Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/pages/12-package-the-macos-app.md
- Generated: 2026-08-24T05:54:33.562Z
### Source Files
- `scripts/package-macos.mjs`
- `scripts/clean-build.mjs`
- `scripts/lib/codesign.mjs`
- `scripts/lib/macos-package-verification.mjs`
- `scripts/lib/build-asar.mjs`
- `scripts/lib/router-renderer-patch.mjs`
- `tests/publication-packaging.test.mjs`
---
title: "Package the macOS app"
description: "npm run package compiles runtimes, patches Settings Router, replaces app.asar, sets reconstructed identity, ad-hoc signs, and verifies."
---
`npm run package` runs `npm run check`, then `node scripts/package-macos.mjs`. That script aborts unless `process.platform === "darwin"`, builds a **fidelity-hybrid** ASAR (`buildKind: "fidelity-hybrid-reconstruction"`), copies the checksum-pinned 0.18 Electron shell with `/usr/bin/ditto`, replaces `Contents/Resources/app.asar` and `app.asar.unpacked`, rewrites reconstructed identity in `Info.plist`, ad-hoc signs with `codesign --sign -`, and verifies the result.
Default output:
```text
dist/Grok Bot 0.18 Reconstructed.app
```
The official cached `Grok Bot.app` is **reference-only**. Packaging copies its ABI-matched shell and helpers, then must **not** keep the official signed `Contents/MacOS/Grok Bot` identity or the official `app.asar` SHA-256.
Packaging is macOS Apple Silicon only. On any other platform the script throws: `The reconstructed macOS application can only be packaged on macOS.`
## Prerequisites
Apple Silicon macOS, Node `>=26.5.0 <27`, Xcode Command Line Tools (`/usr/bin/codesign`, `/usr/bin/ditto`, `/usr/bin/plutil`, `/usr/bin/xattr`), and Git LFS.
Run `npm run bootstrap` so the cached app, official `app.asar`, and ignored `src/app/dist` renderer exist and match the pinned SHA-256 identities.
`npm ci` then `npm run check` (the package script already runs check first: frontend typecheck, `source/` typecheck, and `tests/*.test.mjs`).
## Command
```sh
npm run package
```
Equivalent:
```sh
npm run check && node scripts/package-macos.mjs
```
Success log (counts come from `runtime-deps-manifest.json` and the unpacked runtime snapshot):
```text
Packaged application: dist/Grok Bot 0.18 Reconstructed.app ( native manifest entries, unpacked runtime files)
```
Override the `.app` basename with `GROK_BOT_OUTPUT_APP_NAME` (the value is passed through `path.basename`). Leave `CFBundleName` / `CFBundleExecutable` as `Grok Bot`: Electron derives nested helper names from that string, and this fork reuses the ABI-matched 0.18 runtime.
Optional. Basename of the bundle under `dist/`. Default: `Grok Bot 0.18 Reconstructed.app`.
Optional. Schema version 1 host production-binding manifest. Unbound slots keep host in `artifact-fallback` mode; no inferred native fallback.
Optional override. If unset and `manifests/reconstruction/electron-main-production-bindings-manifest.json` exists, that path is used. Unbound slots keep Electron main in `artifact-fallback`.
Optional repo-relative directory with `index.html`. Replaces staged `dist/renderer` during ASAR staging. Default packaging does **not** use `frontend/` Vite output; it keeps the checksum-pinned shipped renderer plus the Settings Router patch.
## Pipeline
```mermaid
flowchart TB
subgraph gate [Gate]
CHK["npm run check"]
DAR["darwin only"]
end
subgraph compile [Clean-source compile]
SRC["source/*.ts"]
FID[".build/fidelity-clean-runtime"]
ACT["host / electron-main activation"]
end
subgraph renderer [Renderer authority]
ART["src/app/dist/renderer"]
PROV["dist/renderer-artifact-provenance.json"]
PATCH["applyOriginalRendererRouterPatch"]
EXT["dist/renderer-router-extension.json"]
end
subgraph shell [Official 0.18 shell]
RT["cached Grok Bot.app"]
DITTO["ditto + xattr -cr"]
end
subgraph identity [Reconstructed identity]
ASAR["replace app.asar + unpacked"]
PLIST["com.anysphere.sand.reconstructed"]
SIGN["codesign --sign -"]
VER["verify shell, unpacked runtime, signature"]
end
CHK --> DAR --> SRC --> FID --> ACT
ART --> PROV
FID --> PATCH
ART --> PATCH --> EXT
RT --> DITTO --> ASAR --> PLIST --> SIGN --> VER
EXT --> ASAR
ACT --> ASAR
```
### 1. Compile reconstructed runtimes
`buildFidelityReconstructedAsar()` stages the bootstrapped app tree, then overlays a fidelity clean distribution:
| Runtime | Packaged path | Default mode |
| --- | --- | --- |
| electron-main | `dist/electron-main/main.cjs` | `artifact-fallback` unless production bindings validate, then `clean-source` |
| host | `dist/host/host-main.cjs` | same activation rule |
| primary / dev-controls / webview / VNC preloads | `dist/electron-preload/*.cjs` | `clean-source` |
| node-agent-coordinator | `dist/node-agent-coordinator/main.cjs` | `clean-source` |
| host workers | agent-store, transcript-mirror, box-store-vacuum, search-index | `clean-source` |
| box-exec-daemon / local-exec-daemon | `dist/box-exec-daemon/main.cjs`, `dist/local-exec-daemon/main.cjs` | `clean-source` |
| renderer | `dist/renderer` | `checksum-pinned-artifact-runtime` |
| electron-runtime-dependencies | `dist/deps` | `artifact-runtime` (copied from 0.18 unpacked) |
| node-runtime-dependencies | `dist/node-deps` | `generated-runtime` (local Node ABI tree-sitter rebuild) |
| native-runtime-tools | `dist/native` | `artifact-runtime` |
| electron-shell | `Contents/Frameworks/Electron Framework.framework` | `artifact-runtime` |
`dist/deps/node_modules/node-gyp-build` is a byte-exact sibling copy recorded as `resolutionClosure.mode: "byte-exact-sibling-package-copy"` in `dist/deps/runtime-deps-manifest.json`.
The composition audit is packed at `dist/runtime-composition-audit.json`. `dist/reconstruction-build.json` is rewritten to `schemaVersion: 2` after the audit is attached.
Clean-source executables carry a `// Deterministic clean-source` banner. Artifact-fallback Electron main is the immutable evidence bundle plus an explicit reconstructed transform (updater/telemetry guard and optional `GROK_BOT_RECONSTRUCTED_DEV` seams). When Electron main activates as `clean-source` with `reconstructedPackage: true`, the same updater guard is prepended to the bundled `main.cjs`.
### 2. Patch Settings Router into the shipped renderer
Default packaging does **not** swap in the Vite `frontend/` workspace. It copies the exact 0.18 renderer from `src/app/dist/renderer`, then `applyOriginalRendererRouterPatch` edits **exactly one** settings-registry chunk and **exactly one** settings-panel chunk.
Transforms:
| Transformation | Effect |
| --- | --- |
| `settings-registry` | Inserts `{id:"router",label:"Router",icon:"git-branch"}` between General and Usage |
| `router-panel` | Inserts `RRouterPanel` / `RBoxRuntime` and wires `x==="router"` |
| `usage-panel` | Routes Usage to `RRouterUsage` (Cursor usage UI remains when provider is `cursor`) |
Provider ids in the injected UI: `cursor`, `claude-code`, `codex`, `openrouter`. The panel talks to `window.desktop.agent.getInferenceRouter` / `setInferenceRouter`, `getBoxRuntime` / `setBoxRuntime`, and `window.desktop.secrets.list` / `upsert`. Missing or ambiguous minified anchors throw: `Original renderer
