Skip to main content

Configuration reference

Complete reference for config/config.toml. See config/config.example.toml in the repository for a commented example.

Top-level settings​

SettingDefaultDescription
bot_name"Istota"User-facing name (chat, emails, folder names)
emissaries_enabledtrueInclude emissaries.md in system prompts
worldview_enabledtrueInclude worldview.md in system prompts, between emissaries and the persona. See persona
model""Deprecated (ISSUE-418). This was the claude_code brain's own default living at the top level, where it was applied to whatever brain ran and shadowed that brain's configured default — so a room pinned to native still got the Claude model. Still loads, and is migrated onto [brain.claude_code] with a warning; never onto [brain.native]. Set the per-brain key instead.
effort""Deprecated (ISSUE-418), migrated the same way as model above.
db_path"data/istota.db"SQLite database path
module_data_dirderivedRoot for per-user module DBs (feeds, health, location, money); defaults to {db_path.parent}/modules. It must be local disk, not the Nextcloud mount: SQLite's WAL keeps an mmap'd -shm file that raises SIGBUS on the rclone FUSE mount, which would leave the databases on the slower DELETE journal mode. A path under workspace_mount_path is refused at runtime. The user-facing files (health uploads, money ledgers, feed exports) stay in the workspace; only the .db files live here
workspace_pathworkspace_mount_pathOn-disk root of the bot's file tree. Required when [nextcloud] url is set. On the stack istota setup writes /data/workspace for a local workspace and /mnt/shared for a mounted one; change it with istota-stack setup --force, or move a mounted workspace to local storage with istota-stack localize-workspace (see Moving to a local workspace)
workspace_mount_pathnot setThe mountpoint the workspace lives on, when it is one (the rclone mount of Nextcloud, or a host folder shared into a VM); doctor and the backup guard check it is mounted. With a [nextcloud] url, set means the workspace is the bot's Nextcloud files and the bot describes them that way; unset means a plain local workspace, and Talk and the nextcloud skill still work. On the stack istota setup writes /mnt/shared when the workspace is the rclone mount (--workspace mount, the default with a Nextcloud URL) or the local VM's shared folder (--storage host-folder), and leaves it unset for a local workspace. It has to agree with STORAGE in the VM's host.env: the daemon refuses to start when the mount is not the kind STORAGE names. nextcloud_mount_path is read as its old name, with a warning; both set to different paths is a load error
skills_dir"config/skills"Operator skill overrides directory
disabled_skills[]Instance-wide skills to exclude
temp_dir"/tmp/istota"Temporary directory for task execution
max_memory_chars0Cap total memory in prompts (0 = unlimited). A deployment-wide budget applied after retrieval has picked what is most relevant, so lowering it drops the weakest matches rather than switching recall off. A per-user [users.X] max_chars of 0 means "share this budget"
max_knowledge_facts50Cap knowledge graph facts per prompt (0 = unlimited)

[nextcloud]​

SettingDefaultDescription
url""Nextcloud server URL
username""Bot's Nextcloud username
app_password""Nextcloud app password
share_default_expire_days14Default expiry on links the bot creates
dav_prefix""Where the storage root sits in the bot's Nextcloud tree; prefixed onto every DAV/OCS path. Empty when the workspace is the root of the bot's files; otherwise the folder that holds it, which istota setup asks for. A Nextcloud moved out of an old stack uses "Shared Files" (see Moving the bundled Nextcloud)
auto_share_bot_dirtrueShare the bot workspace back to the user over OCS at boot. False where the deployment already mounts it into the user's tree

[nextcloud.sharing]​

The highest access a user may give the bot to their calendars and address books from the Nextcloud card on Settings > Connections. The ceiling bounds raising a share only: lowering or removing one is always allowed, and a share made by hand above the ceiling is shown at its real level.

SettingDefaultDescription
calendars"full""off", "readonly" or "full". An unknown value falls back to "off" with a warning, and istota apply refuses a plan carrying it
contacts"full"The same, for address books

[talk]​

SettingDefaultDescription
enabledtrueEnable Talk polling
bot_username"istota"Bot's username (to filter own messages)
attachment_max_mb50When the workspace is not the Nextcloud mount, a file posted in Talk is fetched over WebDAV into Channels/<room>/media/<message id>/, once per message. Files larger than this are skipped and the task runs without them
attachment_retention_days30Days a fetched attachment is kept before the cleanup pass removes it; 0 keeps them. Not used when the workspace is the mount

[talk.signaling]​

Receive Talk messages over Nextcloud's standalone signaling server (the high-performance backend) instead of polling for them. With enabled = true the daemon stops running the Talk poll loop entirely — one driver, never two.

There is no credential here, and that is deliberate: istota connects to the signaling server as its own Nextcloud user, so the server URL, the hello token and the per-room session id are all minted on demand by Talk from calls the bot account can already make. The protocol's other option, an internal client holding the signaling server's shared secret, can join any room on the instance and is not implemented.

Two prerequisites, and each is a refusal to boot rather than a fallback to the poller: the HPB has to be registered with Talk already (occ talk:signaling:list), and the websockets library has to be installed (the signaling extra, included in all and test but not in local). A daemon quietly polling while an operator believes push is live is worse than one that did not start.

While watching, istota holds an active Talk session in every room it watches, so it shows as present to everyone else in those rooms. It is not in a call and never joins one. A second daemon pointed at the same Nextcloud opens its own sessions and receives every event; duplicate work is prevented by the read cursor rather than by the transport.

SettingDefaultDescription
enabledfalseTake Talk messages over the signaling server instead of the poll loop
url""HPB base URL. Empty means "use whatever Talk advertises" — set it only where the daemon reaches the server by a different route than browsers do
room_sync_interval300Seconds between room reconciliations. Also the safety net: each pass compares every room's latest message id against the stored cursor and fetches only the rooms that are behind, so it bounds how long a gap lasts when the event stream is down. It is also the worst case for the first message in a brand-new room
reconnect_backoff_max60Reconnect backoff ceiling, seconds. The proxy in front of the signaling server drops every connection hourly whatever the traffic, so reconnect is an ordinary event
payload_directfalseIngest the relayed message directly instead of refetching the room. Talk sends a message with the event only from about Talk 21; below that every event is a bare notification and this changes nothing. The relayed message was measured field for field identical to the fetched one on Talk 24.0.4; it stays off by default because it is the only part of the design that can be wrong about message content rather than timing

[email]​

