# Quickstart

> Clone, LFS pull, bootstrap, check, package, and open dist/Grok Bot 0.18 Reconstructed.app with the expected success signal.

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

<Warning>
Packaging aborts unless `process.platform === "darwin"`. The pinned installer is macOS arm64. Node must satisfy `>=26.5.0 <27`.
</Warning>

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

<Steps>
<Step title="Clone the reconstruction">

```sh
git clone https://github.com/sashimikun/grok-bot-0.18-reconstructed.git
cd grok-bot-0.18-reconstructed
```

</Step>
<Step title="Materialize Git LFS installers">

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

<RequestExample>
```sh
cd research-archives/original/0.18.0 && shasum -a 256 -c SHA256SUMS
```
</RequestExample>

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

</Step>
<Step title="Install lockfile dependencies">

```sh
npm ci
```

`postinstall` applies third-party patches. Do not commit `.cache/`, `.build/`, `dist/`, or `src/app/dist/`.

</Step>
</Steps>

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

<ParamField body="GROK_BOT_018_APP" type="string">
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`.
</ParamField>

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

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

<ParamField body="GROK_BOT_OUTPUT_APP_NAME" type="string">
Optional basename under `dist/`. Default output is `dist/Grok Bot 0.18 Reconstructed.app`.
</ParamField>

<ResponseExample>
```text
Packaged application: …/dist/Grok Bot 0.18 Reconstructed.app (N native manifest entries, M unpacked runtime files)
```
</ResponseExample>

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

<CardGroup>
<Card title="Installation" href="/installation">
macOS Apple Silicon, Node 26.5.x, Git LFS, Xcode tools, optional Docker, and `npm ci`.
</Card>
<Card title="Bootstrap the pinned runtime" href="/bootstrap-pinned-runtime">
Full `GROK_BOT_018_APP` / cache / LFS / URL order and SHA-256 gates.
</Card>
<Card title="Package the macOS app" href="/package-macos-app">
Renderer patch, ASAR replace, reconstructed identity, ad-hoc sign, verify.
</Card>
<Card title="Verify and smoke" href="/verify-and-smoke">
Required ASAR paths, evidence markers, 12s native e2e, updater guards.
</Card>
<Card title="Choose an inference provider" href="/choose-inference-provider">
Settings → Router persistence and Cursor / Claude Code / Codex / OpenRouter auth.
</Card>
<Card title="Bootstrap failures" href="/bootstrap-failures">
Pointer-sized archives, DMG/asar mismatches, version and hydration errors.
</Card>
</CardGroup>