Config file (config.toml)

kabactl reads one file, config.toml, from its storage directory:

Platform	Path
Linux	`~/.config/kaba/config.toml`
macOS	`~/Library/Application Support/kaba/config.toml`
Windows	`%APPDATA%\kaba\config.toml`

The file is created with defaults the first time kabactl runs. On each start it is re-read and rewritten in canonical form, so keys added by a newer version appear with their defaults and you can edit them in place. A file that fails to parse is left untouched and defaults are used for that run. Restart the server after editing.

Example

jwt_exp_time = 28800
jwt_secret = "…33 random characters…"
kabactl_server_port = 28832
proxy_server_port = 28833
cert_path = "/home/you/.config/kaba/certs/kaba.cert"
key_path = "/home/you/.config/kaba/certs/kaba.key"
tls = true

[memory_options]
memory_version_limit = 100
memory_optimization_interval = 60

[adblock_options]
enabled = true
blocklist_urls = ["https://easylist.to/easylist/easylist.txt"]

[cluster_options]
cluster_enabled = true
relays = ["https://relay.kaba.dev"]
include_default_relays = false
n0_discovery = false
relay_only = false
iroh_log_level = "error"
federation_seeds = []

[kaba_engine_options]
base_model = "e2b"
accept_remote_inference = true
accept_remote_training = true

[security_options]
block_malicious = true

[exec_options]
enable_peer_exec = true
allow_network = true
sandbox_allow_shell = false

Top-level keys

If you write the file by hand, it must contain jwt_exp_time, jwt_secret, cert_path, key_path, tls, and the [memory_options] and [adblock_options] tables. Every other section is optional and falls back to its defaults. The simplest route is to let kabactl create the file, then edit it.

Key	Default	Description
`jwt_secret`	random, 33 characters	Signs session tokens and the proxy credentials used by off-box clients. Generated on first run. Treat it as a secret.
`jwt_exp_time`	`28800`	Session lifetime in seconds (8 hours).
`cert_path`, `key_path`	`<storage>/certs/kaba.cert`, `kaba.key`	The TLS certificate and key the API serves. See certs.
`cert_format_version`	`1`	Managed by kabactl. When lower than the current format, certificates are regenerated on start.
`headless`	unset	`true` or `false` forces whether this node presents as headless. Unset, it is decided at runtime from whether a real user account exists.
`relay_config_migration_version`	`2`	Managed by kabactl. Do not edit.
`kabactl_server_port`	`28832`	See the caution below.
`proxy_server_port`	`28833`	See the caution below.
`tls`	`true`	See the caution below.

memory_options

Key	Default	Description
`memory_version_limit`	`100`	How many versions of a memory to keep.
`memory_optimization_interval`	`60`	How often the store is compacted and optimized.

adblock_options

Controls blocking in the SOCKS5 proxy. The client has its own in-browser blocker with its own lists under Settings → Security & Privacy.

Key	Default	Description
`enabled`	`true`	Block requests that match the lists.
`blocklist_urls`	EasyList	Filter lists to download. The engine is built lazily on the first proxied connection, so a node that never proxies never downloads them.

cluster_options

Key	Default	Description
`cluster_enabled`	`true`	`false` keeps this node off the mesh entirely.
`relays`	`["https://relay.kaba.dev"]`	Relay servers used when two peers cannot connect directly.
`include_default_relays`	`false`	Also use iroh’s public default relays.
`n0_discovery`	`false`	Also use iroh’s public discovery service.
`relay_only`	`false`	Never attempt direct connections; send everything through relays.
`iroh_log_level`	`"error"`	Log level for the networking layer. Applied when `KABA_DEBUG=1`.
`federation_seeds`	`[]`	Seed nodes for the public-services directory. `KABA_FEDERATION_SEEDS` also sets these.
`public_directory_url`	unset	Directory of public `.kaba` services. Unset, the first relay is used. An empty string disables it.

kaba_engine_options

Key	Default	Description
`base_model`	`"e2b"`	Base model variant this node serves: `e2b` (about 2B effective parameters) or `e4b` (about 4B).
`lora`	unset	Adapter applied by default when a request does not name one.
`accept_remote_inference`	`true`	Let cluster peers run inference here.
`accept_remote_training`	`true`	Let cluster peers train here.
`serve_remote_large_model`	`true`	Serve the larger variant to peers that ask for it.
`llama_max_ctx`	unset	Upper bound on the context window, in tokens.
`mmproj_on_demand`	`true`	Load the model without the multimodal projector and attach it on the first image or audio request. `false` always attaches it, at a cost of several hundred MB per load.
`inference_use_persona_block`	`true`	Include the built-in persona in prompts.
`inference_ground_with_retrieval`	`false`	Retrieve related memories into every prompt.
`default_lora_rank`	`16`	Training default.
`default_epochs`	`3`	Training default.
`default_peak_lr`	`0.0001`	Training default.
`default_min_records`	`200`	Minimum memories required to train.
`summary_cache_max_entries`	`0`	Size of the summary cache.
`cluster_min_unique_hostnames`	`50`	Minimum distinct sites before memories are clustered for training.
`cluster_min_embedding_coverage`	`0.3`	Minimum share of memories with embeddings before clustering.
`spill_summarize_max_cells`	unset	Limit on context-spill summarisation.

security_options

Key	Default	Description
`block_malicious`	`true`	Block connections to indicators in the local threat database.
`feeds`	see below	The sources `kabactl security update` builds the database from.

Each feed is a [[security_options.feeds]] table:

Key	Default	Description
`name`	required	Display name.
`type`	`"http"`	`http` to download from `url`, or `file` to read `path`.
`url`		Source URL for `http` feeds.
`path`		For `file` feeds, relative to `<storage>/security/`.
`kind`	`"domain"`	What each line is: `domain`, `url`, `ip`, `filename` or `sha256`.
`format`	`"plain"`	`plain` (one value per line) or `hosts`.
`category`		Free-form label such as `malware` or `phishing`.
`enabled`	`true`	Include this feed.
`column`, `delimiter`	`0`, `,`	For delimited files: which column holds the value.

Default feeds:

Feed	Kind	Enabled
URLhaus malware hosts	domain	yes
Phishing Army (extended)	domain	yes
Feodo Tracker botnet C2 IPs	ip	yes
URLhaus malware URLs	url	no
testsafebrowsing (bundled test file)	url	yes
Local custom domains (`feeds/custom-domains.txt`)	domain	no
Local malware filenames (`feeds/filenames.txt`)	filename	no
Local file hashes (`feeds/hashes.txt`)	sha256	no

[[security_options.feeds]]
name = "Company blocklist"
type = "file"
path = "feeds/company.txt"
kind = "domain"
category = "custom"

exec_options

Governs commands the tool loop and peers may run on this node. See security.

Key	Default	Description
`enable_peer_exec`	`true`	Let cluster peers manage containers and run sandboxed commands here over `kaba/exec/v1`.
`allow_network`	`true`	Whether sandboxed runs may be given outbound network at all.
`sandbox_allow_shell`	`false`	Allow shell interpreters inside the sandbox.
`extra_allow`	`[]`	Extra command names to treat as allowed.
`extra_deny`	`[]`	Extra command names to always refuse.
`force_allow`	`[]`	Command names to allow even when the built-in list would refuse them. Use with care.

Whatever these lists say, host commands must be a single command on one line: pipes, redirection, chaining and command substitution are refused.

Environment variables

A few settings are only available as environment variables. The full list is in the kabactl environment reference.