# Installation

> Install paths for the macOS desktop DMG and the `@inkeep/open-knowledge` npm CLI, including Node.js 24+, git, and Bun toolchain prerequisites for contributors.

- Repository: sashimikun/open-knowledge
- GitHub: https://github.com/sashimikun/open-knowledge
- Human docs: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/llms-full.txt

## Source Files

- `README.md`
- `packages/cli/package.json`
- `packages/cli/scripts/postinstall.mjs`
- `packages/desktop/package.json`
- `.node-version`
- `.bun-version`
- `docs/content/get-started/quickstart.mdx`

---

---
title: "Installation"
description: "Install paths for the macOS desktop DMG and the `@inkeep/open-knowledge` npm CLI, including Node.js 24+, git, and Bun toolchain prerequisites for contributors."
---

Open Knowledge ships on two consumer install surfaces: a signed **macOS arm64 DMG** that installs the Electron desktop app (with a bundled `ok` CLI), and the **`@inkeep/open-knowledge`** npm package that exposes `ok` and `open-knowledge` on your PATH for Linux, Windows, and Intel Mac. Contributors clone the monorepo and use **Bun 1.3.13+** and **Node.js 24+** as the build toolchain.

## Install paths

| Surface | Audience | Host requirements | Delivers |
| --- | --- | --- | --- |
| macOS DMG (`Open-Knowledge-arm64.dmg`) | Apple Silicon Mac users who want a native app | macOS on Apple Silicon (M1+), `git` | Desktop editor, auto-update, bundled `ok` via `ELECTRON_RUN_AS_NODE` |
| npm global (`@inkeep/open-knowledge`) | Linux, Windows, Intel Mac, or terminal-first macOS users | Node.js 24+, `git` | `ok` / `open-knowledge` CLI, local web editor, MCP server |
| Monorepo clone | Contributors and package maintainers | Bun 1.3.13+, Node.js 24+, `git` | Full workspace for app, CLI, server, desktop, and docs development |

<Note>
The desktop DMG is **arm64-only** today. Intel Mac users should install the npm CLI and run the editor as a local web app in the browser.
</Note>

## Prerequisites

| Dependency | End users | Contributors | Notes |
| --- | --- | --- | --- |
| **Node.js** | 24+ (CLI path only) | 24+ | Pinned in `.node-version` and `engines.node` across packages. Desktop app users do not need a separate Node install. |
| **git** | Required | Required | Minimum version `2.31.0`. Used for project initialization, timeline, and GitHub sync. |
| **Bun** | Not required | 1.3.13+ | Monorepo package manager and build runner. Pinned in `.bun-version` and root `packageManager`. |

<Warning>
Running the CLI on Node.js versions below 24 violates the published `engines` constraint. Installs may succeed, but runtime behavior is unsupported.
</Warning>

## macOS desktop app (DMG)

The desktop build targets **Apple Silicon only** (`arch: [arm64]`) and publishes a stable, version-less asset name so `releases/latest/download/` resolves consistently.

<Steps>

<Step title="Download the DMG">

Download the latest arm64 DMG from GitHub Releases:

```
https://github.com/inkeep/open-knowledge/releases/latest/download/Open-Knowledge-arm64.dmg
```

</Step>

<Step title="Install to Applications">

Open the DMG, drag **Open Knowledge** to **Applications**, and launch the app from Launchpad or Spotlight.

The DMG layout includes a drag-to-Applications alias. The shipped `.app` is code-signed and notarized for Gatekeeper.

</Step>

<Step title="Verify the install">

Launch **Open Knowledge** and confirm the app opens without Gatekeeper warnings. The desktop bundle ships:

- The editor UI (Vite build from `packages/app`)
- A bundled CLI at `Contents/Resources/cli/dist/cli.mjs`
- An `ok` wrapper script that reuses the Electron runtime as a Node host via `ELECTRON_RUN_AS_NODE=1` — no separate Node.js install is required on the Mac.

</Step>

</Steps>

<Tip>
The desktop app auto-updates via `electron-updater`, which downloads the arm64 ZIP variant (not the DMG) for in-place swaps. Beta builds are available through the docs site's `/download/beta` redirect.
</Tip>

## CLI and web app (npm)

On **Linux**, **Windows**, **Intel Mac**, or any environment where you prefer a terminal-first workflow, install the published npm package globally.

<Tabs>

<Tab title="npm (recommended)">

<Steps>

<Step title="Install Node.js 24+">

