Changing configuration from the web
An admin can change the instance configuration at Admin → Configuration (/istota/admin/config): the keys in config.toml, the deployment credentials in secrets/, and the admin allowlist in config/admins. This page is for the operator: what the editor can change, what stays a host action, and how a change reaches the running stack.
How a change is applied
The web container cannot write config/ (it is bound read-only into every service) and cannot restart the stack. A change is therefore a request that the host applies:
- The admin edits fields (or the whole file as text, below), reviews the change and submits it. The page shows a redacted diff, any problems the configuration check reports, and which credentials change (by name, never by value).
- The web stores the request in the
config_change_requeststable and writes its id torequests/config-applyin the stack directory. Credential values are sealed with the master key until the host takes the request. - A systemd path unit on the host runs
istota-stack config-apply. Under the stack lock it takes the request, checks everything with a dry run before writing anything, writes credentials and admins throughput-filesand the config throughistota apply(keeping the newest tenconfig.toml.bak.<timestamp>copies), records the outcome and restarts the stack. A timer runs the same unit every five minutes as a backstop. It starts no container while the trigger file is unchanged since a run that found nothing pending, and asks the database again once that run is an hour old, so a request whose trigger the web failed to write is taken within the hour. - The page follows the request through the restart and reloads once the web process is back.
Every applied change restarts the stack. The review dialog shows how many tasks are running, so the admin can wait for them.
The applier is part of the stack's VM, a server or the local VM on a Mac, set up by host/provision.sh. Anywhere else (istota serve on macOS) the page is read-only and says so. On a VM provisioned before the applier was added, the page is read-only until istota-stack update re-runs provisioning and the stack restarts.
What it guards
- Every submit needs a confirmation: a code sent to the admin's sign-in email address, or, on an install with no mail set up, the admin's account password. An admin with no live email identity cannot submit or preview, and one with no password on an install without mail needs a password link (
istota auth reset <user> --print-link, which works only where[web] authincludesemail) or mail set up. - Settings that can lock admins out or change the security posture (
web.auth, the OAuth client,security.sandbox_enabled,security.skill_proxy_enabled,brain.kind,[private_hosts], any change to the admin list, and a few more) need a typed confirmation. [web] authmust keepemail, and the admin list must not be empty, must keep the acting admin, and may name only users with a live sign-in identity. Give a user an identity on the Users page first.- A value the loader would discard blocks the change, including one already in the file. The page shows it against its key so it can be fixed in the same change.
- If
config.tomlchanges on the host after the page loaded, the submit is refused, and so is a request the host takes after such a change, so a host edit toconfig.tomlis never reverted by an older web request. That check coversconfig.tomlonly: a credential or the admins file written on the host withput-filesbetween the submit and the take is overwritten for the names the request changes. - A request is refused when a plan has taken over what it changes (
config/managed.json) since it was made. - While
config.tomldoes not parse, nothing is changed from the page. Fix it on the host withistota-stack apply, or copy back aconfig.toml.bak.<timestamp>. - Only one request is open at a time. A request the host has not taken can be cancelled.
- Every other admin gets an
admin_config_changenotification when a change is applied or fails.
What stays a host action
These keys are shown read-only, each with the reason and where it is changed instead:
- The container layout
istota setupwrites (db_path,workspace_pathand the rest), and[users.*]as form fields. site.hostname,nextcloud.url,nextcloud.usernameand the Nextcloud app password, which the entrypoint preflight and the rclone mount depend on (istota-stack setup --force).devbox.network_subnet,web.enabledandweb.port.- Keys that select a compose profile:
browser.enabled,browser.api_url,talk.signaling.*,whatsapp.enabled,whatsapp.provider. - The web session signing key.
- Any key an environment variable sets, which wins over
config.toml.
host.env, .env, TLS certificates, the persona and the other prompt files are not edited here at all.
Managed resources
If the optional Ansible management role (or a plan with [meta] managed = true) owns a resource, the editor shows it read-only, because the next play would revert a web change. Ownership is per resource (config, credentials, admins) and is recorded in config/managed.json. To hand a resource to the web, remove it from the role's variables (istota_config, istota_secrets or istota_admins), or run istota-stack apply once with managed = false. A managed.json that cannot be read makes every resource read-only until istota-stack apply rewrites it.
Tables, the whole file, and ignored keys
A table such as [models.aliases] or [[briefings.shared_blocks]] is edited as TOML that defines that one key, starting from what the file holds. "Reset to default" removes the key; shared_blocks = [] is a different edit, and means no shared blocks rather than the shipped ones.
The whole of config.toml can also be edited as text. Every credential in it reads "<unchanged>", which keeps the stored value; typing over it sets a new one. The text replaces the whole file, so it cannot be combined with field edits in one change. [users.*] can be edited there, but it only seeds users on first start; per-user settings belong on the Users page.
Keys the loader does not recognise, retired keys, and a credential set in config.toml while its secrets file is also set (the file wins) are listed under "Warnings about config.toml" with a Remove action. A key inside an array of tables has no Remove action and is removed in the text editor.
History and restore
Applied, refused and cancelled requests are kept for 180 days with their redacted diff and the host's output. Restoring an earlier request previews its configuration as a new change, which the admin then submits. A restore brings back configuration only: credentials and the admin list stay as they are, and a credential cleared since that request stays cleared.
Backing up and restoring the configuration
Back up configuration, above the fields, downloads the saved config.toml, never unsaved edits on the page. It works on a read-only or managed install too.
- Without installation secrets (the default) it is
istota-config-<UTC time>.toml: the file as the raw editor shows it, every credential replaced by"<unchanged>", under a comment saying what is left out. It needs no confirmation. - With Include installation secrets it is
istota-config-<UTC time>.kdbx, a KeePass file holding the same redactedconfig.tomlas an attachment and one entry per installation credential: each deployment secret file, and each credential written inconfig.tomlitself. It needs a confirmation, as a configuration change does: your account password, or a code sent to your sign-in email address. Unlike a credential export, the password is enough even where the install can mail, so an install whose mail has stopped working can still make one. It counts against the credential export's daily limit and is announced to every admin. Istota generates the file's password and shows it once; you may also ask for a key file, which you need with the password to open the backup. Neither is kept on the server, so a lost password cannot be shown again.
The encrypted backup leaves out the master key, the web session and token keys, the browser API token, the Anthropic model-listing key (the web process cannot read it), users' own credentials and everything in the databases, the admin list, host.env and .env, TLS certificates, and the workspace. A credential set only by an environment variable from outside the stack is listed as left out, not exported. The completion screen and the file's manifest list what is missing. A configuration or credential set over 256 KiB is refused rather than cut down.
The .kdbx opens in KeePassXC without Istota (checked with keepassxc-cli 2.8): the group Istota installation backup has a Backup manifest entry, a Configuration entry whose attachment is config.toml, and the credentials under Deployment credentials and Inline credentials, each titled with its setting. Where [push] signing_key_path names a key file, the private push signing key is under Push signing key, as PEM text in the entry's password; its public half is not kept, since it is derived from the private key. A backup holding the key is format version 2, which a release from before it refuses as a newer format; restore it on the same release or a later one. The attached config.toml has "<unchanged>" in place of each credential written in it; Restore configuration fills those back in, and a config.toml copied out by hand needs each value from Inline credentials. keepassxc-cli prints a "Maximum depth of replacement" warning for the manifest, whose values hold braces; the values are intact. The file is not a user vault: Settings → Credentials refuses to import it.
Restore configuration takes either file back. It is offered when the page holds no unsaved edits and no request is open. For a .kdbx it asks for the password and the key file, then lists each credential in it as new, changed, unchanged or host only, without values. The configuration is restored and no credential is, unless you select them; only new and changed credentials can be selected, and a changed one replaces the value the install holds now. The restore is reviewed, confirmed and applied like any other change, and every check above still applies: a host-only credential such as the Nextcloud app password is shown but not applied, and a key a plan manages is refused. A credential inside a list, such as a resource's password, is kept by its place in the list, so restoring it without the configuration is offered only where the current list holds the same entry at that place. The push signing key is restored only where [push] signing_key_path, in the configuration the restore leaves, is push/signing.pem in the config directory; any other path is host only, written with istota-stack push-key import. The host applier writes it after the configuration, with istota push import-key, and refuses the request if the key on the host changed since the review. Replacing a different key is the changed row, and the review then says that phones enrolled under the replaced key must enroll again; phones enrolled under the restored key keep working. The file and its password stay in the browser and are sent again with the submit; nothing decrypted is kept on the server. The server opens a .kdbx in a separate short-lived process, with 30 seconds and 1 GiB of memory to do it, and one at a time across the installation: a second one while another is being opened is refused with "Another backup is being opened; try again shortly", and one that runs past the deadline with "Opening the backup took too long". Each admin gets ten restore previews and submits per ten minutes, wrong passwords included, since a preview says whether a credential in the file matches the current one.
A configuration restore replaces the whole document, so a key the backup lacks goes back to its default, and a credential written in config.toml that the backup does not hold is dropped and named in the review. A plain .toml holding a real credential value is refused: use the .kdbx or the raw editor. A credential file written on the host after the review is not noticed, as for every change from this page. A restore from a lost installation's backup is part of Recovering a lost installation, which also lists what to keep outside the install.
Comments in config.toml
Every write goes through the same TOML writer istota apply uses, so comments in a hand-written config.toml are not kept. The page warns when the file has comments. The previous text is in the newest config.toml.bak.<timestamp>.
A credential moved to its secret file is removed from every config.toml.bak.<timestamp> and from config.toml.pre-localize on the next write, and from the daily copies in Backups/config/<date>/ on the next database backup. Copying one of those back on the same stack still loads the credential, because the secret file wins over a value in config.toml. A restore onto a new VM never had the secret files, so you enter those credentials again there, as the restore already tells you. On a Nextcloud workspace, Nextcloud's own file versions and trash may keep an older copy of Backups/config/; delete those versions if that matters to you.
When something goes wrong
- A request still waiting after two minutes: check
systemctl status istota-config-apply.path istota-config-apply.timeron the host, or runistota-stack config-applyby hand.istota doctor --only web.config_applierwarns about a request pending for ten minutes or taken for an hour. - The web does not come back after a change: on the host, run
istota-stack applywith an earlier plan, or copyconfig/config.toml.bak.<timestamp>back as uid 10001 and runistota-stack up.
Legacy [[default_briefings]] is read-only migration input. Create group definitions in Briefings and use the migration workflow to retire old defaults.