Environment variables
This page lists public operational variables used by the launch build. The
daemon runtime uses KB1_* names throughout.
Daemon variables
Section titled “Daemon variables”| Variable | Required | Default | Purpose |
|---|---|---|---|
KB1_HOME |
No | ~/.kb1 |
Daemon state, vaults, metadata, and status files. |
KB1_HOST |
No | 127.0.0.1 |
Bind host for local UI, API, and MCP. |
KB1_PORT |
No | 7382 |
Bind port for local UI, API, and MCP. |
KB1_WEB_PORT |
Dev only | 5173 |
Internal Vite web dev server port used by pnpm dev. |
KB1_WEB_PROXY_TARGET |
Dev only | unset | Existing web dev server target for the daemon front door. |
KB1_RELAY_URL |
Self-hosted relay | unset | Cloud relay URL, usually https://api.kb-1.ai/t/<org-id>. |
KB1_RELAY_TOKEN |
Self-hosted relay | unset | Daemon-scoped relay API key returned once by Cloud. |
KB1_DAEMON_VERSION |
No | unset | Optional daemon version announced to Cloud relay. |
KB1_DAEMON_BUILD |
No | unset | Optional daemon build identifier announced to Cloud relay. |
KB1_ACTOR_DEFAULT |
No | user |
Actor fallback for local REST calls; valid values are user and unknown. |
KB1_HISTORY_COALESCE_WINDOW_MS |
No | 300000 |
Window used to coalesce nearby note-history snapshots. Set 0 to disable coalescing. |
KB1_RELAY_URL and KB1_RELAY_TOKEN must be supplied together.
Legacy KB2_* variables are ignored; update service files and shell profiles to
use the KB1_* names. On a default-path upgrade, first boot copies a legacy
~/.kb2 daemon home into ~/.kb1. Before removing the legacy source, the
daemon checks that every regular source file exists at the same relative path
in the target with the same byte length. Symlinks and empty directories are not
checked. If ~/.kb1 already exists, it may contain additional files; a missing
regular source file or size mismatch aborts startup without cleaning up
~/.kb2. This is not a content hash comparison, so make a separate backup first
if you need stronger verification or a rollback copy.
Cloud API variables
Section titled “Cloud API variables”| Variable | Required | Purpose |
|---|---|---|
ENV |
No | Runtime environment label such as development, e2e, or staging. |
BETTER_AUTH_URL |
Yes | Public API/auth origin used by Better Auth. |
BETTER_AUTH_SECRET |
Yes | Better Auth signing secret. Use a long random secret outside local dev. |
GOOGLE_CLIENT_ID |
Optional | Google OAuth client id. |
GOOGLE_CLIENT_SECRET |
Optional secret | Google OAuth secret, provisioned with Wrangler secrets outside dev. |
ALLOWED_DEV_ORIGINS |
Dev/e2e | Comma-separated web origins allowed for CORS/auth in dev-like envs. |
HOSTED_ENTRY_SECRET |
Hosted | Secret used to sign human entry tokens for hosted/relay data plane entry. |
HOSTED_DEV_TOKEN |
Hosted lifecycle | Bearer token for private hosted lifecycle calls. |
HOSTED_PUBLIC_ORIGIN |
Hosted | API origin hosted runtimes use to reach the /v entry plane when no managed-daemon relay origin is configured. |
HOSTED_DASHBOARD_ORIGINS |
Hosted | Web origins allowed by hosted dashboard/data-plane interactions. |
MCP_DAEMON_PROXY_SECRET |
Cloud MCP | Shared secret used by Cloud MCP proxy paths when enabled. |
KB1_SYSTEM_ADMIN_WORKSPACE_DOMAINS |
Admin | Comma-separated Workspace domains whose org admins can use KB-1 system-admin routes. |
BROWSER_SESSION_MAX_AGE_SECONDS |
No | Optional browser session max-age override. |
Hosted lifecycle variables
Section titled “Hosted lifecycle variables”| Variable | Default in dev/e2e/staging | Purpose |
|---|---|---|
HOSTED_IDLE_THRESHOLD_SECONDS |
20 |
Idle threshold before a hosted daemon can park. |
HOSTED_EVENT_SYNC_DEBOUNCE_SECONDS |
2 |
Debounce for hosted event sync. |
HOSTED_EVENT_SYNC_MAX_LAG_SECONDS |
10 |
Maximum event sync lag before a safety response. |
HOSTED_SAFETY_NET_SYNC_INTERVAL_SECONDS |
300 |
Periodic hosted safety-net sync interval. |
HOSTED_RELAY_PRE_FLUSH_DRAIN_MS |
unset | Optional drain window before hosted relay pre-flush. |
HOSTED_MAX_FINAL_SYNC_FAILURES |
3 |
Hosted final-sync failure tolerance before surfacing errors. |
Managed daemon variables
Section titled “Managed daemon variables”Hosted Cloud organizations run a KB-1 operated managed daemon runtime. Local dev
and e2e use the local_docker provider; staging and production default to the
fly provider unless explicitly overridden.
| Variable | Default in dev/e2e/staging | Purpose |
|---|---|---|
MANAGED_DAEMON_PROVIDER |
local_docker in dev/e2e, fly in staging/prod |
Managed runtime provider. Valid values are local_docker, fly, and fake. |
MANAGED_DAEMON_PUBLIC_RELAY_ORIGIN |
staging API origin | Public Cloud API origin used by non-local managed daemons to dial the relay. |
MANAGED_DAEMON_LOCAL_RELAY_ORIGIN |
local API origin | Local API origin used by Docker-managed daemons in dev/e2e. |
MANAGED_DAEMON_LOCAL_PROVIDER_ORIGIN |
local provider port | Origin for the local Docker provider sidecar. |
MANAGED_DAEMON_LOCAL_PROVIDER_TOKEN |
dev/e2e token | Bearer token for local provider sidecar requests. |
MANAGED_DAEMON_COMPED_CODE |
dev/e2e/staging code | Provisioning code for comped Cloud Hosted org creation. |
MANAGED_DAEMON_IMAGE_REF |
local or Fly image ref | Daemon image used when provisioning or rolling managed runtimes. |
MANAGED_DAEMON_REGION |
sjc in staging |
Provider region for new managed daemon runtimes. |
MANAGED_DAEMON_RELAY_READY_TIMEOUT_MS |
env-specific | How long Cloud waits for a managed daemon to connect and answer through relay. |
Fly-specific variables are only required when MANAGED_DAEMON_PROVIDER=fly:
| Variable | Purpose |
|---|---|
FLY_API_TOKEN |
Fly Machines API token used by Cloud to create and control managed daemon apps. |
MANAGED_DAEMON_FLY_ORG_SLUG |
Fly organization slug for managed daemon apps. |
MANAGED_DAEMON_FLY_APP_PREFIX |
Prefix for per-org Fly apps. |
MANAGED_DAEMON_FLY_VOLUME_GB |
Size of the Fly volume mounted as the daemon home. |
MANAGED_DAEMON_FLY_MEMORY_MB |
Memory size for Fly Machines. |
MANAGED_DAEMON_FLY_CPUS |
CPU count for Fly Machines. |
MANAGED_DAEMON_FLY_EXEC |
Optional command override for Fly Machines. |
Web variables
Section titled “Web variables”| Variable | Purpose |
|---|---|
PUBLIC_API_ORIGIN |
API origin used by the SvelteKit web app. |
PUBLIC_HOSTED_ORIGIN |
Data-plane origin for /v/<org-id>/ entry URLs. In cloud-018 this is the API origin. |
Local dev ports
Section titled “Local dev ports”The standard dev stack uses:
web http://127.0.0.1:9987api http://127.0.0.1:9988daemon http://127.0.0.1:7390See Ports and local development for the full port map.