Local daemon profiles¶

Use a local daemon profile to select an existing Kata home on this machine. The profile pins the database's instance UID, so a stopped work daemon can restart against its existing data while a personal daemon continues running. This feature requires Kata 0.19.0 or later; older releases accept URL overrides only.

A spoke is a local project replica joined to a federation hub. Personal and work spokes can join different hubs and contain projects with the same name. A healthy personal daemon does not establish that the selected work spoke is healthy. Keep their homes, database identities, and hub bindings separate.

Register an existing home¶

Inspect the existing home without starting it. Clear inherited storage overrides first, so the command reads that home's configured storage:

KATA_HOME=/absolute/work-home kata daemon diagnose --json

Record observed_instance_uid and, when a workspace is bound, project_uid. Diagnose does not initialize a missing database. If the storage is missing or unreadable, restore access before registering it.

Add a profile to the client home's config.toml:

[[daemon]]
name = "work"
local = true
home = "/absolute/work-home"
instance_uid = "01J00000000000000000000001"

Replace the example UID with the observed UID. home must be absolute or start with ~/. Both home and instance_uid are required together. Repeat with a separate name, home, and observed UID for a personal profile if needed. A legacy local = true entry without home still means the current KATA_HOME.

Bind the workspace in its ignored .kata.local.toml:

version = 1

[server]
daemon = "work"

server.daemon accepts only a registered local profile with a home and instance UID. It is mutually exclusive with server.url. Keep the committed .kata.toml project binding unchanged. Kata warns when it reads server.daemon in that committed file; the setting has no effect there.

Selection follows --daemon, KATA_SERVER, the workspace override, active_daemon, then the default local home. A child directory inherits the nearest eligible override within the existing workspace boundary. A separate repository or linked worktree needs its own ignored override. A tracked local override is ignored; a broader ancestor does not bypass workspace boundaries.

Registration is opt-in. Kata does not convert loopback URLs into profiles, remove overrides, enroll a project, or merge same-named projects.

Diagnose and recover¶

Run these commands from the bound workspace:

kata daemon diagnose --json
kata daemon recover --expect-project-uid 01J00000000000000000000002 --json
kata health --json

Replace the example project UID with the known work project UID. The project assertion is optional; without it, diagnosis reports the observed project UID, or project_state=missing_project if it does not exist yet. An absent project does not prevent locating or recovering the daemon. With the assertion, recovery checks the existing project before and after startup. A same-named personal project cannot satisfy the assertion. Diagnosis reports project_unverifiable when that assertion cannot be checked through readable local storage, including URL targets; it never reports an unverified assertion as ready.

Diagnosis, status, health, and locate never start the selected daemon. daemon status lists current-home processes and reports selected separately. Use that selected state to distinguish a healthy personal process from a stopped work profile. Diagnose returns the state even when it is not ready; failed recovery, health, and locate return an error.

If routing configuration is invalid, diagnose reports state=selection_error and a message explaining the failure. Status still lists current-home processes and includes the same state and message under selected. That inventory is separate from the selected target; it does not enable fallback or recovery of another home. Storage and live identity inspection use the normal KATA_HTTP_TIMEOUT budget (five seconds by default), so an unavailable database cannot stall diagnosis indefinitely.

For the default local daemon, different binary_version and runtime_version values are informational; they do not change a reachable daemon's ready state. Profile recovery still checks binary and schema compatibility.

For a reachable daemon, diagnosis reports the selected principal's live writable and actor_policy capabilities from /api/v1/instance. A token's presence does not imply write authority: an identity-mode bootstrap token remains read-only. JSON omits unavailable capabilities; agent output reports writable=unknown when storage is stopped or the live response cannot supply them.

