Daemon configuration

The KB-1 Local daemon is the content authority for local-only and self-hosted vaults. It serves the local web UI, REST API, and MCP endpoint from one process.

The process is kb1d, its environment variables use the KB1_* prefix, and its default home is ~/.kb1.

Default configuration

Setting	Default	Notes
Service name	`kb1d`	Appears in health output and service logs.
Host	`127.0.0.1`	Keep loopback unless you deliberately expose a private network route.
Port	`7382`	Serves UI, API, and MCP.
Home	`~/.kb1`	Override with `KB1_HOME`.
Vaults directory	`$KB1_HOME/vaults`	One immediate child directory per vault.
Daemon state	`$KB1_HOME/daemon`	Includes `status.json`.
Starter vault	`demo-vault`	Created on first boot when no vault exists.

Filesystem layout

$KB1_HOME/
  daemon/
    status.json
  vaults/
    demo-vault/
      .kb1/
        vault.json
        folders.yml
      README.md
      notes/

The daemon discovers vaults from immediate directories under $KB1_HOME/vaults/. Do not place backup copies of vault folders inside that directory; duplicate .kb1/vault.json identities can prevent startup.

Relay configuration

Self-hosted Cloud login uses an outbound relay connection. Configure both values together:

KB1_RELAY_URL="https://api.kb-1.ai/t/<org-id>"
KB1_RELAY_TOKEN="kb1_dmn_..."

KB1_RELAY_TOKEN is a daemon-scoped API key returned once by Cloud relay registration. Store it like a secret. Cloud stores its hash and uses it to bind the daemon to the org’s relay channel.

If one relay variable is set without the other, the daemon exits with a config error.

Local development overlay

The cloud dev stack writes relay values to .dev.daemon.json after seeding:

pnpm --filter @kb-1-cloud/api seed:dev
pm2 restart kb1-cloud-dev-daemon

The PM2 daemon reads that file on restart. Until the file exists, the dev daemon runs relay-less on its local port.

Service checks

Health:

curl http://127.0.0.1:7382/api/health

Relay status:

curl http://127.0.0.1:7382/api/relay/status

MCP endpoint:

http://127.0.0.1:7382/mcp

Safe defaults

Use an explicit KB1_HOME for tests and docs smoke runs.
Keep KB1_HOST=127.0.0.1 unless private-network exposure is intentional.
Flush a vault before backup with POST /api/vaults/<vault-id>/ops/flush.
Put backups outside $KB1_HOME/vaults/.
Treat relay tokens like passwords.