# Overview

> What this reconstruction exposes, who can run it, the hybrid runtime split, and the first docs routes after clone.

- Repository: sashimikun/grok-bot-0.18-reconstructed
- GitHub: https://github.com/sashimikun/grok-bot-0.18-reconstructed
- Human docs: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/llms-full.txt

## 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.

<Warning>
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.
</Warning>

## 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) |

<Note>
`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.
</Note>

## 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

<Steps>
<Step title="Install prerequisites">
Node 26.5.x, Xcode Command Line Tools, Git LFS. Docker only if you will toggle local-docker.
</Step>
<Step title="Clone and hydrate LFS">

```sh
git clone <your-repository-url>
cd grok-bot-0.18-reconstructed
git lfs install
git lfs pull
npm ci
```

</Step>
<Step title="Bootstrap the pinned 0.18.0 runtime">

```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 (...)
```

</Step>
<Step title="Check, package, open">

```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`).
</Step>
</Steps>

:::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

<CardGroup>
<Card title="Installation" href="/installation">
macOS Apple Silicon prerequisites, Node 26.5.x, Git LFS, Xcode tools, optional Docker, and npm ci.
</Card>
<Card title="Quickstart" href="/quickstart">
Clone, LFS pull, bootstrap, check, package, and open the reconstructed app with the expected success signal.
</Card>
<Card title="Reconstruction boundary" href="/reconstruction-boundary">
Compiled `source/` runtimes, checksum-pinned shipped renderer, bundle id `com.anysphere.sand.reconstructed`, ignored `src/app/dist`.
</Card>
<Card title="Inference router" href="/inference-router">
Provider ids, default `cursor`, transcript `schemaVersion` 2, usage `schemaVersion` 1.
</Card>
<Card title="Box runtime" href="/box-runtime">
`remote` vs `local-docker`, coordinator restart on switch, loopback-only local gateway.
</Card>
<Card title="Evidence and provenance" href="/evidence-and-provenance">
Pinned DMG and `app.asar` SHA-256 identities, evidence-only UI rule, production bindings.
</Card>
</CardGroup>