State	Action
`ready`	Continue using the selected daemon.
`stopped_local_profile`	Run `daemon recover` to start that existing profile.
`local_stopped`	Start the current home explicitly. It is not a pinned profile.
`local_unreachable`	Inspect the selected process, transport, and credentials.
`selection_error`	Repair routing with `daemon diagnose`; status retains the current-home process list.
`missing_profile_storage`	Restore access to the profile's existing storage.
`unreadable_storage`	Use `message` to restore access to the selected storage metadata.
`unhealthy`	The selected daemon answered health but reported `ok=false`; inspect its health report and logs.
`wrong_database`	Check the home and pinned instance UID.
`missing_project` / `wrong_project`	Check the workspace binding and project UID in this database.
`project_unverifiable`	Restore readable local storage or select its pinned profile to check the project UID assertion.
`version_mismatch`	Use a compatible binary and schema before recovery.
`unknown_loopback_endpoint`	Restore the configured server or tunnel; retain the URL.
`unavailable_remote`	Restore the configured remote connection.

Recovery checks existing storage read-only before any process replacement. It never bootstraps, migrates, or cuts over profile storage, and requires the current binary's exact schema version. Follow the normal upgrade procedure explicitly in that home when the schema differs. A compatible-schema process with a different binary version can be replaced after identity checks. Missing storage, a wrong database identity, or a failed explicit project UID assertion stops recovery before startup. No recovery path creates a replacement project.

An explicit server.url, including a loopback tunnel, stays a URL target. Kata cannot infer its home or ownership. Recovery refuses it and ordinary commands never fall back to another database when it is unavailable.

Configuration and credentials¶

The selected home supplies storage, listener, authentication, federation, integrations, and idle settings. The client does not apply the parent home's KATA_DSN, PostgreSQL schema overrides, daemon tokens, proxies, or hosted PORT to that profile. Child processes receive an OS/toolchain allowlist, explicit safe credential references from the selected configuration, and the selected home/storage settings. Reserved daemon, PostgreSQL, proxy, and hosted variable names cannot be credential references. Other KATA_ names, including KATA_TEAM_HUB_TOKEN and KATA_SHARED_TOKEN, are allowed. SSL_CERT_FILE and SSL_CERT_DIR pass through to child daemons so private certificate authorities remain available for HTTPS connections.

The profile's own auth token is used for its API and identity checks. A catalog token or token_env can select a client credential for identity-token mode; it does not replace the selected daemon's configured auth. Use a neutral, non-reserved environment name for a referenced credential.

SQLite storage paths must be absolute. PostgreSQL profiles require a complete single-host URL with an explicit port, database, and user. Service routing, multiple hosts, and query overrides for host/port/database/user are unsupported. Unset PGSERVICE; any ambient PostgreSQL connection option must be explicit in the URL or profile inspection rejects it before dialing. Keep credentials in the protected home config, not workspace files.

Reboots, idle shutdown, and clients¶

Ordinary commands can restart a stopped, valid local profile. Recover offers an explicit identity check for troubleshooting. Auto-started profiles use their own idle timeout; a reboot or idle exit does not change their database identity. For continuous hub sync or background maintenance, run a resident service in the selected home:

KATA_HOME=/absolute/work-home kata daemon start
KATA_HOME=/absolute/work-home kata daemon stop

These home administration commands, plus restart, reload, and logs, reject --daemon. Clear inherited storage overrides when administering a home. Host-local export and mcp serve --storage-root likewise require an explicit KATA_HOME instead of a profile selector. Ordinary mcp serve uses the shared daemon selection.

The TUI uses the same selection order and retains the selected socket and credential for API calls, SSE, and reconnects. kata ui opens a selected profile's own browser origin. The serving daemon's browser switcher omits home-bearing profiles and rejects requests naming them; URL catalog entries remain the supported browser gateway targets. An outer catalog alias is never appended to a direct profile browser launch.

Existing local replica reads and permitted local writes continue while the hub is offline. Enrollment, hub catalogs, and other hub operations still need that hub. A profile does not upgrade the replica's authority or repair its federation binding. See Federation for those contracts.