Run the local-only daemon

Use this path when you want a solo, open-source KB-1 vault on your own machine. Local-only mode does not require a KB-1 Cloud account. The daemon serves the web UI, local API, and local MCP endpoint from one localhost service.

Local-only mode does not include Cloud users, organizations, team presence, or Cloud MCP. Agents connect to the daemon from the same machine or from a private network you have deliberately trusted.

Connect self-hosted Cloud login when you want Cloud identity, organization membership, relay, presence, or team access while keeping the daemon on your machine. Relay also lets agents reach the vault without being colocated with the daemon.

What this sets up

A local KB-1 daemon on 127.0.0.1.
A filesystem-backed vault under KB1_HOME.
A local web app at the daemon port.
A local MCP endpoint at /mcp for agents on the same machine.
Markdown notes, binary attachments, vault management, and Git-backed, best-effort note history in the local UI.

Prerequisites

A supported Node release: 20.19.x, 22.12+, or 24+.
pnpm through Corepack.
Git.
A writable directory for daemon state.
No process already using the daemon port you choose.

KB-1 Local is released under the Apache-2.0 license. Runtime names use KB-1 throughout: KB1_HOME, KB1_PORT, KB1_HOST, and kb1d.

Start KB-1 Local

Clone the public source and install the locked dependencies:

git clone https://github.com/metatheoryinc/kb-1-daemon.git
cd kb-1-daemon
corepack enable
corepack install
pnpm install --frozen-lockfile

Start the daemon and development web UI from that checkout:

KB1_HOME="$PWD/.kb1-quickstart" KB1_PORT=7382 pnpm dev

Expected output includes:

KB-1 dev front door: http://127.0.0.1:7382
Vite dev server: http://127.0.0.1:5173
[daemon] kb1d listening on http://127.0.0.1:7382
[daemon] KB1_HOME=<your checkout>/.kb1-quickstart

Open the app:

http://127.0.0.1:7382/

On first boot, the daemon creates a starter vault named demo-vault.

Docker alternative

From the same checkout, you can build and run the production image instead of installing the Node dependencies. Keep the unauthenticated Local port bound to loopback:

docker build -f apps/daemon/Dockerfile -t kb-1-daemon .
docker run --rm \
  -p 127.0.0.1:7382:7382 \
  -v kb1-home:/data/kb1 \
  kb-1-daemon

The named kb1-home volume preserves the local vault across container restarts. Open http://127.0.0.1:7382/ and use the same verification commands below.

Verify the daemon

In a second terminal:

curl http://127.0.0.1:7382/api/health
curl http://127.0.0.1:7382/api/vaults
curl http://127.0.0.1:7382/api/vaults/demo-vault/tree

The health response should be shaped like:

{
  "ok": true,
  "service": "kb1d",
  "status": {
    "serviceName": "kb1d",
    "kb1Home": "<your checkout>/.kb1-quickstart",
    "statusFile": "<your checkout>/.kb1-quickstart/daemon/status.json"
  }
}

The vault list should include the starter vault:

{ "ok": true, "vaults": [{ "id": "demo-vault", "displayName": "demo-vault" }] }

The tree response should include Markdown files from the starter kit.

Create another local vault

curl -X POST http://127.0.0.1:7382/api/vaults \
  -H 'content-type: application/json' \
  -d '{"displayName":"Field Notes","slug":"field-notes"}'

A successful response is 201:

{ "ok": true, "vault": { "id": "field-notes", "displayName": "Field Notes" } }

The new vault is immediately available without restarting:

curl http://127.0.0.1:7382/api/vaults/field-notes/tree

Done looks like

curl /api/health returns ok: true.
The web app opens at the daemon port.
curl /api/vaults lists at least one vault.
Creating a note in the UI writes a Markdown file under KB1_HOME/vaults/<vault-id>/.
Local agents can connect to http://127.0.0.1:7382/mcp.