Skip to content

Quickstart in 5 minutes

From a clean machine to your first AI session that reads from a persistent vault, in five minutes. Three commands installs Korva. Three more wires up your editors and starts the vault.

Updated: 2026-05-15

This walkthrough takes you from zero to your first AI session that reads from a persistent vault. By the end, your AI assistant will pull context automatically before answering and will block bad commits.

1. Install (30 seconds)

If you haven’t yet:

Terminal window
curl -fsSL https://korva.dev/install | bash

See Install for Homebrew / PowerShell / Docker options.

2. Initialize your workspace (5 seconds)

Terminal window
korva init

This creates ~/.korva/ (or %LOCALAPPDATA%\korva\ on Windows) with:

  • install.id — a stable random ID for telemetry-free instance tracking
  • hive.key — your private key for the optional Hive sync (mode 0600)
  • a default config.json you can edit at any time

It also writes a per-project korva.config.json if one doesn’t exist already.

If you intend to administer this machine (run korva teams ..., manage Skills Hub, etc.), add --admin:

Terminal window
korva init --admin --owner [email protected]

That generates ~/.korva/admin.key (32 bytes, mode 0600). The owner email is just a label — nothing is sent anywhere.

3. Start the vault server (3 seconds)

Terminal window
korva vault start

The vault listens on http://localhost:7437 for the REST API and on stdio for MCP. The PID is written to ~/.korva/vault/vault.pid so subsequent commands know it’s running.

4. Wire up your editors (10 seconds per IDE)

Terminal window
korva setup --all

This auto-detects every supported editor on your machine (Claude Code, Cursor, Windsurf, Copilot, Codex, OpenCode, Gemini, VS Code) and writes the right MCP config — never overwriting unrelated settings, never duplicating entries. To target one editor only:

Terminal window
korva setup claude-code
korva setup cursor
korva setup vscode

See Integrations for the per-IDE details.

5. Verify everything is healthy

Terminal window
korva doctor
korva status

Both should print All checks passed. If something fails, the error message tells you what to do (the vault is not running, the admin.key is missing, the IDE config wasn’t writable, etc.).

6. First AI session

Open Claude Code, Cursor or any wired-up editor. The first prompt your AI runs will silently call vault_context and pull your project’s recent decisions, patterns and bug fixes. You’ll notice it without doing anything else: the AI starts respecting your conventions instead of inventing new ones.

To save the AI’s first useful insight to the vault, just ask it:

Save the architectural decision we just made about idempotency keys to the vault.

The AI calls vault_save for you. Six months from now, when anyone in the team opens the same file, that decision resurfaces automatically.

7. Connect to a Teams portal (optional)

If your organization uses the Korva Teams tier, connect this workstation to get shared skills, private scrolls, and team analytics:

Terminal window
korva connect https://portal.korva.dev K0RVA-XXXX-XXXX-XXXX-XXXX

Replace the URL and key with the ones provided by your team admin. The portal URL and license key are stored locally at ~/.korva/. See Teams setup for details.

8. Lock the gate at commit time

Terminal window
korva sentinel install

Adds two Git hooks to the current repo:

  • pre-commit runs the architecture validator and blocks the commit on hard violations
  • post-commit runs korva sync --vault --quiet (best-effort, never blocks)

You can run the validator manually with korva sentinel check over staged files.

What just happened

In under five minutes you have (optionally eight steps with Teams):

  • a persistent local memory that survives editor restarts
  • automatic context injection in every supported IDE
  • commit-time architecture and security guardrails
  • structured Git hooks that keep the vault in sync

Next steps