Download and install Node.js 24 or newer from [nodejs.org](https://nodejs.org/en/download/).

</Step>

<Step title="Install git">

Install `git` 2.31.0 or newer. On macOS, `xcode-select --install` provides the Xcode Command Line Tools including git. On Linux and Windows, use [git-scm.com](https://git-scm.com) or your package manager.

</Step>

<Step title="Install the CLI globally">

```bash
npm install -g @inkeep/open-knowledge
```

This places two equivalent binaries on your PATH:

| Binary | Entry point |
| --- | --- |
| `ok` | `dist/cli.mjs` |
| `open-knowledge` | `dist/cli.mjs` |

</Step>

<Step title="Verify the CLI">

```bash
ok --version
```

The version output includes the package version and GPL-3.0-or-later license notice.

</Step>

</Steps>

</Tab>

</Tabs>

### Post-install skill wiring

The npm package runs a `postinstall` script that attempts to install the bundled Open Knowledge agent skill to detected agent hosts (Claude Code, Cursor, Codex, and others). Outcomes:

| Result | Behavior |
| --- | --- |
| `installed` | Prints `[open-knowledge] Agent Skill installed to detected agent hosts.` |
| `failed` | Prints a remediation hint to run `npx skills@~1.5.0 add <bundled-path> --agent '*' -g -y --copy` manually |
| `skip-current` | Skill already at the current version; no action |

Project-level MCP registration and skill installation also run during `ok init`. If agent hosts miss the skill after install, use `ok repair-skills` or see [Wire agent editors](/wire-agent-editors).

### Optional native dependency

`@parcel/watcher` is listed as an optional dependency for efficient filesystem watching. If it fails to install on your platform, the CLI falls back to polling-based watchers.

## Contributor toolchain

Contributors work from a monorepo clone and use Bun as the package manager and Turbo for orchestrated builds, lint, typecheck, and tests.

<Steps>

<Step title="Install toolchain versions">

Pin these versions before cloning:

- **Bun 1.3.13+** — read from `.bun-version`
- **Node.js 24+** — read from `.node-version`

Version managers:

```bash
# fnm
fnm install

# volta
volta install node@24

# mise
mise install
```

</Step>

<Step title="Clone and install dependencies">

```bash
git clone https://github.com/inkeep/open-knowledge.git
cd open-knowledge
bun install
```

`bun install` warns with `EBADENGINE` if Node is below 24. The install usually succeeds, but builds and tests may fail — pin Node 24+ before reporting issues.

</Step>

<Step title="Run the public PR gate">

```bash
bun run check
```

This runs Biome lint, then Turbo `build`, `typecheck`, and `test` across workspaces. No environment variables are required for a fresh clone.

</Step>

<Step title="Run local dev surfaces (optional)">

```bash
# Web editor dev server
bun run --filter @inkeep/open-knowledge-app dev

# Docs site
cd docs && bun run dev

# Desktop Electron dev
bun run --filter @inkeep/open-knowledge-desktop dev
```

</Step>

</Steps>

<Info>
Contributor setup requires no secrets or `.env` files. See `.env.example` for optional observability variables (OpenTelemetry, custom dev server port).
</Info>

## Verify your environment

After installing the CLI and initializing a project, run health checks from the project directory:

```bash
ok init          # if not already initialized
ok diagnose health
```

`ok diagnose health` runs checks for `git`, `bun`, `config-yaml`, `content-dir`, `server-lock`, `shadow-repo`, `shadow-health`, and `macos-codesig`. The `bun` check passes only when Bun is on PATH (relevant for contributors; end users can ignore a `bun` failure). The `macos-codesig` check applies to the packaged desktop app.

To confirm the editor serves correctly:

```bash
ok start --open
```

The browser should load the WYSIWYG editor. If something fails, see [Troubleshooting](/troubleshooting) for `ok diagnose bundle`, server lock recovery, and `ok clean`.

## Install surface architecture

```text
┌──────────────────────────────────────────────────────────────┐
│                     Open Knowledge                           │
└───────────────┬──────────────────────────┬───────────────────┘
                │                          │
     macOS arm64 DMG                npm @inkeep/open-knowledge
                │                          │
    ┌───────────▼──────────┐    ┌──────────▼──────────┐
    │  Open Knowledge.app    │    │  ok / open-knowledge │
    │  ├─ Editor UI          │    │  ├─ Web editor       │
    │  ├─ Bundled CLI        │    │  ├─ MCP server       │
    │  └─ ok.sh wrapper      │    │  └─ postinstall skill│
    │     (ELECTRON_RUN_     │    │     wiring           │
    │      AS_NODE=1)        │    └──────────┬──────────┘
    └───────────┬────────────┘               │
                │                            │
                └────────────┬───────────────┘
                             │
                    ┌────────▼────────┐
                    │  .ok/ project   │
                    │  git repo       │
                    │  markdown docs  │
                    └─────────────────┘
```

## Related pages

<CardGroup>

<Card title="Quickstart" href="/quickstart">
Run `ok init`, `ok start --open`, and confirm MCP tools respond from a connected agent.
</Card>

<Card title="Initialize a project" href="/initialize-project">
Scaffold `.ok/`, initialize git, install skills, and register MCP entries for detected editors.
</Card>

<Card title="Contributing" href="/contributing">
Public mirror PR flow, changeset requirements, and local dev commands for the monorepo.
</Card>

<Card title="Troubleshooting" href="/troubleshooting">
Diagnose server lock state, repair stale skills, and recover from crash leftovers.
</Card>

</CardGroup>