Security model
KB-1 separates identity from vault hosting. Cloud can authenticate people and route sessions while the vault engine may live on the user’s machine or in a KB-1 operated Hosted environment.
Identity and authorization
Section titled “Identity and authorization”KB-1 Cloud owns:
- user login and sessions,
- organization membership,
- org-scoped vault entry checks,
- signed entry tokens for browser data-plane access,
- approved MCP integrations when Cloud MCP is enabled,
- presence and collaboration identity.
A user must be an org member before Cloud mints a vault entry assertion for that org and vault slug.
Local-only daemon
Section titled “Local-only daemon”Local-only mode has no Cloud account requirement and no application login layer
in front of the daemon. Keep it bound to 127.0.0.1 unless you deliberately
expose it through a private network you trust.
Anyone who can reach a local-only daemon endpoint can use its local UI, API, and MCP surface. This is why the safe default is loopback.
The local daemon has no Cloud users, organizations, or per-user org permissions of its own. Those features are Cloud-layer concerns. Local-only access is a network trust boundary, not a login boundary.
Self-hosted relay
Section titled “Self-hosted relay”Self-hosted full experience uses Cloud login plus an outbound daemon connection.
The daemon presents a daemon-scoped API key as KB1_RELAY_TOKEN; Cloud stores
only a hash of that key. Admins can issue or rotate the key from the
Organizations self-hosting surface or through the org API-key routes.
The relay avoids inbound public ports. Cloud authenticates the person, checks org membership, signs entry, and routes requests to the connected daemon. The daemon remains the vault home and durable content authority.
Hosted vaults
Section titled “Hosted vaults”Hosted full experience uses the same Cloud login and org model, but KB-1 operates the vault engine and lifecycle. The hosted runtime uses the same daemon contract behind the Cloud entry plane, with lifecycle controls kept private to Cloud. Hosted may also keep bounded, per-org hot-cache state for repeated reads and hot documents. Daemon-produced cache entries are reconstructible from daemon state; pending hot-document edits may be stored there temporarily until replay or ack. The hot cache must not be treated as a generic Cloud content store or a separate search/indexing surface.
Agent access
Section titled “Agent access”Local MCP agents connect to the daemon’s /mcp endpoint. Today, the local MCP
surface does not have per-agent RBAC; treat any configured local MCP client as
able to read and write the daemon vaults it can reach.
Cloud MCP, when enabled for a deployment, uses Cloud sign-in, OAuth-style approval, an integration record, and server-authored attribution before routing tool calls to the selected org daemon. Use the agent’s own approval model, prompts, and client isolation to control what it is allowed to do.
Data custody
Section titled “Data custody”| Mode | Durable vault content | Cloud role |
|---|---|---|
| Local-only daemon | User machine | None required. |
| Self-hosted with Cloud login | User machine | Login, orgs, signed entry, relay, presence, routing metadata. |
| Hosted | KB-1 operated hosted environment | Login, orgs, signed entry, lifecycle, durability, bounded hosted hot-cache state, presence, routing metadata. |
Cloud should not be described as storing every vault just because a user logs in. Cloud login and vault home are separate decisions.
Operator checklist
Section titled “Operator checklist”- Keep local daemons on loopback by default.
- Treat relay tokens, Better Auth secrets, hosted entry secrets, and hosted dev tokens as secrets.
- Rotate relay keys if they are pasted into the wrong place.
- Use explicit
KB1_HOMEpaths for tests and demos. - Flush before backups.
- Keep backups outside
$KB1_HOME/vaults/.