Connect a self-hosted vault to Cloud

Use this path when you want the full KB-1 Cloud experience, but you want the vault engine and durable files to stay on a machine you control.

This is the confusing but important split: people and agents still log into KB-1 Cloud. Cloud handles identity, organization membership, signed entry, presence, and routing. Your daemon remains the vault home.

What this sets up

KB-1 Cloud login for the organization.
A self_hosted organization whose daemon mode was chosen from birth.
A daemon-scoped relay key, returned once, used as KB1_RELAY_TOKEN.
An outbound daemon connection to Cloud. No inbound public port is required for the relay path.

Prerequisites

For launch users:

A KB-1 Cloud account.
A self-hosted organization provisioned for you. A cloud-hosted organization is not silently flipped into self-hosted mode.
A machine that can run the KB-1 daemon continuously.
A backup plan for that machine’s vault directory.

For local verification from this repository:

Node 24 or newer, as required by the KB-1 Cloud workspace.
pnpm through Corepack.
The daemon submodule initialized with git submodule update --init.

The daemon uses KB-1 runtime names throughout: KB1_HOME, KB1_PORT, KB1_RELAY_URL, KB1_RELAY_TOKEN, and kb1d.

Register the relay path

The launch-supported relay registration path is an authenticated Cloud API call:

POST /api/orgs/<org-id>/vaults/relay

It works only for an organization that was created as self_hosted. It does not turn a Hosted organization into a self-hosted one, and it does not create a durable Cloud vault row. It issues the daemon-scoped key your daemon presents as KB1_RELAY_TOKEN.

Send a body shaped like:

{"name":"Main vault"}

For an operator or API client with the signed-in user’s Cloud session cookies:

export KB1_API_ORIGIN="https://api.kb-1.ai"
export KB1_ORG_ID="org_..."
export KB1_SESSION_COOKIE='better-auth.session_token=...'

curl -X POST "$KB1_API_ORIGIN/api/orgs/$KB1_ORG_ID/vaults/relay" \
  -H 'content-type: application/json' \
  -H "cookie: $KB1_SESSION_COOKIE" \
  -d '{"name":"Main vault"}'

That route also returns the plaintext daemon key once:

{"apiKey":"kb1_dmn_...","daemonId":"dmn_..."}

Some deployments also expose an admin-only Organizations -> Self-hosting panel for self_hosted orgs. When present, that panel issues or rotates the same kind of daemon-scoped key through:

POST /api/orgs/<org-id>/api-key
POST /api/orgs/<org-id>/api-key/rotate
GET /api/orgs/<org-id>/api-key

Treat that panel as a convenience surface. If it is not available in your deployment, use the relay registration API above or ask the launch operator to run it for you. Plaintext keys are shown only once; later reads show only a masked value.

Use the response and org id to configure the daemon:

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

The token is daemon-scoped. Store it like a secret. Cloud only stores its hash.

Start the daemon

From a KB-1 daemon checkout:

corepack enable
pnpm install
KB1_HOME=/srv/kb1 \
KB1_PORT=7382 \
KB1_RELAY_URL="https://api.kb-1.ai/t/<org-id>" \
KB1_RELAY_TOKEN="kb1_dmn_..." \
pnpm dev

Expected daemon output includes:

kb1d listening on http://127.0.0.1:7382
KB1_HOME=/srv/kb1
status=/srv/kb1/daemon/status.json

In another terminal, confirm the local daemon is healthy:

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/relay/status

The relay status should report that relay is configured. Once the control socket is connected, it should also report relay.controlConnected: true:

{
  "ok": true,
  "relay": {
    "configured": true,
    "started": true,
    "controlConnected": true,
    "reconnectScheduled": false
  }
}

Verify locally today

The local dev rig seeds one Hosted org and one self-hosted org. From the kb-1-cloud repository:

git submodule update --init
pnpm install
pnpm bootstrap:worktree --force-env
pm2 start ecosystem.config.js
curl http://127.0.0.1:9988/api/health
pnpm --filter @kb-1-cloud/api seed:dev
pm2 restart kb1-cloud-dev-daemon

The seed writes .dev.daemon.json with local relay wiring, and the PM2 daemon reads that file on restart.

http://127.0.0.1:9987/sign-in
olivia@example.test / dev-password-123

Then open the self-hosted demo vault:

http://127.0.0.1:9987/app/org/demo-self-hosted/vault/demo-vault

Done looks like

The daemon health endpoint is green on your machine.
/api/relay/status reports relay.configured: true and relay.controlConnected: true.
The Cloud app lists the self-hosted vault under the self-hosted organization.
Opening the vault through Cloud reaches your daemon, not a Hosted daemon.
Edits made through Cloud persist under your daemon’s KB1_HOME vault folder.