Skip to content

configuration.md

Latest commit

 

History

History
130 lines (93 loc) · 4.06 KB

configuration.md

File metadata and controls

130 lines (93 loc) · 4.06 KB

Configuration

kata configuration is split between environment variables, committed workspace bindings, local per-machine overrides, and daemon config.

Environment variables

Variable Meaning
KATA_HOME Data directory. Defaults to ~/.kata.
KATA_DB Explicit SQLite database path.
KATA_AUTHOR Default actor for mutations.
KATA_SERVER Remote daemon URL. Skips local discovery and auto-start.
KATA_AUTH_TOKEN Bearer token for daemon API auth.
KATA_TRUST_PRIVATE_NETWORK Set to 1 to permit trusted plaintext bearer use on private non-loopback HTTP.
KATA_HTTP_TIMEOUT Per-request CLI timeout for non-streaming daemon calls, such as 30s or 2m. Defaults to 5s; raise it for bulk imports.
KATA_FEDERATION_PULL_INTERVAL_MS Federation runner poll interval for tests or latency-sensitive private deployments.
PORT Hosted-mode listener port when no explicit listener is configured and the daemon is not an auto-start child.
XDG_RUNTIME_DIR Runtime socket parent on Unix when applicable.

Workspace binding

.kata.toml is committed with the project:

version = 1

[project]
name = "product"

It should stay secret-free.

Local override

.kata.local.toml is gitignored. Use it for machine-specific daemon routing:

version = 1

[server]
url = "http://100.64.0.5:7777"

KATA_SERVER wins over the local file.

Daemon config

<KATA_HOME>/config.toml can configure listener and auth behavior:

listen = "100.64.0.5:7777"

[auth]
token = "change-me"
trust_private_network = true

The kata daemon start --listen <host:port> flag wins over the config file. Auto-started daemons also read the config-file listener value.

Token identity mode

For a shared daemon where each user should have stable attribution:

[auth]
token = "bootstrap-admin-token"
trust_private_network = true
require_token_identity = true

Create per-user tokens before requiring token identity:

export KATA_AUTH_TOKEN=bootstrap-admin-token
kata tokens create --actor wesm --name laptop
kata tokens list
kata tokens revoke 1

tokens create prints plaintext once. The daemon stores only a SHA-256 hash. Lost tokens must be revoked and recreated.

In identity mode, the bootstrap/admin token can manage tokens and perform reads, but attributed writes require a DB-backed token. The daemon derives the actor from that token.

Close throttle

kata refuses structurally dangerous close patterns. The parent-completeness guard always refuses closing an issue while it has open children. Two further guards throttle close bursts by one actor under a shared parent:

  • sibling-burst: closing more than three sibling issues within 60 seconds is refused;
  • repeated-message: closing a second sibling with an identical done or audit-no-change message within thirty minutes is refused.

Close each issue as soon as its work is verified. Batching closes at the end of a run is the pattern this guard is meant to catch, and it can push one actor over the sibling-burst limit even when each individual issue is legitimate.

Operators can disable both throttles daemon-wide:

[close.throttle]
enabled = false

enabled = false relaxes only the two sibling throttles. Normal CLI and API close paths still run the parent-completeness refusal, message-substance checks, and evidence checks. The TUI close path skips the message-substance and evidence checks because an interactive human confirms each close; the structural guards still apply.

Federation credentials

Federation enrollment tokens are separate from daemon API tokens. The hub stores only token hashes. A spoke stores the plaintext enrollment token in its local federation credentials file so it can call hub federation transport routes.

Do not put federation enrollment tokens in .kata.toml.

Hosted mode

When PORT is set and no explicit listener is configured, a foreground daemon binds 0.0.0.0:$PORT. Hosted mode still requires daemon API auth and explicit private-network trust. See Hosted mode.