Configuration overview¶

Config file locations¶

ISTOTA_CONFIG_PATH wins over the search order below — it is how a subprocess resolves the same config the daemon loaded rather than searching afresh. It does not beat an explicit -c PATH, and a path that does not exist is ignored rather than fatal, falling through to the search. Config is otherwise loaded from the first file found in this order:

config/config.toml (relative to working directory)
~/src/config/config.toml
~/.config/istota/config.toml
/etc/istota/config.toml

Override with -c PATH on the CLI.

Structure¶

The config file is TOML with nested sections:

bot_name = "Istota"
db_path = "data/istota.db"

[nextcloud]
url = "https://nextcloud.example.com"
username = "istota"
app_password = "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"

[talk]
enabled = true

[email]
enabled = false

[conversation]
# ...

[scheduler]
# ...

[security]
# ...

[sleep_cycle]
# ...

[memory_search]
# ...

[users.alice]
display_name = "Alice"
timezone = "America/New_York"

See the full reference for all available settings.

Per-user config¶

Per-user data lives in DB tables (user_profiles, user_resources, briefing_configs, secrets) populated by the matching istota … ensure CLI commands or the web UI. The [users.NAME] block in the main config is also accepted (the docker entrypoint relies on it); DB rows win at config-load time. The retired config/users/{user_id}.toml mechanism is gone. See per-user configuration.

Credentials¶

Istota has two credential tiers: global (bot identity, in TOML/env vars) and per-user (user accounts, in the encrypted secrets table). Instance-wide secrets can be provided as env var overrides (e.g., from systemd EnvironmentFile=) instead of storing them in TOML. Per-user credentials are provisioned via the web UI at /istota/settings or istota secret ensure.

See credentials for the full inventory, runtime flow, and the decision heuristic for new integrations.

Admin users¶

Admin user IDs are listed in /etc/istota/admins (plain text, one per line, # comments allowed). Empty file or missing file = all users are admin (backward compatibility).

Override path via ISTOTA_ADMINS_FILE env var.

CalDAV¶

By default CalDAV settings are derived from Nextcloud credentials: {url}/remote.php/dav with the same username and app password. Nothing to configure in the common case.

An explicit [caldav] section overrides that derivation, which is what a standalone install without Nextcloud uses to reach an external CalDAV server:

[caldav]
url = "https://caldav.example.com/dav"
username = "alice"
password = ""    # or via the encrypted secrets store

Derived properties¶

Property	Derived from
`bot_dir_name`	`bot_name` sanitized for filesystem (ASCII lowercase, spaces to underscores)
`caldav_url`	`[caldav] url` if set, else `nextcloud.url + /remote.php/dav`
`caldav_username`	`[caldav] username` if set, else `nextcloud.username`
`caldav_password`	`[caldav] password` if set, else `nextcloud.app_password`
`use_mount`	`True` if `nextcloud_mount_path` is set