SettingDefaultDescription
enabledfalseEnable email
imap_host""IMAP server
imap_port993IMAP port
imap_timeout_seconds30IMAP socket timeout
imap_user""IMAP username
imap_password""IMAP password
smtp_host""SMTP server
smtp_port587SMTP port
smtp_user""SMTP username (defaults to imap_user)
smtp_password""SMTP password (defaults to imap_password)
poll_folder"INBOX"Folder to poll
bot_email""Bot's email address
signup_task_window_minutes30The first message to a signup address within this many minutes of the tag opening mints one follow-up task. Later messages are filed and raise a notification. 0 files every message and mints no task
signup_body_retention_days14Filed signup message bodies are cleared after this many days. The message rows stay
outbound_approval_floor"untrusted"Minimum outbound email approval policy for every user: off (never hold) | untrusted (hold unless every recipient is trusted) | all (hold unless every recipient is one of the user's own addresses). A user may tighten past the floor but never loosen below it, and a user who has never set their own policy follows the floor, so raising it reaches everyone. An invalid value fails the config load rather than falling back — see the outbound approval gate
confirm_sender_match"off"What an own-address claim buys: off (the header is proof — assumes the MTA enforces DMARC) | verify (proof only when the MTA's own stamp says so; needs authserv_id, and the daemon refuses to load without it) | gate (never proof; every self-sent message is held). Legacy false/true still load as off/gate — see confirm_sender_match
dmarc_canarytrueWarns when mail routed on a user's own address arrives without a dmarc=pass from the receiving MTA. Monitoring for the assumption above; never blocks mail — see the DMARC canary
dmarc_canary_warn_on_missingfalse, or true when authserv_id is setAlso warn when your MTA's stamp carries no DMARC verdict at all. Off by default because a path that stamps nothing would warn on every message. Turn it on once you know your MTA stamps: it is the only way a mailbox moving to a provider that does not evaluate DMARC ever surfaces. Left unset, it follows authserv_id, since setting that says your MTA stamps
thread_disclosure_footerfalseEnds every plain-text mail the bot sends into a multi-person thread with one line naming the bot, the host and the !<name> off switch. Off by default, since mail from the bot's address is already from the bot
imap_security"""tls" or "starttls". Empty picks by port: 993 is implicit TLS, any other port upgrades with STARTTLS. Certificates are always verified — see email
smtp_security""The same for SMTP: 465 is implicit TLS, any other port STARTTLS
authserv_id""Your receiving MTA's authserv-id — the first field of the Authentication-Results header it stamps. Set it and headers from any other authserv-id are discarded rather than read; blank keeps the older topmost-header-only read, which a sender can forge once the MTA stops stamping. Write the single token before the semicolon, without any version number that follows it. Setting it also makes mail arriving without your stamp warn on its own — see the DMARC canary

[mail_accounts]​

Mail accounts users connect in Settings > Connections or with istota mail-account. Separate from [email], which is the bot's own mailbox. A server on a private address needs a mail_accounts grant in [private_hosts]. See email.

SettingDefaultDescription
enabledtrueOff keeps the accounts and makes every one unreachable
allow_sendtrueOff makes every account read-only
max_per_user10Accounts one user may connect

[sms]​

One provider-neutral SMS surface backed by Twilio or Telnyx. See the SMS setup guide for provider portal steps, phone-number authority, opt-outs, and switching.

SettingDefaultDescription
enabledfalseAccept inbound SMS work and send new messages through the active provider
provider"twilio"Active provider: twilio or telnyx
service_numbers[]Exact E.164 numbers allowed to receive inbound messages
default_sender_number""Default outbound E.164 number; must be in service_numbers
max_segments6Per-message segment ceiling, from 1 through 10
request_timeout_seconds10Provider API timeout, from 1 through 30 seconds

[sms.twilio]​

SettingDefaultDescription
account_sid""Account checked on signed inbound events
auth_token""Secret used only for Twilio webhook validation. Set it as the stack secret file istota_sms_twilio_auth_token
api_key_sid""Restricted API key SID used for outbound sends. Stack secret file istota_sms_twilio_api_key_sid
api_key_secret""Restricted API key secret used for outbound sends. Stack secret file istota_sms_twilio_api_key_secret
messaging_service_sid""Messaging Service whose sender pool carries outbound messages

[sms.telnyx]​

SettingDefaultDescription
api_key""API secret used for outbound sends
public_key""Ed25519 public signing key used for webhook validation
messaging_profile_id""Messaging Profile checked on inbound events and used for sends

When SMS is enabled, the common block and active provider block must be complete. A provider block with any value must also be complete when inactive. This lets its adapter authenticate late delivery callbacks after a switch without accepting new inbound tasks.

[whatsapp]​

One WhatsApp business phone number, reached through one adapter. Inbound it takes text and photographs, outbound it sends text, and the one-to-one chat with each user has a private room, read-only in web chat, that records the conversation without ever causing a send. See the WhatsApp setup guide for the Meta portal steps, the three operating modes, enrollment, and what the billing controls can and cannot see.

Three settings are at this level; each adapter's own are its nested block.

SettingDefaultDescription
enabledfalseAccept inbound WhatsApp work and send
provider"baileys"Which adapter sends and receives: baileys (a paired WhatsApp Web session, free and unmetered, no Meta account) or whatsapp_cloud (Meta's hosted Cloud API)
business_phone_number""Exact E.164 number this deployment sends from, whichever adapter holds it
group_bare_file_hold_seconds30In a group, a member's photo or GIF with no caption waits this long for the same member's next message, which is then read as its caption so the two get one answer. 0 answers the file at once

A configuration written before the adapters existed put every [whatsapp.cloud] setting below directly under [whatsapp]. It still loads: those keys are read as the nested block, and one carrying a waba_id, a phone_number_id or one of the three credentials selects whatsapp_cloud when no provider is set, so an existing Cloud deployment keeps its adapter and its webhook. The flat spelling is deprecated and will be removed.

[whatsapp.cloud]​

Meta's Cloud API, used directly rather than through a Business Solution Provider. Read only under provider = "whatsapp_cloud", and refused at load only under it — a Baileys deployment need not carry a WABA id.

SettingDefaultDescription
waba_id""Decimal WhatsApp Business Account id; an event from another WABA is rejected
phone_number_id""Decimal business phone number id from the Meta app, not the phone number
access_token""System-user token with whatsapp_business_messaging. Stack secret file istota_whatsapp_access_token (ISTOTA_WHATSAPP_ACCESS_TOKEN)
app_secret""Meta app secret; validates X-Hub-Signature-256 over the raw webhook body. Stack secret file istota_whatsapp_app_secret (ISTOTA_WHATSAPP_APP_SECRET)
verify_token""Shared secret Meta echoes on the GET verification handshake. Stack secret file istota_whatsapp_verify_token (ISTOTA_WHATSAPP_VERIFY_TOKEN)
graph_api_version""Empty follows the version the installed PyWa release pins. An explicit v23.0-style value is for a controlled migration
business_timezone"UTC"IANA zone the monthly quota month is computed in
request_timeout_seconds10Cloud API timeout, from 1 through 30 seconds
billing_policy"free_guard"free_guard (no templates, local attempt cap, circuit breaker on the first billable status) or allow_paid
monthly_service_attempt_limit900Service-message attempts per business number and calendar month. 1 to 1000 under free_guard; under allow_paid, 0 means no local cap

[whatsapp.baileys]​

SettingDefaultDescription
session_dir""Where the paired session is stored. Empty derives it beside the database. The session is a full-account credential
library_version""Pin the sidecar's Baileys version. Empty follows what the shipped sidecar pins
sidecar_command""The command that runs the Node sidecar, split by shell rules and not run through a shell. Empty means the daemon listens and spawns nothing, which is what a deployment running the sidecar as its own unit or compose service wants, and is better there, since systemd restarts a unit a permanent fatal stopped. istota whatsapp pair finds the program in a checkout on its own
pairing_enabledtrueWhether a session can be re-paired from Admin, Connections. false makes the pairing routes answer 404; istota whatsapp pair is unaffected
pairing_window_seconds300How long a pairing window stays open for a code to be scanned. For that span a pairing code, a full-account WhatsApp credential, can be relayed to the admin UI, so shorten this to narrow the exposure
pairing_relay_path""Where a pairing code is relayed between the process holding the sidecar and the web process. Empty derives it beside the database, 0600, where the task sandbox binds nothing; a path inside a sandbox-bound root is refused at the route
restart_interval_seconds0Roughly how long this deployment's supervisor waits before restarting the sidecar. It gates nothing — it sizes how long a pairing window waits before reporting the sidecar missing. 0 means undeclared, which is right wherever the supervisor backs off rather than waiting a fixed period (Docker). Under systemd, set it to the unit's RestartSec

[whatsapp.cloud.proactive_template]​

SettingDefaultDescription
enabledfalseSend one approved utility template when the 24-hour service window has closed. Valid only with billing_policy = "allow_paid"
name""The approved Meta template name (lowercase letters, digits, underscores)
language"en_US"The exact approved language code. Istota never creates, submits or substitutes a template

The three credentials never enter task environments, prompts, logs or the admin configuration page, and the business phone number is masked there. The attempt cap bounds Istota's own attempts only: a message sent from a coexistence client or another application consumes Meta's allowance without passing through the ledger, so free_guard is conservative rather than a guaranteed zero invoice.

[conversation]​

SettingDefaultDescription
enabledtrueEnable conversation context
lookback_count25Messages to consider
skip_selection_threshold3Include all if history <= this
selection_model"fast"Role alias for relevance matching (resolves to Haiku by default)
selection_timeout30.0Timeout for selection
use_selectiontrueUse LLM selection
always_include_recent5Always include this many recent
context_truncation0Max chars per bot response (0 = no limit)
context_recency_hours0Exclude old messages (0 = disabled)
context_min_messages10Min messages when recency filtering
previous_tasks_count3Unfiltered tasks to inject
talk_context_limit100Messages from Talk API

[speech_gate]​

Whether the bot replies to a turn nobody addressed to it, in a room more than one human reads. A direct conversation is never gated, and a turn that mentions the bot is always answered. Every turn is recorded whatever the mode. See shared rooms.

SettingDefaultDescription
mode"classifier""mention" answers only when addressed; "classifier" lets a cheap model decide and stays quiet when it fails; "off" answers every turn. An unknown value stays quiet
disposition"friendly"With the classifier: "reserved" answers a turn addressed to the bot, asking it for something or answering its question; "friendly" also answers thanks and other reactions to its last answer, in one short line, and treats the classifier as a lenient filter: a turn it lets through may be declined by the bot, which then posts nothing. An unknown value is "reserved". A room's host can override it for one room with !room disposition
ack_reaction"👍"Under "friendly", the reaction a turn that only acknowledges the bot (thanks, agreement, a joke, good news) gets on Talk and in WhatsApp groups instead of a reply, when ack_reactions has no list for its kind. One emoji; anything that is not one emoji is ignored with a warning. Empty turns reactions off everywhere, ack_reactions included, and every acknowledgement gets one short line. A reaction that cannot be sent falls back to the short line, and web chat, SMS and email always get the line
ack_reactionsthanks = ["👍", "🐙"], agreement = ["👌"], funny = ["😄", "🐙"], celebration = ["🎉"]A sub-table, [speech_gate.ack_reactions]: a list of emoji for each kind of ack the classifier names (thanks, agreement, funny, celebration) plus default. One is picked per message by its id, so a message always gets the same one. A kind that is missing, empty or holds no valid emoji uses default; with no default, ack_reaction is used, which is why the shipped table has none. The table wins over ack_reaction. A table in the config file replaces the shipped lists whole; an empty one leaves only ack_reaction.
model"fast"Role alias for the classifier, resolved per brain namespace
window_messages8Transcript turns the classifier sees
max_message_chars400Per-turn character cap inside the window
timeout_seconds20.0Classifier call timeout. A timeout means no reply. On the claude_code brain each call starts the CLI from scratch, which takes 4 to 8 seconds
decision_retention_days30Days to keep speech_gate_decisions rows (0 keeps them)

[logging]​

SettingDefaultDescription
level"INFO"Log level (INFO or DEBUG)
output"console"Destination: console, file, or both
file""Log file path
rotatetrueEnable log rotation
max_size_mb10Max log file size
backup_count5Rotated files to keep

[scheduler]​

Polling intervals​

SettingDefaultDescription
poll_interval5Seconds between queue checks
dispatch_interval0.5Sub-tick cadence for pool.dispatch() within a poll tick — bounds cold pending-task pickup latency. 0 or ≥ poll_interval = legacy one-dispatch-per-tick
talk_poll_interval10Seconds between Talk polls
talk_poll_timeout30Talk long-poll timeout
talk_poll_wait2.0Max wait before processing available rooms. Also the slack the cycle's own deadline adds over talk_poll_timeout, since an answer to a server-side long-poll cannot arrive before that hold elapses
talk_poll_full_sweep_interval300Seconds between polls of every room regardless of the lastMessage gate. Between sweeps only a room the room list says has a newer message is long-polled. 0 turns the gate off
email_poll_interval60Seconds between email polls
email_poll_batch_size50Messages one email poll walks. The remainder is left for the next tick and drains in arrival order, rather than falling off the end
email_rate_limit_messages60Inbound email tasks one user's account will pay for per window. The bot+{user_id}@domain address is public by construction (it is the From: on every mail the bot sends for that user), so anyone who has corresponded with the bot can turn one SMTP transaction into a paid model call. Over-budget mail is filed (routing_method="throttled", left in the mailbox, one alert per window), never dropped, and can still be read on demand with email from-senders. 0 disables
email_sender_rate_limit_messages20The same budget narrowed to one correspondent, so a single loud sender throttles alone rather than consuming the user's whole allowance. 0 disables
email_rate_limit_window_seconds3600The sliding window both counts run over, and the window the throttle alert and the collapsed confirmation prompts are deduplicated on
email_sender_flag_hold_threshold3Counted flags that hold an address's mail for the user's approval before any model sees it. A flag records that a mail looked like a prompt injection attempt, and only mail that passed aligned DMARC can earn one. 0 or less turns holding off; flags are still recorded
email_sender_flag_window_days90Age past which a flag stops counting and is pruned. 0 or less means flags never age
email_task_queuebackgroundWhich worker queue inbound mail lands on. Background by default: email is the one surface an unauthenticated stranger can create work on, and the one whose turnaround nobody is watching. foreground restores the previous behaviour at the cost of a flood competing with live chat
email_confirmation_prompts_per_window3Untrusted-sender confirmation prompts per (user, sender) per window before they collapse into one summary notice. The held mail stays held and individually approvable with !confirm <task-id>; only the interruption collapses. A sender held by flags gets one prompt per window rather than this many. 0 = never collapse
email_max_body_chars32000The body is interpolated whole into the prompt, so a single large message is its own amplification. Truncated with a marker past this; the full mail stays in the mailbox
email_max_attachment_bytes26214400Attachment bytes written to disk and uploaded per message (25 MiB). Not a bound on the IMAP transfer — the client fetches and decodes the whole message before any part can be inspected. Whole attachments only: one that would cross the budget is skipped rather than truncated, and the prompt names it. 0 = unlimited
email_max_attachment_bytes_per_poll104857600The same budget across one whole poll tick (100 MiB). A per-message cap alone bounds one message and not a batch of fifty. 0 = unlimited
briefing_check_interval60Seconds between briefing/job/cleanup checks
tasks_file_poll_interval30Seconds between TASKS.md polls; 0 turns them off. With full Nextcloud integration a poll reads the mount only after tree_watch_interval saw a change, or hourly
shared_file_check_interval120Seconds between shared file checks; 0 turns them off. Gated by the tree watch the same way
tree_watch_interval30Seconds between checks of whether anything under the bot's Nextcloud root changed, with full Nextcloud integration. The TASKS.md poll, the CRON.md sync and the shared-file organizer then read the mount only after a change, or hourly. 0 turns the check off: the three read on their own intervals, and on the VM's rclone mount a change made in Nextcloud then takes up to ten minutes to show
heartbeat_check_interval60Seconds between heartbeat checks; 0 turns them off
db_health_check_interval86400Seconds between SQLite quick_check + self-heal REINDEX sweeps over framework + per-user DBs (24h)
doctor_check_interval3600Seconds between re-runs of the istota doctor runtime self-check (1h; 0 disables). Re-run rather than trusted from boot, because the drift it catches happens after boot — a mount drops, a credential expires, a binary goes missing under a config the daemon already loaded
worktree_reap_interval21600Seconds between developer-worktree reaping sweeps (ISSUE-288, 6h; 0 disables). Also gated by [developer] worktree_reap_enabled. Well under the 24h default retention, so nothing waits long after becoming eligible. A periodic job rather than a task setup hook: setup_env hooks run for every skill whatever the task selected, so a sweep there fired on every Talk reply and every heartbeat tick
sandbox_cache_sweep_interval21600Seconds between package-cache sweeps (ISSUE-317, 6h; 0 disables). It follows the caches rather than a key: with [developer] enabled and repos_dir both set it walks {repos_dir}/{user_id}/.package-caches for each configured user, and otherwise {root}/{user_id} under [security] sandbox_cache_dir, so it is inert only where neither is set. Also gated by [security] sandbox_cache_sweep_enabled. Moving the caches onto disk is what makes them persist, so this is what keeps the fix for a RAM leak from being a disk leak on the volume worktree_reap_interval is already fighting for
avatar_import_interval21600Seconds between Nextcloud profile-picture import ticks (6h; 0 disables). Also gated by [web] avatar_import_from_nextcloud and by the storage backend being Nextcloud. On a cadence rather than at login (which would put a Nextcloud timeout in front of authentication) or on render (a live proxy), so a user who has just signed in for the first time sees the initial chip until the next tick — which is why it is six hours rather than daily
skill_overlay_reindex_interval21600Seconds between memory-search reindexes of every configured user's per-skill overlays (ISSUE-343, 6h; 0 disables). An overlay is a user-written file with no CLI write path, so there is nothing to index from on write, and the per-write reindex never covered a text-editor edit over Nextcloud anyway — which is the authoring mode the file is for. One pass walks the directory, indexes only what actually binds, and reaps rows for files that no longer do, so an edit, a create and a delete are all covered. Deliberately a scheduler tick rather than part of the sleep cycle: that pass is gated on [sleep_cycle] enabled and on the primary brain's breaker, while [memory_search] enabled is an independent setting, and this makes no model call. Seeded to 0 so a fresh daemon indexes on its first tick — a restart is the one moment an overlay edited while the daemon was down is guaranteed to be unindexed. Skipped without a mount and without [memory_search] auto_index_memory_files
credential_backup_interval86400Seconds between scheduled age credential backups; 0 disables them
scheduler_stats_interval60Seconds between scheduler_stats health-line emits (threads / fds / rss / running-tasks / active-workers) — one key=value INFO line per interval on the istota.scheduler.stats logger, for catching resource leaks early (grep it in the journal). 0 disables
loop_stall_alert_seconds180Defense-in-depth: a watchdog thread logs an ERROR and fires one operator alert if the single-threaded main dispatch loop hasn't ticked in this long (a slow call that slipped onto the loop thread, a wedged check), then re-arms when the loop recovers. Suspended around known multi-minute in-loop work (sleep cycles, DB-health sweep) to avoid false pages. 0 disables

Progress & event streaming​

One persisted, typed event stream per task (the task_events table) feeds Talk, the web SSE endpoint, the log channel, and push notifications.

SettingDefaultDescription
progress_updatestrueMaster toggle for Talk progress updates
progress_show_tool_usetrueEmit tool_start / tool_end events
progress_show_textfalseEmit progress_text events (intermediate text; noisy)
event_log_enabledtrueWrite events to the task_events table (kill-switch for task-event-streaming)
stream_text_gate_chars280Narration gate for streamed answer text on stream surfaces (web/REPL). A text run emits no text_delta until it crosses this many chars without an intervening tool call, so short lead-in narration ("Let me check…") is discarded at the tool boundary instead of leaking into the answer area. A block that crossed it is kept, and web chat renders it as its own block rather than folding it into the activity chip. Higher folds more pre-tool text away but animates short answers less (they still arrive whole with the final result); lower shows more intermediate text live. Keep it equal to the web client's SUBSTANTIAL_TEXT_CHARS, and tune it from the stream_gate: log lines. Never loses text — only animation. 0 disables
push_notification_threshold_seconds30Min task duration before an ntfy completion push fires
push_notification_sources[]Source types that trigger a completion push; empty = ntfy opt-in only (never a default surface). ntfy still fires for explicit requests (scheduled jobs with output_target = "ntfy", heartbeat alerts)

Worker pool​

SettingDefaultDescription
max_foreground_workers5Instance-level fg worker cap
max_background_workers3Instance-level bg worker cap
user_max_foreground_workers2Global per-user fg default
user_max_background_workers1Global per-user bg default
long_task_threshold_minutes10A running foreground task older than this stops counting against its user's interactive cap (0 = disabled)
user_max_long_workers1Per-user allowance of discounted long tasks; additive, so the per-user fg thread ceiling becomes 3
max_long_workers2Instance-wide budget of discounts, partitioned inside max_foreground_workers, which stays the hard thread ceiling
worker_idle_timeout10Cumulative idle seconds a worker lingers before exiting. A follow-up task arriving inside this window is claimed within one worker_idle_poll_interval instead of waiting a full poll_interval
worker_idle_poll_interval0.5Idle worker's queue re-check cadence, so a quick follow-up message is picked up in under a second. 0 or ≥ worker_idle_timeout restores the older single wait and single recheck
main_loop_read_timeout_ms2000SQLite busy-timeout for the main dispatch loop's read-only scans. A database locked past it makes the loop skip the tick (it re-dispatches about 0.5s later) instead of blocking up to 30s and tripping the stall watchdog. 0 keeps SQLite's 30s default. Defense in depth on top of WAL; leave it at 2000 unless you have a reason

Robustness​

SettingDefaultDescription
task_timeout_minutes30Claude Code execution timeout
confirmation_timeout_minutes120Auto-cancel confirmations after
stale_pending_warn_minutes30Warn for long-pending tasks
stale_pending_fail_hours2Auto-fail ancient tasks
worker_heartbeat_seconds60How often a running worker pings liveness (0 disables). Stuck-task reclaim uses the heartbeat to tell a slow-but-alive worker from a dead one.
worker_stuck_minutes10Reclaim a heartbeating worker's task after this much heartbeat silence. Independent of task_timeout_minutes. Higher means fewer false reclaims of a slow but alive worker (which would re-run the task), at the cost of slower recovery after a real worker crash
task_retention_days7Delete old completed tasks
usage_retention_days180Prune token/cost records. Kept far longer than tasks so spend history survives task cleanup; 0 disables. 180 rather than a year because the backup job snapshots the whole framework database into several dated directories, so every row is duplicated on the backup target
email_retention_days7Delete old IMAP emails (0 = disable). The sweep is an IMAP BEFORE search, so its cost follows what has expired rather than a fixed slice of the newest mail
processed_email_retention_days90Prune the processed-email dedup ledger (0 = disable). One row is written per polled message, task or not, so the table grows without this. Floored at email_retention_days + 1, because the row is what stops a message still in the mailbox from being ingested again; disabled entirely when email_retention_days is 0. A row still referenced by the stored conversation transcript is always kept, since it carries the sender attribution for that turn
talk_cache_max_per_conversation200Max cached Talk messages
scheduled_job_max_consecutive_failures5Auto-disable threshold
cron_max_staleness_minutes60Skip cron-driven catch-up fires older than this (jobs + briefings). After a long daemon outage, fires missed by more than N minutes are skipped and last_run_at is bumped so the schedule resumes from the next future fire. 0 = legacy unconditional catch-up.
log_channel_show_skillstrueInclude selected skills in log channel messages
max_retry_age_minutes60A task older than this is failed rather than retried
temp_file_retention_days7Delete task temp files older than this
location_ping_retention_days365Prune per-user location.db pings older than this

Subtasks​

SettingDefaultDescription
max_subtasks_per_task10Cap on subtasks one task may queue
max_subtask_depth3Cap on subtask nesting depth
max_subtask_prompt_chars8000Cap on a subtask's prompt length

Subtasks are created when an admin task writes a deferred JSON request, so these caps bound how much fan-out a single prompt-injected task can cause. With max_subtask_depth = 3, a chain such as talk → subtask → subtask → subtask is allowed and nothing deeper; 0 disables subtasks.

Database backup​

SettingDefaultDescription
db_backup_enabledtrueTake timed online-backup snapshots of the local DBs
db_backup_interval86400Seconds between snapshots (24h)
db_backup_dir""Destination for dated snapshot dirs; empty derives {workspace_path}/Backups/db/snapshots. Any destination resolving at or under a configured workspace_mount_path is skipped while that mount is not mounted, rather than written to local disk under a stale mountpoint. Symlinks on either side are followed, so how the path is spelled does not change the answer. A destination outside the mount is taken at face value. Use db_backup_enabled = false to disable
db_backup_retention7Keep this many snapshot dirs

Host memory: breadcrumb, admission gate, snapshots​

SettingDefaultDescription
host_pressure_enabledtrueMaster switch for host-memory sampling. false turns off the breadcrumb, the gate and the snapshots together
host_pressure_breadcrumb_interval_seconds300Seconds between host_pressure lines (0 = disabled)
host_pressure_sample_interval_seconds30Seconds between the samples the admission gate and the snapshot trigger read (0 = disabled). Faster than the breadcrumb because this reading feeds a decision rather than a series
min_available_memory_mb768Admission floor. Below this much MemAvailable, no new worker is spawned and no idle worker claims; pending rows wait exactly as they do when a cap is full. 0 disables this half of the gate
host_pressure_psi_threshold40.0memory some avg10 above this also counts as pressure and closes the gate. 0 disables this half. With both this and min_available_memory_mb at 0 the gate is open unconditionally
host_pressure_alert_cooldown_seconds900Minimum gap between threshold snapshots, between admin notifications, and between the dispatch_admission_closed log lines for one continuous closed stretch
host_pressure_shmem_unaccounted_alert_mb1024A third snapshot trigger: shmem that no filesystem accounts for, above this many MB. Deliberately not wired into the admission gate — a residue swap absorbs is a reason to collect evidence, not a reason to refuse work. 0 disables
host_pressure_docker_socket/var/run/docker.sockRead-only handle used only to ask Docker which pid a container has, so its tmpfs can be read through /proc/<pid>/root during a snapshot. Empty disables container lookup

One breadcrumb line per interval carries MemAvailable / Shmem / SwapFree / PSI / per-tmpfs usage / shmem_unaccounted, written whether or not the host is under pressure — 288 lines a day at the default. See host memory breadcrumb for why it is unconditional and what shmem_unaccounted answers, and admission gate for what the gate does and does not touch.

The gate fails open in every uncertain case — sampling disabled, no sample yet, a sample that would not parse. A broken sampler must not be able to halt all dispatch.

Per-task cgroups​

SettingDefaultDescription
task_cgroup_enabledtruePut each task's process tree in its own cgroup v2 group, so a runaway build or test suite is OOM-killed inside its own group instead of taking the host down. No-ops with a log line on a deployment whose unit file has no delegated subtree
task_memory_max_mb2048memory.max per task (0 = unbounded)
task_pids_max512pids.max per task — bounds a fork storm
task_cpu_max_percent200cpu.max as a percentage of one core (200 = two cores; 0 = unset)

These need a cgroup subtree delegated to the daemon, which the stack's root phase sets up (ISTOTA_TASK_CGROUP_ROOT); under systemd it is Delegate= with DelegateSubgroup=supervisor on the scheduler's unit. Without it containment never engages; the daemon says so once in the startup log rather than looking protected. See per-task cgroups.

[security]​

SettingDefaultDescription
sandbox_enabledtrueBubblewrap filesystem isolation (Linux only)
skill_proxy_enabledtrueCredential proxy via Unix socket. Required wherever sandbox_enabled is true, for two reasons. Turning it off leaves every configured service credential in the task environment, readable by the model from inside the sandbox rather than injected per call — the quiet cost, and the one that undoes what the sandbox is for. It also leaves skill CLIs running inside the sandbox, where the databases they read are masked out, so a CLI that can't reach the proxy refuses rather than reading nothing
skill_proxy_timeout300Proxy command timeout (seconds). Capped at skill_client_wait_seconds minus 30; [security.skill_proxy_timeouts] gives one skill a different budget under the same cap
skill_client_wait_seconds600How long the sandboxed istota-skill client waits on the proxy socket. The bound every skill budget sits under — the global and every per-skill entry are capped at this minus a 30s margin, so a skill wanting more than 570s needs this raised too. Exported to the client as ISTOTA_SKILL_CLIENT_WAIT; the proxy derives its ceiling from this field, never from the export, which lives in the model's environment
credential_history_days180Retain old credential versions for this many days, up to ten per field
credential_audit_days365Retain credential activity records for this many days
credential_exports_per_day3Credential exports one user may make from the web UI in 24 hours. Values below 1 count as 1
credential_backup_retention30Keep this many scheduled age credential backups
skill_proxy_max_connections64Open connections one task may hold on the skill proxy. A call past it is refused as busy, at once and without a thread
skill_proxy_max_concurrent8Skills one task may run at once. A call past it waits for a slot, up to what remains of skill_client_wait_seconds after the skill's own timeout and the 30s margin, then is refused as busy
skill_proxy_max_output_mb16Stdout plus stderr one skill call, CRON command: row or heartbeat shell-command check may produce. Past it the process group is killed and nothing is returned
network_proxy_max_connections128Open connections one task may hold on the network proxy. A connect past it gets a 503
vault_fetch_limit_per_task10How many distinct shared credentials (the vault_entries namespace a user's credential store produces) one task attempt may read over the proxy, on the model's socket and a skill's private channel alike. A credential already served in full this attempt can be read again at no cost on the same channel (a value a skill was given privately is charged again when the model asks for it), so a skill that resolves its entry on every call (WordPress, for one) spends one fetch for the session. 1 limits a task to one credential. 0 is unlimited and is the only spelling of unlimited — an absent key is this default, never "off". Enforced by the proxy rather than by the istota-credential shim the model calls, since that program sits in a directory the model can overwrite. A request for a name not yet served in full, whether it does not exist or the proxy refuses it, is charged every time, so probing for absent names is not free; listing the namespace is not counted. A skill that reads a whole entry (password, username, URL and custom fields together) spends one fetch for it. This is a bound on how many secrets a task can reach, not on how many calls it makes with them
allow_unsandboxed_multi_user_vaultsfalsePermit credential vaults for multiple configured users without effective sandboxing. This accepts same-uid cross-task credential exposure. Applies to imports, credential writes and task access, including cached credentials. Restart services after changing it. See credential vault
vault_writes_per_task3How many vault_create requests (istota-credential new) one task attempt may make, refusals included. A capability gate rather than a budget: 0 disables model-requested vault writes, and unlike vault_fetch_limit_per_task it never means unlimited. See credential vault
scheduled_job_max_unapproved"public"The furthest reach a new scheduled job gets with no approval: limited, public or full. Past it the job runs limited and asks its owner. An unknown value falls back to limited — see scheduling
wallet_requests_per_task3Purchase requests one task attempt may make — see wallet
wallet_fills_per_purchase3Checkout fills one approved purchase may use
wallet_authorization_minutes30How long an approved purchase stays usable
passthrough_env_vars["LANG", "LC_ALL", "LC_CTYPE", "TZ"]Extra env vars for subprocess
sandbox_ro_paths[]Extra RO bind-mounts in the sandbox, for co-located services. Keep entries narrow — a broad path sweeps in whatever lives under it. The DB directories are masked after this list either way
sandbox_cache_dir""The fallback root for the package managers' caches, read only where the developer skill is not configured. With [developer] enabled and repos_dir set, each user's cache is derived at {repos_dir}/{user_id}/.package-caches and this key is not consulted at all — so setting it on a developer deployment names a path nothing uses while reading like the intended one. Where it is read, each user gets {root}/{user_id}, bound RW into their sandbox with UV_CACHE_DIR, XDG_CACHE_HOME and npm_config_cache pointed at it. Empty leaves those caches on bwrap's own root tmpfs — RAM the host cannot attribute, discarded at task exit, so every task downloads again. The derivation exists for the mount rather than for tidiness: uv populates a venv by hardlinking out of its cache and link(2) compares mounts rather than devices, so a cache outside the bound subtree returns EXDEV even on the same filesystem and every worktree pays for a full copy. On this fallback branch nothing binds an ancestor, so that copy is what a venv in the task workspace pays — the same cost as before ISSUE-305 addressed the RAM, not a new one. The root must already exist and be writable. Ignored with one warning when relative, missing, unwritable, under a database directory, or at or above a path the sandbox already mounts, since a bind above an earlier mount would cover it: so not temp_dir, ~/.cache, ~/.local or repos_dir itself
sandbox_cache_sweep_enabledtrueBound what the per-user caches grow to (src/istota/maintenance/sandbox_cache_sweeper.py). Every sweep runs the package managers' own cheap reclaim (uv cache prune, npm cache verify); a per-user cache still over its ceiling afterwards is wiped with their clean verbs. The sweeper deletes no file itself — a tool that is missing, that fails or that times out is reported and the cache is left alone. A user with a task in flight is skipped entirely, and --force is never passed to uv, so its own in-use check still stands. On the derived layout the sweep is over the users the daemon knows about rather than the directory names it finds, so a cache belonging to nobody configured is reported and left rather than swept. Runs on [scheduler] sandbox_cache_sweep_interval
sandbox_cache_max_gb10.0The ceiling, per user, over the whole of that user's cache directory. One uv sync --all-extras writes about 1.8 GB, so the ceiling has to clear one resolution; on a small disk shared with the worktrees, 4.0 is a reasonable setting. A size budget rather than an age window for the same reason — one command writes more than any sane window's worth of bytes at once. Clamped to a 1 GiB floor: below that the ceiling is under one dependency resolution's working set, so every sweep would wipe a cache that is doing its job. XDG_CACHE_HOME points at the user's cache directory, so a third tool's cache counts toward the budget while neither reclaim verb can touch it — that case is reported with the largest remaining subdirectory named, not deleted by hand

[security.skill_proxy_timeouts]​

Per-skill overrides of skill_proxy_timeout, in seconds, applied instead of the global for the skills named (browse = 90). An entry narrows as readily as it widens. Every entry, and the global, is bounded by the wait the sandboxed client arms before it sends: skill_client_wait_seconds minus a 30s margin, so 570s at the default.

code_review has a 540s ceiling of its own without an entry here. It is the only skill that drives model calls, and raising the global to suit it would hand the same minutes to every other skill. That value lives in the code rather than in this table's default because a table an operator writes replaces the default instead of merging with it, so shipping the entry here would mean that setting any other skill silently took the review's ceiling back to the global. Naming code_review here still overrides it.

sandbox_admin_db_write was removed: the framework DB is no longer bound into the sandbox for anyone, so there is no bind left to widen. A stale key logs a warning and is ignored.

[security.credential_broker]​

Substitutes credential placeholders in authentication headers, for hosts a credential is bound to, so a task uses a credential without holding its value. Needs the network proxy and effective sandboxing. See Credential broker.

SettingDefaultDescription
enabledtrue on Linux with sandbox_enabled and [security.network] enabled, otherwise falseTurn the broker on. When the key is absent the default follows the sandbox and the network proxy; a value you write is kept
enforce_revealsame as enabledtrue refuses public value reads (istota-credential get, run, env) of entries without the istota:reveal tag. false returns them and logs each one (credential_reveal, action=would_refuse). No effect while enabled = false
scan_max_bytes1048576Request scan limit; responses past it stream, still scrubbed
leaf_validity_hours24Lifetime of the per-host TLS certificates the broker issues

[security.network]​

SettingDefaultDescription
enabledtrueNetwork isolation via CONNECT proxy
allow_pypitrueAllow PyPI access
extra_hosts[]Additional allowed hosts, as host:port. An entry may be on your own network (a private, loopback or link-local address). No Anthropic host is on the default list; a task that calls Anthropic's API from Bash needs api.anthropic.com:443 here
private_hostsRetired and ignored, with a warning. An extra_hosts entry already allows a private address. The top-level [private_hosts] table is a different permission

[skills]​

There is no [skills] config section. Skill disclosure is single-axis (a skill is either eager or a menu entry the model loads on demand) with no config knobs. A stale [skills] block only logs a warning at load time.

[models] enabled​

Which models a non-admin may pick with !model, !room model, the room settings and a model in their CRON.md. A list of glob patterns over provider/id references, matched case-insensitively:

[models]
enabled = ["anthropic/*", "openrouter/z-ai/glm-5*", "openrouter/moonshotai/kimi-k2*:high"]

An entry may end in :effort, the effort offered when that model is picked; it does not narrow the match. A deprecated model is matched only by an entry naming it exactly. Unset, the list is anthropic/* plus <native's provider>/<[brain.native] model> when native has a provider, which is what non-admins could run before the setting existed. enabled = [] leaves non-admins the aliases only.

An admin picks from the whole catalogue, and an alias is always selectable by anyone, because the operator wrote it. The list bounds who may set a selection, not what runs: a room an admin pinned to a model outside it keeps running that model for every member's turn. A room or job stores the alias or the provider/id reference it was given (a bare id or a chat pattern is stored as the reference it matched) and resolves it when each task is created, so an alias change reaches it. istota doctor's models.catalogue check warns about a pattern that matches no model.

[models.aliases]​

The operator-visible model alias registry — one table holding both the portable tiers and the provider shortcuts, overlaying the shipped defaults, which name families rather than model ids. Used by !model <name> <prompt> in Talk/web and by internal subsystems (fast for triage/classification, general for sleep cycle, smart is user-facing only).

Shipped defaults (base names, no baked effort):

AliasDefault target
fasthaiku
generalsonnet
smartopus
opus / sonnet / haikuthe newest current model of that family in the catalogue
defaultno override (brain/config default)

A family follows the catalogue (see Models and providers), so a new Anthropic model reaches the tiers when the catalogue lists it, and !models shows what each resolves to today. On the native brain an unremapped tier means the room's provider's default model ([brain.native] model on native's default provider, [providers.<id>] default_model on another). Each alias may also take an effort-only table ([models.aliases.general] anthropic = { effort = "medium" }) that keeps the target and changes the effort.

Effort is an orthogonal :effort modifier appended to any reference (opus:high, smart:low, opus:xhigh) — never baked into a name. An alias override is per provider so one definition covers every room: anthropic = the claude_code brain and a native room on anthropic, any other provider id = a native room on that provider. The old openai_compat key is read, for one release, as native's default provider, ahead of that provider's own key. An alias with no target for a room's provider cannot be picked there and never resolves into another provider. Two forms, both accepted:

# Flat (one target for every provider, resolved by whichever brain runs the task):
[models.aliases]
smart = "claude-opus-4-6:high" # pin smart to Opus 4.6, effort high
deep = "opus:max" # a custom alias

# Per-provider (define once, correct in every room):
[models.aliases.smart]
anthropic = "opus:high" # CLI brains
openrouter = { model = "anthropic/claude-opus-4.8", effort = "high" } # a native room on openrouter
[models.aliases.general]
anthropic = "claude-sonnet-5"
openrouter = "anthropic/claude-sonnet-4.6" # bare string = no effort
[models.aliases.deep]
anthropic = "opus:max"
openrouter = "anthropic/claude-opus-4.8"
portable = true # a cross-brain custom tier

Alias targets carry effort: a :effort modifier on the target (opus:high → high) or an explicit effort = on a per-provider table reaches the wire (explicit wins). An alias uses one form (TOML: a key can't be both a string and a table). A per-provider table with no key for a room's provider has no operator target there: a built-in tier keeps its shipped meaning on that provider, and a custom alias cannot be picked there. A custom alias is a non-portable pin unless flagged portable = true (then it re-resolves across the cross-brain fallback boundary like the built-in tiers). Invalid anthropic targets (neither a known alias nor a versioned canonical Claude ID) are warned at config-load time via Brain.validate_alias_override; a target under another provider is sent as written.

The old [models.roles] key is a hard rename to [models.aliases] — no longer read; a stale one present logs a one-time migration warning. The old effort-in-name forms (opus-high, opus-46) no longer resolve.

[brain]​

Selects which model-invocation backend the executor uses. See architecture/brain for the protocol and the native brain runbook for the full [brain.native] settings.

SettingDefaultDescription
kind"claude_code"Brain implementation. "claude_code" (default) wraps the headless claude -p CLI subprocess; "native" runs Istota's own in-process agent loop against any OpenAI-compatible model (configured under [brain.native]). The "tmux_claude" brain was removed: a config that still names it loads as "claude_code" with a warning, and a [brain.tmux] block is ignored.
source_type_overrides{}Per-source_type brain override (e.g. route scheduled to native while interactive tasks stay on claude_code).
room_selectable[]Brain kinds a chat room may pin for itself, with !brain or the web room settings, and kinds a scheduled job may pin with brain in CRON.md. The name is narrower than the setting: one list bounds every pin written outside your own config, and both are admin-only on top of it. CRON.md is writable by the model through the schedules skill, so a non-admin's brain is dropped at sync with a warning and the job runs the configured brain. It is a gate rather than a preference: brain kind decides which process holds the agent loop, which tools it registers and which sandbox profile is built. Empty means none may, so the feature is inert until you name kinds. A name here that is not a brain kind is warned about at load and offered to nobody. Listing a kind also widens the doctor checks for it — claude on PATH, a native API key — whether or not anything has selected it. Neither a pinned room nor a pinned job fails over: it runs the brain it names or fails saying why.
custom_system_promptfalseAdd config/system-prompt.md to every brain's system prompt: the claude_code brain uses it in place of Claude Code's default, the native brain appends it to its own. For claude_code that one file, and nothing else in the config directory, is bind-mounted read-only into the sandbox, since the CLI opens it there. Formerly a top-level key, which still loads with a warning
fallback""Brain to rerun a request on when the primary is unavailable (a subscription usage limit, a missing binary), with that brain's own settings. A portable role tier (fast/general/smart) carries across the provider boundary; a provider-specific model pin drops to the fallback brain's own default, logged and noted in the reply. Single level only. "" means no fallback for every brain kind. A value equal to the kind a task runs on is no fallback for that task, so naming claude_code here with a source_type_overrides entry routing to native gives the routed tasks failover and leaves the rest alone. After a persistent unavailability, later tasks skip the primary for fallback_cooldown_seconds; a successful primary probe ends that early
fallback_on_transienttrueAlso reroute a persistent transient_api_error
fallback_cooldown_seconds900Skip an unavailable primary at most this long before retrying it; a usage limit against a Claude subscription instead ends at the quota's own reset (floor 60s). 0 disables

[brain.native] (used when kind = "native", when it is the fallback, or when a source_type_overrides entry routes to it): provider (the id of a [providers.<id>] record; no default, so a native brain without one is unavailable), providers (the other providers a native room or job may run on, opt-in; default empty, meaning provider alone; an admin picks one per room or job, see Models and providers), model (explicit id at that provider), effort, model_overrides, context_window, max_turns, max_tokens, compaction_reserve_tokens, compaction_keep_recent_tokens, compaction_background, compaction_background_tokens, bash_spill_full_output, turn_budget_nudge, turn_budget_nudge_early_percent, turn_budget_nudge_remaining, tool_failure_nudge_after, soft_deadline_percent, plus the nested [brain.native.web_fetch] SSRF-policy block. base_url, api_key, extra_headers, the wire settings and model_catalog_* are legacy, read for one release as native's provider's fields. The endpoint and its key are a provider's: [providers.<id>] takes kind (anthropic, openrouter, openai_compat), base_url, api_key (or ISTOTA_PROVIDER_<ID>_API_KEY), extra_headers (or ISTOTA_PROVIDER_<ID>_EXTRA_HEADERS, a JSON object that replaces the table), prompt_caching, prompt_cache_key, prompt_cache_ttl, strict_tool_schemas, reasoning_replay, a [providers.<id>.compat] table, discover, discover_ttl_hours, models and default_model (what a native room on that provider runs with no model of its own; native's default provider uses [brain.native] model). anthropic and openrouter are built in. [models.overrides."<provider>/<id>"] patches one model's catalogue fields. Full annotations in the native brain runbook.

soft_deadline_percent (default 90) stops the loop at that share of [scheduler] task_timeout_minutes, on a stop that keeps the model's partial work. The hard clock discards that work and max_turns delivers it, and on a slow brain the clock is what arrives first; the remaining slack still covers a turn that hangs. 0 or 100 and above disables it.

[brain.native.web_fetch]​

The native brain's daemon-side WebFetch tool, documented in the native brain runbook. Every user gets it, on either brain: a claude_code task is offered this tool through its tool harness rather than the CLI's own WebFetch. It was admin-only until ISSUE-449, on the grounds that a fetch from the daemon's network namespace is egress beyond the sandbox's CONNECT allowlist. That is true, and the policy fields answer it: they bound where a fetch may go, the same way for everybody, where identity bounded nobody's destinations. enabled = false withdraws it from everyone, and admin_only = true puts the old gate back for a deployment with users whose turns should not reach the network from the daemon's namespace at all. Fields the runbook's table does not list:

SettingDefaultDescription
allowed_ports[80, 443]A port not listed is refused before any connect
user_agent"IstotaBot/1.0"User-Agent sent with each fetch
extra_blocked_cidrs[]Operator additions to the private/reserved blocklist, such as a metadata endpoint or an internal range the shipped list does not know about

allow_http stays off for a reason: the fetch is unauthenticated but its content reaches the model, and cleartext is content anyone on the path can choose. require_url_provenance is for a deployment ingesting content it does not trust, since it stops the model composing a URL from data it read.

[brain.native.session_log]​

A per-attempt transcript of a native-brain run: one append-only JSONL file per task attempt holding the assembled prompt, every assistant turn with its thinking and tool calls, every tool result, every compaction and steer, and a terminal record. tasks.execution_trace keeps tool labels and no output, so this is the only record of what the model saw and did on a finished run. Native only; claude_code gets a transcript from the claude CLI.

The files hold the assembled prompt, which holds USER.md, and raw tool output, which can hold whatever a Bash call printed. They are written 0600 behind a 0700 per-user directory, on local disk, bound into no sandbox, and nothing copies them off the host. An operator who cannot accept a credential a task printed living there for the retention window sets enabled = false. On the stack, istota setup writes db_path = "/data/db/istota.db", so the directory is /data/db/logs in the state directory (/srv/app/istota/data/db/logs on the VM), beside the framework database and behind the same sandbox mask.

SettingDefaultDescription
enabledtruefalse writes no new files; retention still sweeps existing ones
dir"""" resolves to {db_path.parent}/logs, beside istota.db, modules/ and backups/ and behind the sandbox's database mask. A value set here is used as given, with no ~ expansion and no resolving against a base, so write an absolute path: a relative one follows each process's working directory, and the daemon, the sweep and an istota command from a shell need not share it. Outside db_path.parent gets a WARN from istota doctor; / and other values naming no directory of their own are refused. Otherwise the value is trusted, as [security] sandbox_cache_dir is: the retention sweep treats every subdirectory as a user's and unlinks the *.jsonl files under it, so point it at a directory istota owns. Nothing the model writes reaches this setting. The walk bounds a mis-set value: only *.jsonl, only under a first-level subdirectory (never a file at this directory's own level) but at any depth within one, never through a symlink, and rmdir only on a directory the sweep itself emptied
retention_days14Age rule, for privacy. Longer than [scheduler] task_retention_days on purpose: the log's value is that it outlives the task row. 0 keeps files for ever by age; the size ceiling still applies
max_total_gb2.0Size ceiling for the disk, across every user summed, since the filesystem also holds istota.db and every module DB. Lean on purpose: on a busy deployment this, not retention_days, is what binds, and istota doctor warns when the last sweep evicted by size. Eviction is largest user first, then oldest within that user, so a noisy neighbour cannot clear a quiet user's history. Clamped to a 0.5 floor; 0 means no ceiling
max_content_chars32768Per text or thinking block. Over the cap the block keeps its head and its tail (a build log's error is at the tail) and records the real length. 0 means no cap, unlike the two limits above where 0 switches the rule off
max_args_chars8192Per tool-call arguments object. Over the cap it becomes a marker rather than a truncated JSON fragment. 0 means no cap
include_thinkingtrueReasoning traces in the written log: the most useful record for debugging a wrong answer, and the bulkiest. Independent of istota-skill tasks transcript, where thinking stays off unless asked for

[brain.claude_code]​

This brain's own default model and effort, plus the subscription usage poll. Every field defaults in code, so an absent block is the shipping behaviour. See the subscription reading for what the poll does and why.

model and effort are read whatever kind is set to, because a fallback or a source_type_overrides entry can route here from another primary. They replaced the top-level keys, which were this brain's defaults sitting where they read as deployment-wide (ISSUE-418).

SettingDefaultDescription
model""This brain's default model when the task pins none. Same values the top-level key took: a canonical id, a shortcut (opus), a role tier (smart), any of them plus a :effort modifier. Empty = the CLI's own default. A bare shortcut floats to the latest version each release; a canonical id is immutable, so pin a versioned id for stability
effort""This brain's default effort: low, medium, high, xhigh, max. Empty = the model's own. A task that pins a model takes no effort from here, since an effort chosen for one model need not be valid on another
auth""How the claude CLI authenticates. "subscription": the OAuth token (CLAUDE_CODE_OAUTH_TOKEN, the claude_code_oauth_token secret file) and never an API key; the [providers.anthropic] base URL must be Anthropic's. "api_key": the [providers.anthropic] key and base URL, never the token. Empty is decided by each process from its environment: the token gives "subscription"; an API key alone never switches a deployment to API billing. Under either mode the credential is in the environment of the claude CLI only, which runs outside the sandbox with its tools in the sandboxed tool server; no task env carries it, and on a sandboxed deployment nothing the model drives can read it (on an unsandboxed one a Bash call can read any process of the daemon user). The sandbox's network allowlist names no Anthropic host. istota doctor reports the mode as models.cli_auth
advisor_model""Advisor model for this brain (the CLI's --advisor); resolves through the same alias table as model but carries no effort. Must resolve to a model capable of being an advisor (a weak/cheap tier fails every task it runs on). Dropped for any task carrying its own model pin (!model, !room model, a [[jobs]] model). Formerly a top-level key, which still loads with a warning
subscription_usagetruePoll api.anthropic.com/api/oauth/usage for plan utilization at all. Off = the doctor check SKIPs and the admin card is absent rather than showing a reason
subscription_usage_cache_ttl_seconds1800One deployment-wide fetch per this window, and the minimum backoff after a failure. A server-stated Retry-After overrides it, capped at six hours. Floored at 1 — a 0 would fetch on every read. 30 minutes rather than 5 because the shortest window reported is five hours, so polling faster buys no accuracy for the requests it spends, and the endpoint rate-limits a deployment that tries
subscription_usage_timeout_seconds10.0Matches doctor.PROBE_TIMEOUT. Floored at 1
subscription_usage_warn_percent80.0Doctor WARNs and the tile turns amber at or above this
subscription_usage_high_percent95.0The tile turns red at or above this — still a WARN, never a FAIL at any utilization, since a busy plan is a fact about the plan rather than a defect in the host. Both clamp to [0, 100]; a warn above high is lowered to high and logged, because an inverted pair leaves no amber band
subscription_usage_stale_after_seconds3600A cached reading older than this is reported SKIP rather than as a current number

The credential is not configured here. It is read — never written, never refreshed — from CLAUDE_CODE_OAUTH_TOKEN, then ~/.claude/.credentials.json, then the macOS keychain.

[sleep_cycle]​

SettingDefaultDescription
enabledtrueEnable nightly memory extraction
cron"0 2 * * *"Schedule (user's timezone)
lookback_hours24How far back to gather day data
memory_retention_days0Prune dated memory files and ephemeral memory_chunks rows (conversation, memory_file, channel_memory) older than N days. Durable user_memory chunks are not touched. 0 = unlimited
auto_load_dated_days3Days of dated memories injected into prompts; 0 disables
extraction_model"general"Role used for the nightly extraction call
curation_model"general"Role used for the USER.md curation call
curate_user_memoryfalseRun op-based USER.md curation after extraction
curation_log_summarytruePost a one-line summary to the user's log_channel after applied curation ops
knowledge_graph_audit_retention_days365Prune knowledge_facts_audit rows older than N days. Independent of memory_retention_days. 0 = unlimited

[channel_sleep_cycle]​

SettingDefaultDescription
enabledtrueEnable channel memory extraction
cron"0 3 * * *"Schedule (UTC)
lookback_hours24How far back to gather channel data
memory_retention_days0Prune dated channel files and channel_memory chunks older than N days. 0 = unlimited
extraction_model"general"Role used for the nightly extraction call
SettingDefaultDescription
enabledtrueEnable memory search
auto_index_conversationstrueIndex after task completion
auto_index_memory_filestrueIndex after sleep cycle
auto_recallfalseBM25 auto-recall in prompts
auto_recall_limit5Max recall results
recency_half_life_days180.0Age half-life for the recency down-weight; 0 disables

[briefings]​

Module-level settings for the briefings module (per-user content store + archive). All defaulted, so an absent block is the shipped behaviour.

SettingDefaultDescription
archive_retention_days90Prune archived briefing results older than this, on insert (0 = keep forever)
default_lookback_hours12Seeds the email / rss source window when a source omits it
newsletter_max_links_per_source20Cap on inline [anchor](url) links kept per newsletter body. Newsletters are mostly links, so the converter first drops unsubscribe, social and web-version chrome, and this caps what survives; an over-cap anchor keeps its text and loses only the destination. 0 = unlimited
max_source_chars5000Cap on a single source's gathered text. The todos source spends it item by item and never cuts one in half — a half-item would read as a todo the file does not contain — dropping from the end and saying in its provenance line how many were left out
max_browse_chars20000The same cap for a browse source, which gathers markdown rather than flattened text. Bigger because the URLs the markdown keeps cost characters, and a frontpage spends its first couple of thousand on masthead chrome before the headline grid starts. A browse source's own max_chars wins over either cap — it is the only kind that reads one; email, notes and todos take the module cap directly.
shared_block_timezone"UTC"Timezone module-owned shared blocks evaluate their cron in. Shared blocks are global (generated once, no per-user timezone), so this is one operator-chosen zone — typically the operator's own, so morning/evening regeneration lines up with their day. An invalid name falls back to UTC at run time.

[[briefings.shared_blocks]]​

Module-owned shared blocks generated once globally under the reserved __system__ identity and read by any user's briefing through a shared_block (or kv) source, so a frontpage fetch and synthesis many users share runs once in total. Seeded once into the shared_block_configs table, after which the DB is authoritative and admins manage them from the web UI or istota briefings shared. Leave unset for the canonical defaults (world-headlines, markets-summary); an explicit empty list ([briefings] shared_blocks = []) opts out. Formerly the top-level [[briefing_shared_blocks]], which still loads with a warning. Only user-agnostic source kinds are allowed (browse, markets, email). See briefings.

[[default_briefings]]​

Deprecated migration input, with the old personal name/cron/output/blocks shape. Existing effective defaults are preserved once during upgrade; new accounts receive no copied defaults. Import disabled All users definitions and review cutover with istota briefings migrate. DB edits win after import. See Migrating group briefings. New authoring uses Briefings or the group_briefings settings-plan section.

[developer]​

SettingDefaultDescription
enabledfalseEnable developer skill
repos_dir""Root of the per-user repository subtrees. A clone lives at {repos_dir}/{user_id}/{namespace}/{project}.git with its worktrees beside it, and an admin developer task has only {repos_dir}/{user_id} in its sandbox — never the root, so one admin's clones, worktrees, git configs and package cache are not in another's namespace. The package cache is derived at {repos_dir}/{user_id}/.package-caches. Create the root and give it to the daemon; everything below it is created per user. An existing shared tree is migrated by python -m istota.maintenance.repos_relocate, run by hand with the daemon stopped — it needs exactly one configured admin to know who owns the clones, and refuses rather than guessing. It leaves {repos_dir}/.package-caches behind, orphaned by the derivation and safe to remove by hand
gitlab_url"https://gitlab.com"GitLab instance URL. Userinfo (user:secret@) fails the config load, since the URL reaches the sandbox; the token goes in gitlab_token
gitlab_token""API token
gitlab_username""GitLab username for HTTPS auth
gitlab_default_namespace""Default namespace for short repo names
gitlab_reviewer""GitLab username to assign as MR reviewer. glab mr create --reviewer resolves by username
gitlab_reviewer_id""That user's numeric id. Recorded for reference; read by nothing
github_url"https://github.com"GitHub instance URL. Userinfo fails the config load, as for gitlab_url; the token goes in github_token
github_token""Personal access token
github_username""GitHub username
github_default_owner""Default org/user for short repo names
github_reviewer""PR reviewer username
author_credit""Name credited as author on commits the bot makes
forge_cli_extra_denied[]Extra verbs the gh / glab wrapper refuses, written as typed ("gh repo delete"); no binary name applies to both
forge_cli_permit[]Baseline deny entries to turn off — each one removes a guard. The baseline lives in code because it is a safety default rather than a preference. An entry that matches no baseline rule is warned about at startup, because a hatch that silently stopped matching reads like one still open
gh_bin_path"/usr/local/bin/gh"Real gh the wrapper execs. istota setup writes the image's path, /usr/local/lib/istota_forge/gh (off PATH, so the wrapper stays the only gh a task can resolve), since the default matches no shipped install
glab_bin_path"/usr/local/bin/glab"Real glab the wrapper execs, rendered the same way
devbox_proxy_enabledtrueRun the devbox credential proxy, which hands forge tokens to the users in [devbox] forge_users
devbox_proxy_socket_dir"/var/run/istota"Where the per-user devbox proxy sockets live
devbox_proxy_audit_log""Optional path for a devbox proxy audit log
worktree_reap_enabledtrueRemove a task worktree under repos_dir once every commit on it is upstream (squash- and rebase-merged branches included), the checkout is clean (untracked and gitignored files included), it is unlocked, and it has been idle for the retention window (ISSUE-288). Everything else is kept and counted. To keep one indefinitely, git worktree lock it rather than turning the sweep off. The sweep runs on [scheduler] worktree_reap_interval
worktree_retention_hours24.0Idle hours before a worktree is a reap candidate. This is what protects a task running right now, not just a stale checkout: the sweep knows nothing about the worker pool, so recent activity is the only evidence a checkout is in use. Clamped to a one-hour floor — a worktree seconds old is clean and has nothing that is not upstream, so anything shorter reaps a worktree a task is still setting up

How the wrapper behind gh_bin_path / glab_bin_path actually works — where it takes its policy and trust anchors from, and why it refuses rather than falling back to a public host — is written out under [devbox], since one file serves both the sandbox and the container.

[developer.container]​

The exec transport into the devbox. This block configures the transport; it no longer decides that there is one. Where project code builds and runs is derived from three settings, all of which have to be on: [developer] enabled, a non-empty [developer] repos_dir, and [devbox] enabled. With any of them off, npm, uv, cargo and the rest run on the host inside the task's sandbox, as they always did.

A deploy-time choice, not a runtime one: within a deployment there is exactly one place a build happens, so nothing on the host ever consumes an environment the container built and no parity rule has to hold.

SettingDefaultDescription
exec_socket_dir"/run/istota-exec"The parent. The socket is {exec_socket_dir}/{user_id}/exec.sock, and only the per-user subdirectory is ever mounted into a container
connect_timeout_seconds5.0The client's connect budget, and the only timeout on the connect path
idle_timeout_seconds3600Server-side backstop reap for a connection with no traffic either way. Deliberately longer than most task timeouts, so in practice it only fires on an orphan whose task is already gone. Do not lower it to something that would kill a long link step
shim_commandsfifteen, belowThe commands fronted by a shim

The default list is npm npx pnpm yarn node uv uvx pip pip3 cargo rustc rustup go bundle gem. The list is a routing declaration — "if you type this, it belongs in the container" — and not a promise that the container has the tool: cargo, rustc and rustup are routed but deliberately not in the devbox image, so they are installed on demand and a devbox reset takes them again. A shimmed command the container does not have refuses with a line saying so, and exits 120 having run nothing. Two absences are deliberate and one of them is not negotiable. python3 is refused whatever you write here, because the sandbox launches its own network bridge with it — a shim would route that into the container and break egress for every developer-enabled task. So are the shells, env, git, gh, glab and istota-skill, each for the same class of reason. make is merely omitted: shimming a driver command inverts routing for everything beneath it, so a Makefile calling git, gh or python3 would get the container's copies. Add it if you know your Makefiles; the cost of leaving it out is a recipe that calls ./node_modules/.bin/<tool> by path.

Routing builds into the container needs the three settings above, a container for the user, and the devbox image built with the daemon's own uid, which on the stack is 10001 by default. A mismatched uid is the one failure with no error message anywhere that names it: the container cannot write into a worktree the daemon made, and once that is worked around the daemon cannot unlink a tree the container made, so every worktree that ever ran a build becomes permanently unreapable.

backend is retired. It used to sit in this block with the values none and devbox, and it could disagree with [devbox] enabled. Both pairings were bad: a devbox that was on alongside backend = "none" gave the model a devbox skill whose every verb but reset refused, and the reverse asked the developer skill to reach a container nobody had built. A file still carrying the key gets a WARNING at config load and a WARN from istota doctor --only developer.container. The value is ignored, not honoured. If you set it to "none" to keep builds on the host, turn [devbox] enabled off instead.

istota doctor --only developer.container answers the five questions that each fail silently — does the rendered config derive what the running daemon is running (re-derived from the three inputs, since there is no key left to read), does the transport answer, do the two sides agree on uid and repos root, is the derived package cache visible inside the container, and is the command reaper running. That last one needs no configuration: the cache is {repos_dir}/{user_id}/.package-caches, inside the subtree the container already mounts, so cache and venv share one mount and uv hardlinks instead of copying. Leave [security] sandbox_cache_dir blank here — it is the fallback for a deployment without the developer skill.

[developer] repos_dir is a per-user root whether or not the devbox is on. The daemon derives {repos_dir}/{user_id} and hands that to the sandbox bind, DEVELOPER_REPOS_DIR and the credential scrub. That is what stops one user's coding task reaching another's checkouts, and it has nothing to do with containers — so an upgraded host has to move its existing clones down a level before the developer skill can see them again. repos_relocate does the move, and with more than one configured admin it refuses, because the old layout recorded no owner and a wrong guess hands one admin's clones to another.

[developer.review]​

The code_review skill's model, caps and budget. There is no separate feature flag — the skill is already gated by developer.enabled and an admin check, so enabled = false here is the off switch.

One reviewer reads the diff and the code around it with Read, Grep and Glob, over a copy of the reviewed commit written out of git into {temp_dir}/.review/. On a sandboxed deployment that copy is the only thing it can read. Where the copy or the sandbox cannot be built, it reviews the diff alone, and the result says so in reviewer.tools.

SettingDefaultDescription
enabledtruefalse switches the CLI off; a workflow that asks for a review then reports it unavailable and lands anyway
model"smart:high"Role alias for the reviewer. A :effort modifier is honoured
file_budget8Files the reviewer may read beyond the changed ones. 0 or less reads as 8, with a warning
snapshot_max_bytes104857600 (100 MiB)Total size of the reviewed commit's copy. Changed files are written first; over the cap the rest is listed as skipped. 0 or less keeps the default
snapshot_max_file_bytes2097152 (2 MiB)Per file in that copy; a larger file is skipped. 0 or less keeps the default
max_diff_chars200000Cap on the diff in the prompt. The full patch is in the copy either way
timeout_seconds480The reviewer's budget, including a reformat of an unusable answer. Clamped to fit under the skill proxy's ceiling for code_review
max_calls_per_task8Review runs per task

bughunt_model from an older config is read as model when model is unset. conformance_model, both_agents_threshold_lines, boundary_patterns, max_context_chars, max_file_chars, max_callers_per_symbol and max_need_files are retired: they are dropped at load with one INFO line and do nothing.

max_calls_per_task counts runs that reached the model. One run charges 1, which covers the review and, if its answer could not be parsed, one text-only reformat call. Guard refusals and breaker skips are free. At the cap the review degrades to skipped rather than erroring — a blocking cap would stop a task that had already finished its work from landing it. 0 or less permits no reviews at all rather than reading as "unlimited"; use enabled = false to switch the feature off.

ntfy push notifications​

ntfy is a per-user connected service — there is no [ntfy] config block. Each user supplies their own server URL, topic, and (optional) auth via the encrypted secrets table (see credentials for the full per-user credential inventory):

istota secret ensure --user alice --service ntfy --key topic --value alice-alerts
istota secret ensure --user alice --service ntfy --key server_url --value https://ntfy.example.com
istota secret ensure --user alice --service ntfy --key token --value tk_…

Or via the web UI at /istota/settings/connections (ntfy push). Priority is hardcoded to 3 (the ntfy default).

What it IS: a one-way push channel (bot → device) used by heartbeat alerts and scheduled-job output (output_target = "ntfy"). What it ISN'T: two-way (no replies), a Talk replacement, operator-shared infrastructure, or required.

Money​

Money is a module (on by default; opt out per user via disabled_modules = ["money"]). Per-user money settings live in the per-user money DB, not in config.toml; the one instance-level knob is:

SettingDefaultPurpose
autoclass_lookuptrueLet the portfolio module look up ticker metadata from a third-party quote API when classifying a newly imported symbol. The request carries the symbol, which is private financial data, and runs in the unsandboxed web or daemon process, outside the CONNECT allowlist. Off falls back to offline description heuristics, which need no network
The bot auto-discovers *.beancount files at the top level of {user_workspace}/ledgers/ — no per-resource path is required. Monarch credentials are a cookie pair in the encrypted secrets table — provision both keys (session_id and csrftoken) via the CLI or the web settings UI:
istota secret ensure --user alice --service monarch --key session_id --value …
istota secret ensure --user alice --service monarch --key csrftoken --value …

[google_workspace]​

SettingDefaultDescription
enabledfalseEnable Google Workspace skill
client_id""Google OAuth client ID
client_secret""Google OAuth client secret (or ISTOTA_GOOGLE_WORKSPACE_CLIENT_SECRET env var)
scopesDrive, Gmail, Calendar, Sheets, DocsOAuth scopes to request

See Google Workspace for setup instructions.

[site]​

hostname is load-bearing beyond OAuth2 and the origin check: minting a location ingest token refuses with a 409 while it is unset, because the webhook URL it assembles would be a relative path and the phone's QR decoder accepts only https://. An install with no hostname, such as istota serve on a Mac, therefore cannot add a device, by QR code or from the iOS app's one-tap button.

The deployment's public DNS name.

SettingDefaultDescription
hostname""Public DNS name; used by the web app for OAuth2 redirect derivation, origin/CSRF checks, and webhook URLs. The origin check compares scheme, name and port, so a public install browsers reach on a port other than 443 names it here (istota.example.com:8443). On the stack istota setup --hostname writes it, and in direct and proxied ingress its name must equal DOMAIN in the VM's host.env, which holds the name without the port, or the daemon refuses to start; change both with istota-stack setup --force. The local VM writes localhost:<port>

The agent-writable static web root (enabled / base_path) was removed. A publicly-served directory the agent could write to with an ordinary cp was an outbound egress channel the confirmation model treated as a benign local write, so anything the agent could read could be published to a public URL without a gate. Serve static assets outside istota, from a directory the agent cannot reach. A stale enabled / base_path key logs a warning at config load and is ignored.

[web]​

SettingDefaultDescription
enabledfalseEnable web interface
auth["nextcloud"]Login methods: any of "nextcloud" (OAuth2 against Nextcloud) and "email" (an email identity with a password or an emailed sign-in code), "local_code" (the Mac app's one-use login codes from istota web login-code; it needs [site] hostname to be localhost:<port>, the address the app opens; the web app then answers at localhost and 127.0.0.1 on that port only, and the stack refuses it under any ingress but local or unset), or ["none"] alone. A bare string is still accepted, and unknown names are dropped with a warning. "none" disables auth entirely; it is exclusive and only the loopback istota serve launcher accepts it (the stack and direct uvicorn refuse it). It answers only at localhost, 127.0.0.1 and [::1] on the port serve bound, accepts a POST only from that origin or the Vite dev server on port 5173, and refuses requests a page on another site or port makes in the background. Email identities are managed with istota auth. To move from Nextcloud to email login, set ["nextcloud", "email"], attach identities with istota auth add, then select ["email"] once every user has one. Passwords are optional: emailed sign-in codes work without them when SMTP is configured. Never put a public proxy in front of the no-auth local launcher. On the stack istota setup writes "nextcloud" when it is given a Nextcloud OAuth client id (--oauth-client-id) and "email" unless --no-email-login, so the written value is never empty. Env override: ISTOTA_WEB_AUTH, comma-separated. See email login
auth_enrol_ttl_hours168Lifetime of an enrolment link
auth_reset_ttl_hours1Lifetime of a password-reset link
auth_step_up_ttl_minutes10Lifetime of a sensitive-action confirmation (an emailed code; the account password for admin actions, and for every action where mail is not set up)
auth_sign_in_code_ttl_minutes10Lifetime of an emailed sign-in code. The code works only in the browser that asked for it
auth_min_password_length12Minimum password length. Never below 8; a value above 128 is refused
auth_throttle_window_seconds900Window for the two password-attempt budgets below
auth_throttle_max_email10Password attempts per address per window
auth_throttle_max_ip30Password attempts per client address per window. Inactive while trusted_proxy_hops is 0, since no client address is read
auth_mail_link_max_email3Self-service mails per address per hour, reset links and sign-in codes together
auth_step_up_mail_max20Confirmation codes a signed-in user may be mailed per hour, apart from auth_mail_link_max_email. Past it the confirmation dialog says when to try again. At least 1
trusted_proxy_hops0How many trusted proxies sit in front of the backend; selects the client address from X-Forwarded-For for the IP budget. Set it only when the backend cannot be reached around those proxies
token_storage"ephemeral"Where per-user Nextcloud tokens live. "ephemeral" keeps them in the session only; "encrypted" retains them in web_user_tokens and requires ISTOTA_WEB_TOKEN_KEY (at least 32 characters, delivered to the web process only, never the scheduler). Retaining them enables posting web messages to Talk as the user and web-to-Talk read-state sync; a Nextcloud OAuth token grants full account access, so this is a deliberate opt-in. Any other value warns and falls back to ephemeral. istota setup writes "encrypted" on the stack, because its entrypoint mints /data/.web_token_key itself. Env override: ISTOTA_WEB_TOKEN_STORAGE
port8766Web app port
oauth2_provider""Public Nextcloud URL (browser-facing), no trailing slash
oauth2_client_id""NC OAuth 2.0 client ID
oauth2_client_secret""NC OAuth 2.0 client secret (or ISTOTA_WEB_OAUTH2_CLIENT_SECRET env)
oauth2_token_endpoint""Optional server-to-server token URL override
oauth2_userinfo_endpoint""Optional server-to-server userinfo URL override
oauth2_redirect_uri""Explicit redirect URI override; otherwise derived from request
max_avatar_kb4096Byte cap on a profile-picture upload, in KB. Enforced on the declared Content-Length before the body is read and again on the running total. 0 switches uploads off — both the user's own PUT /settings/avatar and the admin PUT /admin/avatar answer 503, and a stored picture is still served. istota bot-icon set keeps working and falls back to this field's own default: the cap is about an unauthenticated network body, and the CLI reads a local file as the operator. Separate from nginx's client_max_body_size, which bounds what reaches the process at all and is sized for chat attachments
avatar_import_from_nextcloudtrueWhether the scheduler imports users' Nextcloud profile pictures. Only a custom avatar is imported — Nextcloud generates a coloured letter for a user who has set none, and importing that would swap the app's own initial chip for Nextcloud's version of the same idea, indistinguishable afterwards. Inert on a local storage backend. Cadence: [scheduler] avatar_import_interval
session_secret_key""Session signing key (or ISTOTA_WEB_SESSION_SECRET_KEY env)

[web.chat]​

Knobs for the in-app web chat surface (the "Chat" tab). The surface is always enabled when the web UI is on; these tune limits and streaming cadence. The room_stream_* settings tune the live room-event stream (GET /chat/stream): one user-scoped SSE connection per open tab carries every room the user belongs to, so a Talk turn, a routed alert or a message in a background room reaches the browser in about a second whatever surface produced it.

SettingDefaultDescription
max_prompt_chars32000Max characters accepted per chat message
max_attachment_mb25Max attachment size, in MB. Application default, and the binding limit on the stack, whose nginx allows 512M (see below)
attachment_extensionspdf png jpg jpeg heic webp gif txt md csv wav mp3 m4a ogg webm weba docx xlsxAllowed attachment file extensions — images (including heic, what an iPhone photo is), documents, text, and the audio formats a voice message arrives in. A list naming webm also admits weba, the name a Chrome or Firefox voice recording is stored under
rate_limit_messages30Messages allowed per user per window
rate_limit_window_seconds300Rate-limit window (5 minutes)
sse_poll_interval_ms200Server-side task_events poll cadence for the SSE stream
client_poll_interval_ms1500Client fallback poll cadence when SSE is unavailable
talk_read_sync_interval60Talk→web read-state pull cadence, seconds (0 disables)
room_stream_poll_interval_ms1000Server-side messages tail cadence for the live room stream
room_stream_keepalive_seconds20SSE comment-frame cadence, so a proxy can't drop an idle stream
room_stream_max_batch500Rows before a gap frame tells the client to reload instead of replay
room_stream_max_bytes2000000Serialized-byte budget for the same guard
room_stream_room_check_seconds10Per-connection room-metadata diff cadence (0 disables)

[web.map]​

Where the background tiles under the location maps come from (ISSUE-334). The two CARTO URLs used to be literals inside a Svelte component; CARTO began requiring an API key and watermarking unauthenticated requests with "API KEY REQUIRED", so every map surface rendered defaced tiles and no deployment could change that without a code edit.

SettingDefaultDescription
provider"openfreemap"openfreemap, carto, osm, or custom. An unrecognised name warns and falls back to openfreemap
api_key""CARTO only. Free from https://carto.com/basemaps/apikey/
dark_style""custom only: a MapLibre style URL
light_style""custom only
attribution""custom only

openfreemap needs no key and is the default for that reason. It is free OSM vector tiles with dark and light themes, and still a third-party request, so it does not make map viewing private. carto needs a free API key, and CARTO is retiring its raster service, so it buys time rather than fixing anything. osm is a keyless raster last resort: light tiles only, so the dark theme looks wrong, and the OSMF tile usage policy discourages application use. custom takes your own MapLibre style URLs, such as a self-hosted tile server; one URL covers both themes. Resolution never returns an unusable spec: an unknown provider, a custom with no URL or a non-http(s) one, and a keyed provider with no key all fall back to openfreemap. Returning the keyless CARTO templates with a "needs key" flag was the original bug wearing a label — nothing in a browser can act on a flag, so the user still got the watermark. The flag survives on the fallback as the reason, which is what lets istota doctor --only web.basemap say "carto, with no key" rather than the vaguer "did not resolve as written".

api_key is not a secret. MapLibre puts it in the tile URL, so it ships to every browser that loads a map and appears in every request they make; CARTO issues these free for exactly that. It is redacted in the admin config view because the name matches the redaction rule, which is harmless but is not a guarantee about the value.

A user can also store their own CARTO key on the Location settings page, where it is a module-owned service rather than one of the account-wide Connected services. A stored key selects CARTO for that user, overriding provider — otherwise pasting a key would do nothing visible, and the reason would live in a file the user cannot reach. GET /istota/api/map/basemap returns that key only already embedded in the tile URL, never as a field.

The web.basemap doctor check reads the same resolver as the endpoint, so it cannot pass while the map is blank. It opens no socket, deliberately: CARTO returns 200 with a byte-identical body and ETag for a keyless request and a bogus-key one, so a probe would report a working basemap for a defaced one — and tiles are fetched by the browser over a different route, so a proxied deployment would fail a probe for a basemap every browser renders.

[web.workspace]​

SettingDefaultDescription
max_upload_mb100Largest file one upload in Files may carry. nginx's body limit bounds what reaches the process at all

[location]​

SettingDefaultDescription
enabledfalseEnable GPS webhook receiver
webhooks_port8765Unused: nothing reads it. The web app serves the webhook routes. Kept so an older config that sets it still loads
accuracy_threshold_m100.0Discard pings less accurate than this, in metres
visit_exit_minutes5.0Minutes away from a place before a visit is closed
reconcile_enabledtrueBatch-reconcile visits from pings, cleaning up state-machine drift
reconcile_lookback_hours6.0How far back a reconcile pass looks
reconcile_buffer_minutes10.0Buffer around the lookback window
reconcile_grace_minutes10.0Time away before an unassigned ping closes a visit. A gap between two pings at the same place no longer splits it (ISSUE-329): a tracker that goes quiet supplies no evidence that you left, and only an observed ping somewhere else does
reconcile_min_pings3Minimum pings for a reconstructed visit to count
reconcile_min_dwell_sec60Minimum dwell for a reconstructed visit to count

[caldav]​

Explicit CalDAV override. When any field is set it wins over the value derived from [nextcloud], which is how an install without Nextcloud points calendar at an external CalDAV server (Radicale, Fastmail, Google) with no Nextcloud in the picture. All-blank — the default — falls back to the Nextcloud derivation, so server deployments are unaffected.

SettingDefaultDescription
url""CalDAV base URL
username""CalDAV username
password""CalDAV password

Set all three fields or none. Each falls back to [nextcloud] on its own rather than as a group, so a half-set block mixes the two: a URL with no password names a foreign host and hands it the Nextcloud app password, and a password with no URL authenticates to Nextcloud's own DAV endpoint with the wrong secret. istota setup refuses the first pairing outright. Where there is no Nextcloud, istota setup offers this block, writing the URL and username into the config and the password to the stack's secrets/istota_caldav_password, which reaches the daemon as ISTOTA_CALDAV_PASSWORD.

A user's calendars are the ones whose DAV:owner names that user's principal. On Nextcloud that is principals/users/<user id>; on any other server the owner must sit beside the connecting account's own principal, with the Istota user id as its last segment, so on a plain Radicale a calendar owned by /alice/ belongs to the user alice. A server whose principals do not carry the Istota user id that way shows no calendars.

[sharing]​

Calendars and folders shared with Istota over open protocols. See sharing. A feed or sharing server on a private address or plain http needs a sharing grant in [private_hosts].

SettingDefaultDescription
ics_poll_interval900Seconds between polls of one ICS feed. Values under 300 are raised to 300
ics_max_bytes2097152Largest feed body read (2 MiB)
ics_max_feeds_per_user10ICS feeds one user may subscribe Istota to
events_per_task10Writes to Istota's own calendar one task attempt may make. 0 turns those writes off

[sharing.ocm]​

SettingDefaultDescription
enabledfalseReceive Open Cloud Mesh folder shares on [site] hostname, sent to <user_id>@<hostname>
max_pending_per_user20Offers waiting for an answer, per user
pending_days14An offer left unanswered this many days after its last send is declined
max_discovery_fetches_per_minute30Discovery requests to sending servers, across all senders

[push]​

Native iOS push through APNs. Install the push extra and put the APNs signing key on the server, readable only by the service user. istota doctor --only push.credentials checks the key's metadata; istota push test --user U sends one. istota doctor --only push.signing_key checks the private push key: mode 0600, owned by the service user, parses, and matches its .pub file. Under delivery = "relay" no APNs key is needed here, and istota doctor --only push.relay checks the relay URL and asks the relay's /healthz.

SettingDefaultDescription
enabledfalseMaster switch
apns_key_path""Path to the .p8 signing key. ISTOTA_APNS_KEY_PATH overrides it
apns_key_id / apns_team_id""The key's ID and your Apple team ID
apns_topic"com.cynium.istota"The app's bundle ID
dispatch_interval_seconds5Seconds between push sweeps. 0 turns the sweep off
chat_delay_seconds15How old an unread chat message must be before it is pushed, so a message read in the web UI first is never pushed
max_age_seconds300Chat messages older than this when a sweep reaches them are skipped rather than pushed
alert_batch_limit200Pending notifications read per sweep
content"legacy"legacy sends plaintext previews, which Apple can read. private encrypts previews for devices that enrolled a device key and sends every other device a fixed alert with no preview; see private push v1. Any other value stops the load
signing_key_path""The Ed25519 signing key for private push, with its public half at <path>.pub. Required when content = "private". Create it with istota push keygen, or on the stack istota-stack push-key create; istota push import-key (istota-stack push-key import) writes a saved key from stdin instead. --force replaces it, and every enrolled device then has to enroll again. ISTOTA_PUSH_SIGNING_KEY_PATH overrides it
delivery"direct"direct sends to APNs with the key above. relay sends each device's pushes through the push relay with that device's send capability, and reads no APNs settings. relay requires content = "private" and signing_key_path, since the relay forwards only encrypted envelopes. Any other value stops the load
relay_url""The relay's base URL, for example https://relay.example.com/istota. It may carry a path, and endpoints are appended to it. Required under relay: https://, no userinfo, query or fragment, at most 256 characters, and no .., //, %2f or %2e in the path. The load lowercases the scheme and host and drops port 443 and a trailing slash; that form is the one discovery reports and the app compares. ISTOTA_PUSH_RELAY_URL overrides it
relay_timeout_seconds15How long one request to the relay may take. At least 1
push_credentials_dir""Where each relay device's send capability is written at registration, as <device id>.cap (mode 0600, directory 0700); the database holds only the file name. A route waiting to be revoked keeps its capability here until the relay accepts the revocation, as the removed device's file or, for a route replaced by a new enrollment, revoke-<route id>.cap. Empty means push/relay beside the framework database (/data/db/push/relay on the stack), not the config directory, which the stack mounts read-only. The web process writes it, so it must be writable there and outside the workspace. istota doctor --only push.relay checks its modes

[assignments]​

Goals an admin gives the bot to work on across days. See assignments.

SettingDefaultDescription
max_workers2Assignment wakes running at once, across the instance
user_max_workers1Assignment wakes one user may run at once
max_active_per_user3Assignments past draft and not yet closed, per user
max_cost_usd_per_assignment50.0Ceiling on any charter's cost budget
max_wakes_per_assignment500Ceiling on any charter's wake budget
min_wake_interval_minutes15Shortest time between two wakes of one assignment
stall_wakes3Wakes in a row with no progress before the assignment is paused
failure_wakes3Failed wakes in a row before the assignment is paused
budget_low_fraction0.75Share of the budget spent that raises a budget notice
scratchpad_prompt_chars24000Cap on the scratchpad in a wake's prompt
history_prompt_chars12000Cap on earlier wake summaries in a wake's prompt

[private_hosts]​

Which hosts each part of Istota may reach on a private, loopback or reserved address. Every other address must be public. The table is keyed by host, and each value names the consumers the grant is for:

[private_hosts]
"wiki.example.internal" = ["browser"]
"rss.example.internal" = ["browser", "feeds"]
"10.0.0.5" = ["servarr"]

heartbeat differs: its grant is needed for a public host too. A grant reaches only the consumers it names. The same host means something different to each one, because the person who chooses the address differs and so does what gets sent:

ConsumerWho chooses the addressWhat a grant lets happen
browserThe model and any page it loadsChrome reaches the host through the egress proxy, and on a VM the firewall opens the addresses it resolves to, refreshed every five minutes. Loopback stays refused whatever is listed, since the browser's API and debugging ports are there, and so does the VM's own address. A change restarts the stack
wordpressThe user who connects a siteThe wordpress skill calls the host with that site's credentials. HTTPS is still required
mail_accountsThe user who types a server nameThe daemon sends that user's mail password to the host. Certificates are still verified
sharingA user adding a calendar feed, or the sharing server a share namesThe daemon fetches the host, and plain HTTP is allowed to it. A redirect may reach a private address only on the same listed host
servarrThe operator, in [servarr.apps.*]The servarr skill sends the app's API key, and plain HTTP is allowed to it
feedsA user, or a task through feeds addThe poller fetches the host on a timer. Plain HTTP is allowed to any feed, listed or not, and each redirect is checked again
heartbeatThe author of HEARTBEAT.md, which a task can writeA url-health check fetches the host and reads its status, from the daemon's network. Without a grant nothing is fetched, even a public host, and every redirect needs a grant too
egressA job's owner, on the job's pageThe owner may grant that job <host>:<port> at any port, and a limited job may then reach it from its shell, on a private address too. Nothing opens until a job is granted it, and only for that job

So there is no shared list. An arr app on 10.0.0.5 granted for servarr does not become a target for a user's RSS feed, a user's mail account or a page Chrome loads.

The rules for writing the table:

  • A key is an exact host name or IP address, compared ignoring case and a trailing dot. A scheme, port, path or wildcard matches nothing, and the loader warns about it.
  • Quote a host name with a dot in it. TOML reads wiki.internal = ["browser"] as a nested table; it is discarded and grants nothing.
  • To add a consumer to a host already in the table, add it to that host's list. A second line for the same host is a TOML error, which istota apply and Admin > Configuration refuse.
  • A host with [] grants nothing. A consumer not in the table above is discarded while the others on that line still apply, and istota apply and Admin > Configuration refuse the change.

Admin > Configuration shows the table as private_hosts under General, written as TOML. The field's text must include the [private_hosts] line, so a first grant in an empty field needs that line above it. Any edit to it needs the typed confirmation.

This table does not touch [security.network] extra_hosts or the hosts of the forge and Nextcloud URLs. Those are the sandbox's own allowlist, a different permission, and they open a host to every task where an egress grant opens it to one job.

Moving from the old keys​

private_hosts under [browser], [wordpress], [mail_accounts], [sharing], [servarr] and [feeds] still works, and a later release removes it. Each host in an old key is added to the table for that consumer, on top of whatever the table already says, and each non-empty old key logs a warning saying what to write. Nothing rewrites config.toml for you.

To move by hand or in a plan, write the table and delete the old keys. Saving any edit to the table in Admin > Configuration moves every old key into it in the same change, with no grant lost. That can leave an empty section header such as [feeds] in the file, which loads the same as no header. The raw editor moves nothing, and neither it nor any other edit may add to an old key. A history entry holding an old key cannot be restored until you move that key into the table.

Move the keys after you have settled on a release that has this table. A release without it treats [private_hosts] as one unknown key and refuses every private host. A move made in Admin > Configuration leaves a config.toml.bak.<timestamp> with the old keys; after a hand edit or a plan you restore them yourself.

[browser]​

SettingDefaultDescription
enabledfalseEnable the headless browser container
api_url"http://localhost:9223"Browser container's Flask API
vnc_url""External noVNC console URL, for operators. The browser service builds each live instance's viewer link from it and passes it to tasks as BROWSER_VNC_URL. The admin Browsers page no longer uses it: its console opens in the page. Do not hand it to users: the console exposes live user IDs to anyone who can reach it (see browser profiles)

An internal site Chrome should reach is a browser grant in [private_hosts].

[wordpress]​

Operator settings for the wordpress skill. Sites and their credentials are per-user vault entries, not config.

SettingDefaultDescription
max_upload_mb25Largest file one media upload may send

A site on a private, loopback or reserved address, such as a local development site or an internal backend, is a wordpress grant in [private_hosts].

[servarr]​

Operator settings for the servarr skill: one install-wide connection per arr app. The skill is offered only when at least one of sonarr, radarr, lidarr or prowlarr has a table under apps. Problems in this section are warnings; none stops the daemon.

SettingDefaultDescription
requesters[]User ids, besides admins, who get the requester tier: search, request with the defaults below, see the queue and their requests. Matched ignoring case. Empty leaves the skill to admins
lookup_timeout_seconds30Timeout for the */lookup calls, which reach TMDB, TVDB or MusicBrainz through the app
release_search_timeout_seconds120Timeout for an interactive release search (why --releases) and an indexer test (indexers --test). Warned about when it leaves less than 60 seconds under the skill's own proxy timeout

[servarr.apps.<app>]​

One table per app, named sonarr, radarr, lidarr or prowlarr. An app with no table is not configured. bazarr is reserved and ignored; any other name is warned about and ignored. A table with no url is discarded; one with no key is warned about and left out until the key arrives.

SettingDefaultDescription
urlThe app's base URL, including any URL base, e.g. http://192.168.1.10:7878. Never shown with userinfo
api_keyThe app's API key (Settings > General > Security). Set it as the stack secret file istota_servarr_<app>_api_key (the variable ISTOTA_SERVARR_<APP>_API_KEY), which wins over a value written here; an inline value still loads. Redacted everywhere

Do not add the arr ports to [security.network] extra_hosts. The skill's CLI reaches the apps host-side; without an entry the sandbox has no route to them.

[servarr.defaults.<app>]​

What an add uses when no flag names a value, which is always the case for a requester. A configured name the app does not have is reported as stale_default rather than replaced.

SettingAppsDescription
quality_profilesonarr, radarr, lidarrQuality profile name
root_foldersonarr, radarr, lidarrRoot folder path on the app's machine
metadata_profilelidarrMetadata profile name
minimum_availabilityradarrtba, announced, inCinemas or released; default released. No command-line flag sets it
monitorsonarr, lidarrSonarr: the episodes a new show monitors (all, future, missing, existing, firstSeason, lastSeason, pilot, none). Lidarr: the albums a whole-artist add monitors (all, future, missing, existing, latest, first, none). Default all

With no default and no flag, an app with exactly one profile or root folder uses it; otherwise the add answers choice_required. A field that does not apply to its app is warned about and ignored.

[devbox]​

A persistent per-user Linux container. It is where the agent installs packages and compiles things. With [developer] enabled and a repos_dir set, enabled below is also what routes project builds into it over the exec transport rather than onto the host.

SettingDefaultDescription
enabledfalseEnable the devbox skill. With [developer] enabled and repos_dir set, this is also the switch that sends project builds into the container
container_prefix"devbox-"Container name is {prefix}{user_id}
max_output_bytes102400Cap per output stream in the skill's JSON envelope
users[]The users who get a devbox in the stack. istota devbox compose-file renders one service each, and the daemon runs one credential-proxy listener each
forge_users[]The users whose devbox may fetch the [developer] gitlab_token and github_token over the credential socket. Any code in that devbox can read and export them, so give these users a narrowly scoped token. A task's own git, gh and glab run in the sandbox and do not need this; a build that clones a private dependency does
mem_limit"4g"Memory limit per devbox container
cpus2.0CPU limit per devbox container
pids_limit512Process limit per devbox container
log_max_size / log_max_file"10m" / 3The container's json-file log rotation
network_subnet"172.30.0.0/24"The devbox network's fixed subnet. The VM's egress unit drops metadata, link-local, RFC 1918 and CGNAT destinations from this range, so the two must agree

No Docker socket is bound into a task's sandbox, and no docker binary either. The skill CLI reaches the container over the exec transport — a Unix socket into a server running inside it — for every verb. reset is a restart request on that transport: the server empties /home/dev (only if it is a mount point), answers, and exits, and the container's restart policy brings it back. docker_cli is retired with the last Docker call; a value left for it is warned about and ignored. The per-user Docker-API allowlist proxy that used to stand at /var/run/docker.sock in every sandbox is deleted along with its docker_socket, exec_timeout_seconds and api_proxy_* settings; a value left for any of those in a TOML file is read by nothing.

The raw-socket diagnostics — traceroute, mtr, tcpdump — no longer work inside the container. They need CAP_NET_RAW, which the deployment dropped: a build needs none of them, and a container holding that capability can pick its own source address and walk past address-scoped firewall rules. Tools that work over ordinary sockets are unaffected, and ping is probably one of them: it tries an unprivileged ICMP datagram socket first, which Docker's default sysctls permit.

The devbox runs the same real gh and glab behind the same wrapper the sandbox uses. docker/devbox/lib/istota_forge_cli.py is a byte-identical copy of src/istota/sandbox/forge_cli.py, kept in sync by scripts/sync-devbox-lib.sh. The wrapper locates its policy beside whichever copy of itself is executing, and takes real_bin, the forge URL and the config dirs from that file rather than from os.environ — it runs as a child of the model's own shell, so the environment is not a trust anchor. With no URL resolvable it refuses rather than falling back to a public host. The token comes from the devbox credential proxy, which returns it only for a user in forge_users. The wrapper puts the raw value in the CLI's environment.

[playbooks]​

Procedural memory — see memory.

SettingDefaultDescription
enabledfalseMaster switch
recall_limit3Top-K playbooks injected per task
min_tool_calls4Tool calls a task needs to qualify for distillation
retention_days90Age-prune by last use; 0 = keep forever
max_chars00 = share the global max_memory_chars budget

[experimental]​

SettingDefaultDescription
features[]Operator-enabled feature flags. istota experimental list shows what this build can gate; an unknown name logs a warning at startup. Not exposed in the web UI and not per-user. See experimental features

[health]​

SettingDefaultDescription
max_document_bytes26214400 (25 MiB)Cap on a single stored document (scan, discharge summary, vaccination card). 0 = unlimited

[feeds]​

No settings of its own. A feed on a private, loopback or reserved address is a feeds grant in [private_hosts]. See feeds.

[users.<id>]​

Most per-user settings are documented in per-user configuration, because the DB row wins over the TOML block for nearly all of them and the CLI is the provisioning path. The one below is the exception: it exists only here.

SettingDefaultDescription
vault_path""Retired legacy file path, read only by the one-time credential migration. New credentials use Settings import.

Legacy file locations remain TOML-only until retirement completes. Import takes an uploaded file and never stores a host path or passphrase.