# Install ## Start here openContext runs on your computer. This website explains the product; it does not host your vault or a sign-in account. **New to openContext?** The app and a separate demo are coming soon. [Email Alec for beta access](mailto:alecmerle.biz@gmail.com?subject=OpenContext%20beta%20access). A public download is not available yet. If you already have an invitation, [open the private repository](https://github.com/Alec-Merle/OpenContext), clone it, and follow the setup instructions below. ## Already installed? From your openContext checkout, run `npm run dev` and leave the terminal open. Once it reports that the app is ready, [open your local workspace](http://localhost:5173/). Your files and any sign-in stay on your own installation. If the workspace does not open, check the terminal for a startup error and run `npm run doctor` in the checkout for an offline diagnostic. The link can only work on the computer where openContext is running. ## Installation guide Installing OpenContext is three commands on a machine with Node 22 and git: `npm run setup`, `npm run doctor`, `npm run dev`. (Acronyms on this page: CLI is the command-line tool, MCP is the Model Context Protocol, API is the programming interface a service exposes, and an API key is the credential that identifies your account with a provider.) It runs on macOS and Linux (Windows is best effort), needs one model credential or none at all in demo mode, and writes nothing outside the folder you point it at. The repository is private during the closed beta; invitees clone it from [GitHub](https://github.com/Alec-Merle/OpenContext). ## Prerequisites - **Node 22 or newer** (`node --version`; the repo ships an `.nvmrc`) and the npm that comes with it. - **git installed where your shell can find it.** Vault versioning, rollback, and repository ingestion all shell out to it. - **A model credential**, one of: an Anthropic API key (the credential that identifies your account with Anthropic), an OpenRouter key, or a logged-in Claude Code CLI (`claude`, then `/login`). Nothing yet? Demo mode below runs the whole pipeline on a simulator. - **macOS and Linux** are supported. Windows is best effort: the scripts avoid shell-specific syntax (`npm run dev`, `npm run demo`, `npm start` work), but `npm run free-ports` relies on `lsof` and does nothing there. - **Disk**: about 520 MB of `node_modules` after setup, as observed on one macOS machine; it varies by platform. Roughly 320 MB of that is the Claude runtime the Agent SDK (Anthropic's software development kit) downloads for your platform from the npm registry as an optional dependency at install time; no separate Claude Code install is needed. ## Quick start ```bash npm run setup # npm install + web install + web build, in one go npm run doctor # free: names anything missing (Node, git, credential, ...) npm run dev # web on http://localhost:5173, API on loopback port 4477 ``` Drop a document onto the Intake page and watch the live feed. `npm run doctor` writes nothing, spends nothing, and kills nothing: it checks the Node version, git, the Agent SDK's bundled runtime, the web build, `.env`, which model credential the server would see (presence only, never a value), the vault, and whether the ports are free, and exits 1 only on a hard failure. `npm run doctor:live` spends one small model call to prove the SDK authenticates with the credential and model the server would actually use. ## Credentials The ingestion agent runs on the Claude Agent SDK, which uses whichever credential it finds, in this order: 1. an Anthropic API key pasted in **Settings, Models**, kept in `vault/_state/anthropic.json` (readable only by your own user account, never returned by the server, unreadable to the agents) and used by the next run, no restart; or 2. `ANTHROPIC_API_KEY` in `/.env`. The server reads `.env` itself at boot, so restart after editing it. `cp .env.example .env` to begin; the example file lists every setting; or 3. a logged-in Claude Code CLI: run `claude` in a terminal once and `/login`. Prefer OpenRouter? Settings, Models can route every run through openrouter.ai instead: paste an OpenRouter key, flip the provider, and pick any model they serve. Or in `.env`: `OPENROUTER_API_KEY=sk-or-...` plus `OPENCONTEXT_PROVIDER=openrouter`. Vault-building leans on tool use, so models that support tool use are recommended. ## Demo mode No credential yet? Demo mode runs the full pipeline with a deterministic simulator instead of the model, spending no tokens: ```bash npm run demo # any platform, disposable vault ``` The demo uses a temporary vault and cannot switch into your personal vault. Restart normally to return to your own files. The low-level `OPENCONTEXT_FAKE_AGENT=1` test flag does not provide this isolation by itself and should only be used with an explicitly configured scratch vault. ## Point your coding agents at it With the app running, install the `opencontext` CLI from a repository you code in. The install also links that repository to the graph by writing a managed block into its `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, and `README.md`. Run it yourself, or paste it at your agent: ```bash curl -fsSL http://127.0.0.1:4477/install.sh | sh ``` on macOS and Linux, or on Windows (PowerShell): ```powershell irm http://127.0.0.1:4477/install.ps1 | iex ``` The package is built and served by your own local server; nothing comes from the internet or a registry. `npm uninstall -g opencontext` removes it. For Claude Desktop, Cursor, Codex, and other MCP clients, **Settings, Connect your AI tools** shows a ready-made install snippet per client for the MCP server. The [for-agents page](https://getopencontext.com/for-agents.md) covers both surfaces. ## Where the vault lives The vault is a plain folder of markdown. At boot the server resolves it in this order: a vault chosen in the app (Settings, Environment, Switch vault), then `OPENCONTEXT_VAULT` from the environment or `.env`, then `/vault`. The default lives inside the app checkout, and the server says so at every boot: keep it elsewhere by setting `OPENCONTEXT_VAULT` to a folder outside the checkout, or switch in Settings. Boot refuses to scaffold a vault into a folder that already holds files OpenContext did not create unless `OPENCONTEXT_VAULT_ADOPT=1` grants it. ## Upgrade ```bash git pull npm run setup # dependencies may have changed, and the web build must be redone npm run typecheck npm test npm run dev ``` Nothing in the vault is migrated by an upgrade; the vault format is markdown and stays readable across versions. If the distillation logic changed, the app may report already-ingested sources as stale and offer to re-distill them. It never does so on its own. ## Back up and restore The vault is a git repository with one commit per operation, so local history is already a backup against your own mistakes. For an off-machine copy, connect a GitHub or GitLab account in Settings, Environment, point the vault at an empty remote repository, and push; or press **Download my vault** for a zip of every knowledge file, the `_sources/` originals, and the full git history. Restore is a clone plus a pointer: ```bash git clone ~/opencontext-vault # then set OPENCONTEXT_VAULT=/Users/you/opencontext-vault in .env and restart, # or use Settings > Environment > Switch vault to point at it ``` A restore from the remote brings back the knowledge graph, not the secrets: reconnect Drive, Gmail, X, and the forges, and re-enter the model key in Settings, Models. ## Development ```bash npm run dev # tsx watch server (4477) + vite (5173, proxies /api) npm run typecheck # server + web npm test # the whole offline suite - no network, no tokens, no spend ``` Every push and pull request runs the same three on Node 22 in GitHub Actions, with every model credential blanked so a green continuous-integration run can never have spent anything. This is release 0.2.0; the [changelog](https://getopencontext.com/changelog.md) has what changed.