Skip to main content

Running the stack

Istota has one deployment: the istota stack on a Debian 13 machine dedicated to it, a server or a Lima VM on a Mac. install.sh and host/provision.sh set the machine up, and istota-stack manages it afterwards. Inside the machine the stack runs as Docker Compose services, which you reach through istota-stack when you need them. The quickstart installs it on a server, and the local install in a Lima VM on a Mac. This page covers running it afterwards; Local VM below says what differs on a Mac.

Every command here runs as root on that machine. istota-stack compose <...> is docker compose with the stack's own files, paths and settings, and istota <...> runs the CLI in the daemon container as uid 10001. Don't run a bare docker compose in src/docker/: it misses the paths and the log driver istota-stack passes, and a docker compose exec starts as root with the container's capabilities.

Stack overview​

The stack's services are defined in the deployed release's docker/docker-compose.yml, which istota-stack runs from the checkout in /srv/app/istota/src. It runs no Nextcloud of its own: storage is local by default, and full Nextcloud integration points istota at a Nextcloud you already run (see Storage).

ServicePurpose
daemonScheduler + Claude Code
webSvelteKit + FastAPI web UI
nginxReverse proxy (single entry port)
browser (profile)Chrome + VNC container for web browsing
whatsapp-baileys (profile)The WhatsApp sidecar for a paired session
signaling (profile)Talk's signaling server

First-run setup​

A fresh machine has no config.toml, and nothing serves the web UI until one exists. You write it once, in the browser or in the terminal. Both run the same validation and write the same files for the same answers.

In the browser​

istota-stack setup --web

This is the default first run. It mints a one-use setup code and a self-signed certificate valid for two days, prints an address with the code in it and the certificate's SHA-256 fingerprint, and runs a setup page on port 443:

Open this address in your browser to set up Istota:

https://203.0.113.5/istota/setup#code=7KQ2M-X9D4F-H3T8W-QP6ZA

Your browser warns that the connection is not private. Check the fingerprint in its certificate viewer before you continue. The code is in the address's fragment, which the browser never sends to the server, and the page clears it once used.

The page asks one topic per screen: the assistant's name, your name, email and time zone, a password, the AI service (an Anthropic API key, an OpenRouter API key, or a Claude subscription token from claude setup-token), how people reach Istota (only on this computer, at your own web address with a certificate from Let's Encrypt, or behind a proxy you run), an optional Nextcloud, an optional email account or calendar, and the features, the web browser included. API keys, Nextcloud, email and the calendar can be tested before you save them. Finish writes the config, the admins file, the secrets and your sign-in, and the page sends you to the sign-in page with your email filled in once the stack answers.

After the page finishes, istota-stack installs .env and host.env, builds what the answers need and the images lack (the browser image, or Claude Code for a subscription), runs provision.sh again when the host settings changed, and starts istota-stack.service. The first start takes a few minutes when something has to be built.

  • istota-stack setup-code prints the address, code and fingerprint again while a setup is running.
  • --local serves plain HTTP on 127.0.0.1 with no certificate, for the local VM or your own SSH tunnel. The port is LOCAL_FORWARD_PORT from host.env, the port Lima forwards, which the Mac writes; 8080 when it is empty.
  • ISTOTA_SETUP_PUBLISH=0.0.0.0:8443 moves the page off port 443 when something else holds it.
  • The first browser to use the code gets the only session. To start over, stop the running setup (Ctrl-C, istota-stack setup-cancel, or sudo systemctl stop istota-setup) and run istota-stack setup --web again, which mints a new code.
  • A setup that does not finish installs nothing on the host; if Finish failed partway, the run names any config or secret files it left so you can remove them. After an hour with no request the page stops, and so does the run. Fifty wrong codes stop it too.
  • With --local the page answers only at localhost, 127.0.0.1 or [::1].
  • On a cloud machine behind its provider's NAT, the printed address is the private one; open the public address instead, and the code still works.
  • It refuses when config.toml exists. Change a configured stack on the admin Configuration page, by editing config.toml, with istota-stack apply, or by running setup again.

istota-setup.service runs istota-stack setup --web as a unit. provision.sh installs it and never enables it, and it is skipped once config.toml exists. host/cloud-init.yaml starts it after the first build and prints istota-stack setup-code to the console, which a VPS provider's web console shows; install.sh --server does the same and prints them in the terminal. journalctl -u istota-setup has the same lines.

The page leaves out the operator features: WhatsApp, the Talk signaling server, the developer skill, devboxes, Nextcloud login, the DAV prefix and the auto-share setting. Set those up afterwards in config.toml or with the terminal setup. A browser re-run keeps them as they are.

In the terminal​

istota-stack setup

This runs istota setup in the image and asks every question, operator settings included. Unlike the web setup it stops after writing the files: run istota-stack check-image || istota-stack update <tag>, then provision.sh, then systemctl enable --now istota-stack. The browser question defaults to yes; a scripted --yes run without --profile browser still leaves the browser off.

Running setup again​

istota-stack setup --web --force # in the browser
istota-stack setup --force # in the terminal

Both start from what the stack's files say now. Each question, and each field on the page, holds the current answer, and finishing without a change writes the same files back. A credential you do not retype is kept. Neither changes the user setup made, nor their name, email, time zone or module choices: those live in the user's profile, which Settings changes. The page shows them read-only and has no password screen.

A re-run writes the whole config.toml from its answers, so a setting setup does not ask about goes back to its default. For one setting, use the configuration editor or istota-stack apply. Before it writes, the current config.toml is copied to config/config.toml.bak.<time>, and .env, host.env and rclone.conf to /srv/app/istota/backups/setup-<time>/ (root only); the newest ten of each are kept.

Setup refuses, by name, a value it could not write back: a [brain] kind other than claude_code or native, or a COMPOSE_PROFILES entry it does not know. Change that on the configuration page first. The browser re-run also refuses a config.toml that does not parse, and a stack where the user is not one id both in config/admins and with a [users.<id>] block; the terminal asks those questions as on a first run instead.

In the browser, the run goes in this order:

  1. It backs up the files above and copies config.toml, config/managed.json and the secret files aside into config/.setup-rerun/.
  2. It pauses istota-browser-watchdog.timer and stops the stack's containers. The page's address could otherwise reach the running web UI, which is already set up.
  3. It prints the address and code, and the page runs as on a first run, filled in.
  4. Finish writes the new files. istota-stack installs .env and host.env, builds what the answers need, runs provision.sh when the host settings changed, and starts the stack and the watchdog timer again. The page then goes to the sign-in page.

A run that does not finish puts the previous setup back: on Ctrl-C, istota-stack setup-cancel, an hour with no request, fifty wrong codes, or a failure before step 4 installs anything, it removes the setup container, restores the copied files and starts the stack on them. Once the new .env and host.env are installed the change is committed: a build that fails after that leaves the stack stopped, and the message names the istota-stack update <tag> that builds it again.

A stored credential is dropped from the page when the server it belongs to changes, so you enter it again: the Nextcloud app password when the Nextcloud address changes, the email password when the IMAP server changes, the calendar password when the CalDAV address changes. A new Nextcloud address also turns Nextcloud login off; the terminal setup turns it back on.

In direct ingress your domain has sent browsers a year of HSTS, so they refuse a self-signed certificate there. A browser re-run uses the Let's Encrypt certificate when the machine has one and prints only the domain's address. Without one it prints only the IP address and says why the domain is left out.

Configuration​

Everything the stack reads lives under /srv/app/istota:

PathHolds
config/config.tomlistota's configuration; config/ is bound read-only at /data/config in every service
config/adminsthe admin user ids
secrets/one file per credential (0400, owned by uid 10001), mounted at /run/secrets
.envcompose settings only: profiles, the hostname, published ports, the deployed and previous tags
host.envthe machine's choices: storage and ingress modes, the domain and TLS source, the release key, the Claude Code pin
compose.devbox.ymlthe per-user devbox services, rendered from config.toml (see Devboxes)
data/the state, bound at /data: databases, the master key, a local workspace (see State and volumes)
requests/the web config editor's trigger file (see Changing settings)
certs/, letsencrypt/nginx's certificate, self-signed or from files, or from certbot
.stack.lockheld by every istota-stack command that writes; it names the command holding it
src/the repository, checked out at the deployed tag

Either first-run setup runs istota setup in the image as uid 10001 and writes these once, plus the master key at /data/.secret_key. It updates .env and keeps every line it does not own. After that config.toml is yours to edit; nothing regenerates it. See SMS and WhatsApp for those blocks, which you add to config.toml yourself.

As an optional extra, an estate that manages its machines with Ansible can write these files from inventory instead; see the Ansible management role. Nothing in an install needs it.

Forge binaries​

The image ships gh and glab under /usr/local/lib/istota_forge, deliberately off PATH so the only gh or glab a task can resolve by name is the policy wrapper. [developer] gh_bin_path and glab_bin_path name them; istota setup writes both, and you change them only to point at your own build.

Being off PATH is a guard against habit, not a boundary — the sandbox binds /usr read-only, so an absolute path still reaches the real binary. The boundary is the skill proxy, which keeps the token out of the model's environment.

A config written before the binaries existed names the old default path. Nothing needs editing: the skill also probes the install location directly rather than trusting the configured path.

Changing settings​

Edit /srv/app/istota/config/config.toml and restart:

istota-stack down && istota-stack up

istota-stack apply plan.toml is the other way in: it writes config.toml from a plan's [config], prints istota apply's JSON result, and restarts the stack only when a committed change needs it (Declarative settings).

An admin can also change settings in the web UI's configuration editor. The web writes a request, and istota-config-apply.path runs istota-stack config-apply on the machine, which checks the change, writes it and restarts the stack. istota-config-apply.timer runs it every five minutes as a backstop; while nothing can be pending, that run exits without starting a container. It never waits for another istota-stack command: when one holds the lock, the next trigger or the timer picks the request up.

A credential is a file under /srv/app/istota/secrets/ (0400, owned by uid 10001); replace the file and restart. An existing install keeps the config.toml its old entrypoint rendered, unchanged, as its own file; docker/istota/config-diff.py in the image compares two configs by key if you want to see what an old render would have changed.

Upgrading an existing deployment​

istota-stack update # the newest signed release
istota-stack update vX.Y.Z # a specific signed release
istota-stack update --unsigned vX.Y.Z # any tag, without the signature check, for this run
istota-stack update --unsigned latest # the tip of main, recorded as main-<12 hex>
istota-stack rollback # back to the previous tag

update fetches the repository and checks the tag before anything moves: it refuses a branch, a lightweight tag, an unsigned tag and a tag signed by a key other than the one in /srv/app/istota/allowed_signers (written by provision.sh from RELEASE_SIGNING_KEY in host.env), and exits 65. With no tag, update picks the newest vX.Y.Z tag (by version number, so v0.10.0 is newer than v0.9.9) and checks it the same way. It does nothing when .env already names that tag as a signed install, and when the newest tag fails the check it exits 65 rather than install an older one; name the release to install another. A named tag is always built again, even when it is the one running. --unsigned skips the signature check for that run; a branch or a bare commit is still refused, because a rollback needs a name that stays put. --unsigned latest follows main without tags: it deploys main's current tip under the name main-<first 12 hex of the commit>, which names that commit for good, so rollback works as for a tag. istota-stack latest-tag prints the name it would install and changes nothing. .env records a tag installed this way as unsigned (ISTOTA_TAG_UNSIGNED=1), and a rollback to it is not verified.

Once the tag is checked out, the rest of the update is run by that release's own istota-stack, so a change a release makes to building or starting the stack applies on the update that installs it. It builds the images on the machine, renders the devbox services, and only then writes ISTOTA_TAG and ISTOTA_PREVIOUS_TAG to .env and starts the stack. A failed build puts the checkout back and leaves .env and the running stack as they were. When the release changed what provision.sh installs (the units, the host scripts, istota-stack itself), the update runs provision.sh as its last step. A stack that does not come up on the new tag still gets the host provisioned, and the update then fails with the stack on the new tag; istota-stack compose ps and journalctl CONTAINER_NAME=istota-daemon-1 say why.

The image records the tag and commit it was built from. The daemon's start-up log line reads STARTUP Running istota <version> (image <tag> <commit>), and the version the admin dashboard shows is <version>+<short commit> for anything but a release tag, so a main-<hex> deploy does not read as the last release.

rollback first asks the previous release's image whether it can run the current database. When a newer release's migration made that impossible it refuses with exit 3 and changes nothing. Otherwise it checks out the previous tag, starts the stack on it and reprovisions the host as update does. It needs that tag's images, which the update keeps; when they are gone, run istota-stack update <previous tag> instead.

Every command that writes (update, rollback, setup, apply, up, down and the rest) holds /srv/app/istota/.stack.lock. A second one waits up to ten minutes, then gives up and names the command holding it. setup --web never waits: it refuses at once while another command runs. istota-stack.service allows its stop eleven minutes, so a systemctl stop behind a running update reaches that message rather than being killed.

Updates keep the current and previous deployment images for rollback and remove older Istota image tags. istota-stack update removes dangling images labeled for the Istota Compose project before building and after each attempt. It also prunes the build cache. Before building and after a failed build, it trims cache toward a 2 GB target, so a retry stays warm. After a successful build, it drops all cache that build did not use, then trims what remains to the same 2 GB target, so the next update reuses most of its layers without the cache growing. Tagged images, containers and volumes are preserved. Unlabeled dangling images are left alone because their owner is unknown.

Stack builds use Docker's default builder explicitly. Its cache is shared with other builds on that Docker daemon, so cleanup can make those builds slower too. Layers needed by retained images and active builds cannot be reclaimed. Each prune prints the space it reclaimed, and each build cache prune adds a line to /srv/app/istota/reclaimed.log; a cleanup failure prints a warning without changing the update's exit status.

What updates do not remove. istota-stack reclaim lists what the stack left behind on the disk, with sizes, and removes nothing. istota-stack reclaim --apply NAME... removes the items you name, and cannot be undone. An update names what it finds but never removes it.

NameWhat it isWhen it stays
old-state-volumeThe state volume from before the state moved to /srv/app/istota/data, with its databaseA container uses it, a compose file names it, or the state directory does not hold the same master key, in which case the volume may be the only copy of the state
test-cache-volumeA cache volume from a test run on this hostA container uses it or a compose file names it
legacy-browser-profileThe old shared browser profile, with its signed-in state, which no user inheritsIt is not a plain directory
containerd-imagesImages in containerd left from before Docker moved to overlay2. Listed only on overlay2, since on the containerd image store these are Docker's own images
root-cachesRoot's uv and npm caches, which nothing in the stack reads

reclaim also reports layers in Docker's layer store that no image, container or build record holds. reclaim reports them and leaves them. A prune may not clear them either: on one install docker system prune -a removed 8 of 39 such layers and left about 6.8 GB. That prune also removes the previous release's images, which rollback needs.

That report reads files only overlay2 keeps. On the containerd image store, reclaim and each update instead compare the disk /var/lib/containerd takes with what docker system df says images, containers and build cache hold, and warn when the difference passes 5 GB. A healthy install has some difference, about 2 GB on the one measured, so what matters is a difference that keeps growing. The warning removes nothing.

The daemon service is called daemon​

The scheduler's compose service was called istota and is now daemon, so its container is istota-daemon-1 rather than istota-istota-1, and the image built for it is istota:<tag> rather than istota-istota:<tag>. istota-stack update brings the stack up with docker compose up -d --remove-orphans, which removes the old istota-istota-1 container. Nothing moves on disk: the state is not keyed by the service, so the new container mounts the same data.

Room identities: offline maintenance required​

When upgrading an install with legacy room identities, update to the new release, then stop the two services that write rooms, daemon and web, and the WhatsApp sidecar before running the migration. The sidecar holds inbound messages in memory for only four minutes while the daemon is away, so stopping it leaves them with WhatsApp instead; naming it is harmless when its profile is off. Leave the rest running. With full Nextcloud integration, keep your Nextcloud and the VM's rclone mount (mount-nextcloud.service) up: the channel directories move over WebDAV, and the migration refuses when either is unavailable. istota-stack update starts the new release before you stop it, and that is safe: no boot runs this migration, so the release already runs against legacy rooms on any install that has not done it yet, and after a partial migration.

istota-stack update vX.Y.Z
istota-stack compose stop daemon web whatsapp-baileys
istota-stack compose run --rm --no-deps --entrypoint istota-drop daemon istota init --relocate-rooms --scheduler-stopped
istota-stack up

Inspect the migration result before the final command. Exit 0 is done. Exit 1 is a refusal with nothing changed: refusal: live_tasks means a task was still running, so wait and rerun; any other reason needs fixing first, and the line names it. Exit 2 means partial work needs attention: the failure lines say which rooms or users, and each admin gets a bell notice listing them. Start the services again, fix what the lines name, and rerun in a later window. The command is safe to rerun while the application services remain stopped. --scheduler-stopped recovers the task rows a stopped scheduler left in flight, which would otherwise refuse as live_tasks on every rerun; leave it off if anything else is executing a task. Existing room history, native surface bindings and old links survive the identity change. Ordinary container boot initializes the schema but does not run this offline migration: the daemon's entrypoint cannot stop the web container beside it.

An install that ran the bundled Nextcloud​

The compose file no longer runs the nextcloud, postgres and redis services. An install whose config.toml still names http://nextcloud is refused at boot, with a message naming the two ways forward: move that Nextcloud, unchanged, into a compose project of its own, or switch to local storage. Moving the bundled Nextcloud walks through both.

Config keys are in the same category, deliberately: config.toml is yours now and nothing rewrites it, so a release that adds or renames a key changes nothing on an existing install until you edit the file. The changes listed below each say what to write.

An install created before the model-alias rename had [models.roles] in its config, which is now read by nothing: the per-role map was dropped and a warning naming the retired key is logged on every process start. Write the current name instead:

# was [models.roles]
[models.aliases]
fast = "..."
general = "..."
smart = "..."

This only changes behaviour if you pointed a role at something other than [brain.native] model — an unmapped role already falls back to the single configured model, so an install that left all three the same loses only the warning.

The repository-layout migration does not apply here​

python -m istota.maintenance.repos_relocate moves developer clones from one shared tree into per-user subtrees. The old bare-metal role ran it on every deploy. The stack does not, and does not need to: the old environment-rendered config left repos_dir empty and never shipped a value, so a stack installed before the per-user split has no clones in the old layout to move. A bare-metal install brought over with istota-stack import-bare-metal was already in the per-user layout, since its role ran the migration, and the import copies the clones as they are. istota setup writes repos_dir = "/data/repos" when the developer skill is on, which is the per-user layout from the start.

If you set repos_dir by hand on an install predating the per-user split, run the migration yourself once before the clones are used:

istota-stack exec python -m istota.maintenance.repos_relocate --dry-run
istota-stack exec python -m istota.maintenance.repos_relocate

It refuses rather than guessing when it cannot tell whose clones are whose, and exits 0 with nothing to do on an install that never set it.

Optional profiles​

There are three: browser (web browsing), whatsapp-baileys (WhatsApp through a paired session) and signaling (Talk over a WebSocket).

They are turned on by COMPOSE_PROFILES in /srv/app/istota/.env, a comma-separated list that istota-stack setup writes from your answers. Empty means the core stack only. To change it, edit the line:

COMPOSE_PROFILES=browser,signaling

Then run istota-stack up, which starts the containers of a profile that was added and removes those of one that was taken out, and re-run /srv/app/istota/src/host/provision.sh, which enables or disables the browser watchdog timer to match. Both are needed. istota-stack up never runs provision.sh, and provision.sh does not start or stop containers for a profile change: it runs istota-stack up only when it has just installed a different istota-stack.

The web service serves the webhook receiver's routes too (location pings, SMS and Meta's WhatsApp callbacks), so no profile is needed for them; each route answers only when its feature is enabled in the config. Set the matching [location], [sms] or [whatsapp] enabled = true in config.toml. Nginx is the public endpoint for /webhooks/.

Only the Baileys adapter needs a profile. Meta's Cloud API receives over a signed HTTP callback, which the web service already serves; a paired WhatsApp Web session receives over a Unix socket from the Node sidecar, which whatsapp-baileys starts. A profile cannot read the config, so turn it on only when [whatsapp] provider = "baileys".

A Baileys session is paired from the running stack, the first time and every time after. On a host that has never paired, the sidecar is up and offering codes. Pair from Admin, Connections with the control that asks you to type a phrase, or run istota whatsapp pair --reset and type the phrase. A plain istota whatsapp pair is refused, because the daemon cannot tell a session that was never paired from a working one. See WhatsApp.

The browser image builds for the machine's own architecture, x86-64 or arm64, since Chrome ships Linux packages for both. BROWSER_PLATFORM=linux/amd64 in .env forces an x86-64 image. Every istota-stack update builds the browser with Google's current stable Chrome, and istota doctor's browser.chrome_version warns when the running Chrome trails a stable release that has been out for more than a week (see Security).

The browser reaches public addresses only. Every Chrome connection goes through a proxy in the container that refuses a private, loopback or link-local address, for redirects, subresources and WebSockets as well as the page itself. To let it reach an internal site, grant the exact names to browser in config.toml, or in private_hosts under General in Admin > Configuration, which asks for the typed confirmation and restarts the stack for you:

[private_hosts]
"wiki.example.internal" = ["browser"]
"git.example.internal" = ["browser"]

If the host is already in the table for another consumer, add "browser" to its existing list: a second line for the same host is a TOML error. A grant reaches only the consumers it names; the configuration reference lists them.

A listed name still cannot reach the browser container's own loopback, where its API and debugging ports are, or a service on the VM itself: the browser's connection to an address the VM holds is dropped and times out. Run an internal site on another machine to grant it. The same rule cuts the browser and a devbox off from a DNS resolver on one of the VM's non-loopback addresses, so point the VM at a resolver on loopback or elsewhere.

On a VM there is a second check outside the container, a firewall that drops the browser's traffic to every private range. It follows the same grants: the VM resolves each name and opens the addresses it gets, when the stack starts and every five minutes after. If a listed site's address changes, the browser cannot reach it until the next refresh. A name that will not resolve opens nothing and logs a warning in the journal of istota-browser-grants.service. On the local VM, a name that resolves to the Mac's address (HOST_GATEWAY_ADDR, 192.168.5.2), or that address written as the grant, opens nothing either and logs a warning naming it: that address forwards to the Mac's loopback, which the browser never reaches.

The firewall identifies the browser by a fixed address, 172.29.0.2. If 172.29.0.0/24 is taken on your host, set ISTOTA_BROWSER_SUBNET in host.env to another x.y.z.0/24, then run systemctl restart istota-devbox-egress and istota-stack up.

Talk over the signaling server​

The signaling profile replaces polling Nextcloud for Talk messages with a WebSocket that Nextcloud pushes to. It cuts inbound latency to a single round trip and removes a request per room per cycle, which is what makes it worth the extra container on a deployment with more than a handful of rooms.

Three things have to line up, and the profile is only the first.

  1. Your Nextcloud's Talk has to have the server registered: occ talk:signaling:add <url> <secret> --verify, with ISTOTA_TALK_SIGNALING_SECRET from .env as the secret, and set ISTOTA_TALK_SIGNALING_BACKEND_URLS to your Nextcloud's URL (both the one browsers use and the one this stack uses, comma-separated, if they differ).
  2. [talk.signaling] enabled = true in config.toml, which is what tells the daemon to use it. istota setup writes it, with url, when you choose the profile.
  3. The websockets library, which comes with the signaling extra and is already in the image.

The registered URL has to resolve from two places. A browser connects to it, and your Nextcloud's own PHP posts room and chat events to it, which is what makes inbound a push at all. The stack's answer is the nginx it already runs, which proxies /standalone-signaling/ through to the server, so the URL is https://<this stack's DOMAIN>/standalone-signaling/. Check it from the Nextcloud host with curl -s https://your.domain/standalone-signaling/api/v1/welcome, which answers {"nextcloud-spreed-signaling":"Welcome",...}. Send a GET, not a HEAD: the signaling server registers that route for GET only and answers a curl -I with 404.

The registration is a config write on the Nextcloud side and nothing more: in Talk's Add.php, --verify is the per-server flag for validating the server's TLS certificate, not a reachability probe. Changing the URL later means running talk:signaling:add again.

[talk.signaling] url is a separate thing and istota setup fills it in: it is the daemon's own route, http://signaling:8080, since the daemon is on the container network beside the server. Left empty the daemon reads the browser-facing URL out of Talk's settings, which on this stack is the wrong answer.

One consequence of turning it on before the server is registered: the daemon refuses to boot, and restart: unless-stopped makes that a loop that keeps web down with it, since it waits for the daemon to be healthy. Set [talk.signaling] enabled = false to back out. Note also that nothing orders daemon after signaling (compose would then start the server on every deployment), so a first boot can post its provisioning message while the server is still coming up; the daemon's own watchers retry, but that one post can fail.

If the daemon is told to use it and cannot — Talk still in internal signaling mode, or the library missing — it refuses to boot. That is deliberate: a daemon quietly polling while you believe push is live is worse than one that did not start. istota doctor --only talk.signaling_reachable says which of the three is missing.

Registering an external signaling server changes call signaling for every Talk user on this Nextcloud, not only for istota. With no MCU configured media stays peer to peer and calls keep working, but it is a change to a shared service. The container itself is one small Go binary — no Janus, no external NATS, and istota never publishes or subscribes to a media stream.

Two consequences to expect once it is on. istota holds an active Talk session in every room it watches, around the clock, so it shows as present to everyone else in those rooms; it is not in a call and never joins one. And a second daemon pointed at the same Nextcloud opens its own sessions and receives every event — Talk allows several sessions per attendee — so duplicate work is prevented by the read cursor rather than by the transport. Point a staging daemon at a staging Nextcloud.

There is no secret to configure on istota's side. It authenticates as its own Nextcloud user, so the server URL, the connection token and the per-room session are minted on demand from calls the bot account can already make. The shared secret above is Talk's, for the server to trust Nextcloud.

[talk.signaling] payload_direct = true goes one step further and ingests the message the server relays instead of refetching it. Leave it off unless you have a reason: it is the only part of this path that can be wrong about message content rather than about timing, and Talk only relays a message at all from roughly Talk 21 — below that every event is a bare notification and the setting changes nothing.

Devboxes​

A devbox is a persistent per-user Linux container, built from docker/devbox/Dockerfile at uid 10001, the daemon's own. Compose cannot loop over users, so the services live in a second compose file that istota renders from config.toml:

[devbox]
enabled = true
users = ["alice"]

istota devbox compose-file prints one devbox-<user> service per entry, plus the daemon service's mounts of each user's two socket volumes, and creates each user's repos directory first. istota-stack writes its output to /srv/app/istota/compose.devbox.yml on setup, update and an apply that changed the config, and passes the file as a second -f to every compose command. Only update builds the devbox image. After editing users in config.toml by hand, run istota-stack update with the deployed tag (ISTOTA_TAG in .env) to re-render the file and build the image. If .env has ISTOTA_TAG_UNSIGNED=1, as on a Lima VM or an install following main, pass --unsigned: istota-stack update --unsigned main-<commit> rebuilds that same commit, where --unsigned latest would move to main's current tip. The next up removes the service of a user taken out and keeps their home volume.

What each devbox gets, and nothing else:

  • devbox-home-<user> at /home/dev, its persistent home.
  • devbox-exec-<user> at /run/istota-exec: the exec transport's socket, which the server inside the box creates and the daemon container reaches at [developer.container] exec_socket_dir/<user>.
  • devbox-cred-<user> at /run/istota-cred: the credential proxy's socket, which istota creates at [developer] devbox_proxy_socket_dir/<user>. The proxy answers on that socket as that user, whoever connects, so it matters that no other container mounts it and no task sandbox binds any credential socket directory. It has no forge token to give unless [devbox] forge_users names the user, and then any code in that devbox can read the token.
  • Its own subdirectory of the state directory, /data/repos/<user>, at the same path on both sides.

istota setup writes both socket directories under /data/devbox/ when the developer skill is on; the render refuses socket directories outside /data, because only mounts there are handed to uid 10001 when the daemon container starts.

istota-skill devbox reset needs no Docker CLI: it is a request on the exec transport. The server empties /home/dev if it is a mount point, answers, and exits, and the service's restart: unless-stopped brings the box back.

Egress filtering is the VM's. The devbox network has a fixed subnet ([devbox] network_subnet, 172.30.0.0/24 by default), and host/istota-devbox-egress.service on the VM drops traffic from it to link-local and cloud metadata, RFC 1918 and CGNAT addresses. A stack run anywhere without that unit leaves a devbox able to reach the local network.

Upgrading from a release that had a devbox profile in this file: that container is not the one rendered here. Copy out or docker commit what you want from it, then remove it, its docker_devbox_home volume and its docker_devbox-net network by hand.

Storage​

Two questions decide the storage: whether istota uses a Nextcloud ([nextcloud] url), and where the workspace lives (workspace_mount_path, when it is a mount). STORAGE in host.env says which mount, if any, the machine provides. istota setup writes all three from your answers:

Modeconfig.tomlWorkspacehost.env
Local (the default)no [nextcloud] url/data/workspace in the state directorySTORAGE=local
Nextcloud, local workspaceurl names your Nextcloud, no workspace_mount_path/data/workspace in the state directorySTORAGE=local
Full Nextcloud integrationurl names your Nextcloud, workspace_mount_path = "/mnt/shared"the VM's rclone mount of the bot's files, bound at /mnt/sharedSTORAGE=nextcloud
Host folder (the local VM)no [nextcloud] url; workspace_mount_path = "/mnt/shared"a Mac folder Lima shares into the VM at /srv/mount/host-folder, bound at /mnt/sharedSTORAGE=host-folder

An older config may name the mount nextcloud_mount_path, the key's old name; it is read as workspace_mount_path.

When you connect a Nextcloud, setup asks where the workspace should live: mount (the default) or local. A scripted run takes --workspace mount|local and defaults to mount when it is given --nextcloud-url. The browser setup asks the same on its Nextcloud screen, with the mount chosen until you pick "On this server". With either answer the bot is a regular user on your Nextcloud: Talk, the nextcloud skill's user, group, Talk and share-listing verbs, and avatars all work.

With a local workspace, provision.sh installs no rclone and no mount unit, and setup writes no dav_prefix and turns auto_share_bot_dir off, since nothing of the workspace is in Nextcloud. Users reach their files in the web UI, not in Nextcloud. A file posted in Talk is fetched into the room's folder, Channels/<room>/media/, and nextcloud talk share-file uploads a copy before posting it. The skill's files verbs, share create and share link refuse, because the file they name is not in Nextcloud. Back up /srv/app/istota/data, which now holds the workspace too (see Backing up a local install).

In full integration the bot is a regular user on a Nextcloud you run, and it sees what users share with it. The VM mounts that account's files with rclone at /srv/mount/nextcloud/content (mount-nextcloud.service), and compose binds the mount into daemon and web at /mnt/shared with rslave propagation, so a remount shows through without restarting them. istota setup writes workspace_path and workspace_mount_path as /mnt/shared, and the mount's rclone.conf (one WebDAV remote named nextcloud, the app password obscured as rclone obscure does it) with RCLONE_REMOTE=nextcloud in host.env, so the mount needs no hand-written config.

The mount keeps its directory listings for ten minutes. That is safe because the daemon does not wait for them to expire: every 30 seconds ([scheduler] tree_watch_interval) it asks Nextcloud whether anything under the bot's root changed, reads only the folders that did, and tells the mount which listings to drop through rclone's control socket (the rc). An edit made in Nextcloud therefore reaches the TASKS.md poll, the CRON.md sync and the shared-file organizer within about a minute, and each of them also runs once an hour regardless. The rc listens on a Unix socket in /srv/app/istota/rclone-rc/ (a directory only uid 10001 can enter) and takes a password from /srv/app/istota/rclone-rc.env, which provision.sh generates once. It can write and delete anywhere on the remote, so only the daemon container binds it, read-only, no task sandbox sees it, and the daemon sends it three calls and nothing else. istota doctor's nextcloud.rclone_rc checks that it answers with the password and refuses without one. Without the rc, the watcher still runs, and a change shows once the mount's own ten-minute cache expires; with tree_watch_interval = 0 the pollers go back to reading the mount on their own intervals.

The entrypoint refuses to start the daemon when full integration is configured and /mnt/shared is not a mount of type fuse.rclone, so the daemon never writes into an unmounted path; compose's restart policy retries until the mount is up. A host folder must be a virtiofs mount with a .istota-workspace file at its root. A workspace_mount_path with no Nextcloud URL and no type that STORAGE declares is refused too, so a config for one mode does not start on a machine provisioned for another. istota doctor's runtime.mount_liveness is the runtime check after that. Docker Desktop refuses rslave on a macOS path, which is one reason a Mac runs the stack in a Lima VM rather than in Docker Desktop.

To move an install in full integration to a local workspace, see Moving to a local workspace.

Workspace files have no versions or trash in either mode.

Ingress and TLS​

The compose nginx is the only listener the stack publishes. The mode is INGRESS in /srv/app/istota/host.env, which istota-stack setup writes and which both nginx and istota read:

INGRESSnginx listens onTLS
local (the default)loopbacknone
proxiedone private address (LISTEN_ADDR:LISTEN_PORT), allowing only UPSTREAM_PROXYon the hop from the proxy: a self-signed certificate the proxy pins (TLS_CERT_SOURCE=self-signed), a certificate from files, or none
directports 80 and 443 on every addressa certificate from certbot on the VM (TLS_CERT_SOURCE=acme) or from files

docker/nginx/istota-ingress.sh renders the server blocks for the mode around the one location template, istota.conf.template, before nginx starts, and refuses a mode it cannot render (proxied with no upstream address, for one). In direct mode, before the first certificate exists, nginx serves only the ACME challenge and the redirect on port 80; istota doctor's web.tls reports FAIL until the certificate is there. The published ports are NGINX_PUBLISH and NGINX_PUBLISH_TLS in .env, which the wizard writes per mode.

Behind TLS (direct and proxied) the entrypoint refuses to start when [site] hostname and the stack's DOMAIN differ, since every login would then fail its origin check.

A static site at the root​

By default / redirects to /istota/ and every other path outside the app answers 404. To serve a static site of your own at the root of the hostname instead, put its files in a directory on the VM and name it in host.env:

sudo mkdir -p /srv/app/istota/site
sudo cp -r ./my-site/. /srv/app/istota/site/
sudo istota-stack host-env SITE_DIR=/srv/app/istota/site
sudo istota-stack up

nginx then serves index.html at / and any other file by its path. A missing file is 404, and so is anything whose path has a part starting with a dot (.git/, for one). /istota/, /webhooks/ and the signaling path still go to the app. Removing the key and running istota-stack up again puts the redirect back.

The directory is mounted read-only into the nginx container and into no other. That is the point of the option: the agent cannot write to anything the stack publishes, so the site changes only when you change it (instance site hosting, which let the agent write to a public directory, was removed for that reason). istota-stack therefore refuses a SITE_DIR that is inside the workspace mount, the state directory, config/, secrets/, requests/, the checkout, the setup directories, Docker's data directory or rclone's cache, or that holds any of them, such as /srv/app/istota itself. A refused or missing directory prints a warning and the stack starts with the redirect.

Encrypting the hop from a reverse proxy​

In proxied mode the reverse proxy terminates the public TLS and forwards to the VM. What crosses that hop is everything: passwords at login, session cookies, OAuth codes, and webhook payloads (messages, location points). Plain HTTP there is acceptable only on a network nothing else shares. Otherwise encrypt it, and make the proxy check what it connects to. A certificate the proxy does not verify stops only passive reading: anyone who can redirect the traffic presents their own certificate and the proxy accepts it.

TLS_CERT_SOURCE=self-signed (the wizard's default for proxied) does both. provision.sh makes a certificate once, in /srv/app/istota/certs/, naming DOMAIN and LISTEN_ADDR, valid for ten years, and never replaces it, since a new one would break the pin; it prints the SHA-256 fingerprint on every run. nginx then listens with TLS on LISTEN_ADDR:LISTEN_PORT. Copy fullchain.pem to the proxy and make it trust that certificate alone for this upstream:

  • nginx:

    proxy_pass https://<LISTEN_ADDR>:<LISTEN_PORT>;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /etc/nginx/istota-upstream.pem;
    proxy_ssl_name <DOMAIN>;
    proxy_ssl_server_name on;
  • Caddy: reverse_proxy https://<LISTEN_ADDR>:<LISTEN_PORT> with a transport http { tls_trust_pool file /etc/caddy/istota-upstream.pem tls_server_name <DOMAIN> } block.

  • HAProxy: server istota <LISTEN_ADDR>:<LISTEN_PORT> ssl verify required ca-file /etc/haproxy/istota-upstream.pem verifyhost <DOMAIN> sni str(<DOMAIN>).

  • Traefik: a serversTransport with rootCAs naming the file and serverName: <DOMAIN>, referenced by the service.

To replace the certificate, delete both files in /srv/app/istota/certs/, run provision.sh, copy the new fullchain.pem to the proxy and reload it, then restart the stack. TLS_CERT_SOURCE=files is the same listener with a certificate you provide, for a proxy that verifies against an internal CA instead.

Websockets through a reverse proxy​

The admin browser console (Admin > Browsers) is a websocket at /istota/api/admin/browsers/console. In direct and local mode the stack's nginx handles it with no configuration. In proxied mode your proxy must forward the upgrade, or the console page says it could not connect:

  • nginx: proxy_http_version 1.1;, proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; in the location that passes /istota/ on, and a proxy_read_timeout of up to an hour (3600s) so a console left on a still screen is not dropped.
  • Apache: mod_proxy_wstunnel, or ProxyPass ... upgrade=websocket on Apache 2.4.47 and later.
  • Caddy, HAProxy and Traefik forward websocket upgrades by default.

State and volumes​

Istota's /data is /srv/app/istota/data on the VM, a directory owned by uid 10001, mode 0711: the container's start-up step can pass through it to hand the volumes mounted below to uid 10001, and only uid 10001 can list it. It holds the databases (/data/db), the master key (/data/.secret_key, unless a secrets file supplies it), and with a local workspace, with or without Nextcloud, the workspace (/data/workspace). /data/config is a separate bind of /srv/app/istota/config. This directory is the one to back up. istota-stack resets its mode on every start. A plain docker compose run outside istota-stack would not bind it and would keep the state in a named volume instead, which is one more reason to use istota-stack compose.

VolumePurpose
browser_profilePersistent Chrome profiles per user, including their logins; also the console TLS certificate and parked legacy profile

In full Nextcloud integration and on the local VM the workspace is not in /data: it is the VM's rclone mount or the Mac folder, bound at /mnt/shared.

Local VM​

On a Mac the stack runs in a Lima VM that the Mac's own istota-stack creates and controls; the local install page covers installing and running it. Inside the VM it is this stack, with host settings that create writes into host.env:

host.envValueEffect
STORAGEhost-folderthe workspace is the Mac folder at /srv/mount/host-folder; provision.sh makes istota-stack.service require that mount, and never creates, chmods or chowns the folder
INGRESSlocalnginx on the VM's loopback, which Lima forwards to the Mac's localhost:<port>
HOST_LOOPBACK_BLOCK, HOST_GATEWAY_ADDR, HOST_LOOPBACK_ALLOW1, 192.168.5.2, emptycontainers cannot reach the Mac's loopback except DNS and the ports listed, and a devbox or the browser not even those (Security)
LOCAL_FORWARD_PORTthe Mac's --port, 8080 by defaultthe port Lima forwards; setup refuses a local hostname on another port, defaults to localhost:<port>, and publishes nginx and the setup page on it

Every command on this page works from the Mac: istota-stack <verb> there runs the VM's istota-stack <verb> as root, and istota runs the CLI in the daemon container. setup writes LOCAL_FORWARD_PORT first when it differs, and setup --web adds --local and opens the page. apply and import-bare-metal take a path on the Mac. Paths such as /srv/app/istota/config/config.toml are in the VM; istota-stack shell opens a shell there.

What differs from a server:

  • First run. The Mac's istota-stack create runs the browser setup and opens the page once it answers; it keeps the host folder as the workspace. create --terminal-setup runs the terminal setup with storage, ingress and hostname set. Either way setup writes [scheduler] cron_max_staleness_minutes = 720 for local ingress, so work missed while the Mac slept runs once after wake.
  • Releases. The VM verifies the tag as a server does. After each update the Mac's istota-stack copies itself, the istota shim and the Lima template out of the VM's verified checkout.
  • Backups. The database snapshots and the config copies land in the Mac folder, and istota-stack update, setup, apply and import-standalone copy .env and host.env there too (Backups/config/<date>/, once a config.toml exists). The master key goes to the Mac's login Keychain. istota-stack restore on the Mac rebuilds a lost VM from the two; in the VM, istota-stack restore is the half that runs istota migrate restore-workspace with the key on stdin, onto a stack that was never set up.
  • The folder's marker. The daemon will not start without .istota-workspace at the folder's root, and istota doctor's runtime.mount_liveness fails without it on a running stack. A folder that is renamed or on an unplugged volume reads as an empty virtiofs mount, and the marker is how the stack tells.

Backing up a local install​

Istota backs up nothing but its databases. On a timer it snapshots them to [scheduler] db_backup_dir, by default Backups/db/snapshots under the workspace. In full Nextcloud integration that is on the mount, so the snapshots leave the VM, beside copies of config.toml and the admins file in Backups/config/<date>/; istota-stack update, setup and apply copy .env and host.env there too, neither of which holds a credential. In local storage mode it is /data/workspace/Backups/db/snapshots, in the same /srv/app/istota/data as the databases themselves: a snapshot there gets you back from a corrupted database file, not from losing the VM's disk. istota doctor reports this as a warning under backups.off_volume, and runtime.workspace_disk warns when the disk runs low on space.

Each snapshot is taken and checked on local disk first, in .backup-staging/ beside the framework database, then copied to the destination once. The row counts of each run go in a manifest.json in its dated directory, and the next run compares against those instead of reading the previous snapshots back, which on the mount would download them. So the state directory needs free space for the largest database while a backup runs.

The workspace and the state directory as a whole are yours to back up. Either back up /srv/app/istota/data with whatever backs up the VM's disk, or stop the stack and archive it:

istota-stack down
tar -czf /root/istota-data.tar.gz -C /srv/app/istota/data .
istota-stack up

Unless a secrets file supplies it, the archive holds /data/.secret_key beside the databases it decrypts, so keep it somewhere at least as private as the VM (see docs/deployment/security.md). To keep the database snapshots off the VM's disk without archiving the directory, set db_backup_dir to a directory on another disk mounted into the stack.

Recovering a lost installation​

Admin → Configuration can download a backup of the saved configuration, as plain TOML or as an encrypted KeePass file with the installation's credentials (Backing up and restoring the configuration). That backup is one part of rebuilding an installation. This section says what each kind of backup gets back, what to keep outside the installation, and how to rebuild before the web UI runs.

What each backup gets back​

What you keptWhat you get back
The plain .toml backupThe saved settings without credentials, checked again against the new install. It is a new installation: enter the credentials again. No users, rooms, history or stored credentials come back.
The .kdbx backup, its password, and its key file if it has oneThe saved settings, the installation credentials in the file and the private push signing key. Still a new installation, unless the databases and workspace come back too.
The .kdbx, the database snapshots and config copies from the workspace's Backups/, and the original master keyThe old installation's state, through istota-stack restore. Note any module database, external file or provider session that did not come back.

The .kdbx password opens the backup file. It is not the master key (ISTOTA_SECRET_KEY, kept at /data/.secret_key), which decrypts the credentials stored in the database: users' Settings → Credentials, connected services and Google tokens. The installation credentials in the .kdbx cannot rebuild those. Without the master key the databases still restore, but the credentials stored in them cannot be read. A database and a key can both look valid and still not belong together, so check that a stored credential decrypts (below) before you call a recovery done.

What to keep outside the installation​

Keep each of these somewhere that survives losing both the VM and the machine it runs on. A key file saved only on the lost machine, or a backup password kept only in Istota's own credentials, is not there when you need it. A successful download is not a complete recovery kit.

  • The .kdbx backup, its password and its key file.
  • The master key, in a backup of its own. On a Mac the local VM copies it into the login Keychain (service istota.local, account secret-key-<instance>), which covers losing the VM but not losing the Mac. A server needs its own copy off the machine. The web backup never includes it.
  • The database snapshots (Backups/db/snapshots/<date>/) and the workspace's files. A workspace on the lost VM's own disk is lost with it unless something copied it off (Backing up a local install). A Nextcloud or Mac workspace that survived helps only as far as its files and backups survived.
  • The config copies in Backups/config/<date>/: config.toml, admins, stack.env and host.env, which the stack writes only where the workspace is a mount. On a server also keep rclone.conf for a Nextcloud workspace and whatever you gave provision.sh and setup. The .kdbx holds none of these files and no admin list.
  • The push signing key pair, [push] signing_key_path (by default /data/config/push/signing.pem) and its .pub, when private push is on. No config copy and no database snapshot holds it. The .kdbx holds the private key in its Push signing key group; the .pub is written from it when the key is restored. A new key makes every enrolled phone enroll again before it shows private previews, while the key the phones enrolled under keeps them working, enrollments restored with the databases included.
  • The rest of the deployment: the release you ran, the storage mode and where the workspace lives, the hostname and DNS, the release signing key you trust, and how to get back into each outside account (model provider, mail, Nextcloud). The .kdbx records the application version, which does not say which database schema a snapshot needs.
  • A way back into an admin account without the old browser session or working mail. A restored database keeps the login identities, and the restored admins file keeps the list; istota auth reset <user> --print-link prints a password link on the host where [web] auth includes email. On a fresh database, setup makes the first admin.

The web session signing key needs no backup: a new one signs everyone out. The web token key (ISTOTA_WEB_TOKEN_KEY) is different: without the old one, the Nextcloud tokens the web stored for users cannot be read, and each user connects again. Paired WhatsApp sessions, browser profiles and TLS certificates are in none of these backups and are set up again.

With the configuration backup alone​

  1. Install a new stack as usual (provision.sh, istota-stack update, setup) and sign in as its admin.
  2. Where setup needs a credential, such as the model key or the Nextcloud app password, open the .kdbx in KeePassXC on a trusted machine and copy it from there. Do not upload the backup to the broken installation first.
  3. In Admin → Configuration, Restore configuration takes the backup file. Review the restored settings, and select the credentials to restore. Settings that stay a host action, such as the Nextcloud app password and the site hostname, are listed but not applied from the page; change those with istota-stack setup --force or write a credential with istota-stack put-files.
  4. The private push signing key is one of the credentials listed. The page restores it only where [push] signing_key_path is /data/config/push/signing.pem in the configuration the restore leaves, and only by selecting it; the host applier writes it with istota push import-key. Where a different key is in place, its row says changed and the review says that phones enrolled under that key must enroll again. Any other path is host only: copy the key out of the .kdbx's Push signing key entry on a trusted machine, pipe it into istota-stack push-key import on the VM (--force to replace a key already there), and delete the copy.

With the databases and the master key​

Start from a new, stopped stack, and do not run setup against it: setup makes a different master key and config, and the restore then refuses to replace them.

  • On a Mac, run istota-stack restore --no-start (Backups and recovery). It makes a VM without setup, writes the key from the Keychain, the config copies and the databases, and leaves the stack stopped, also at the VM's next boot, and held off the network (below). Without --no-start it starts the stack at the end, with no hold.
  • On a server, run provision.sh with the host.env settings of the old install, istota-stack update <tag> with the release it ran, and set up the workspace mount (for Nextcloud, rclone.conf, with the app password from the .kdbx). Check that the workspace shows the old Backups/, stop the stack (systemctl stop istota-stack), then pass the master key on stdin: istota-stack restore --hold < key-file. It puts back the key, config.toml, admins, the .env and host.env copies and the databases, and leaves the stack stopped, though it may run provision.sh, which enables the stack to start at the next boot. Where the copies in Backups/config/ are missing, restore refuses, and it does not take a .kdbx in their place. The steps are then manual, with the stack stopped: write config.toml and admins from your own copies (or config.toml from the configuration backup), the master key to /data/.secret_key (mode 0600, owned by uid 10001), and restore the snapshots with python -m istota.maintenance.db_restore --all. The config.toml in either backup has "<unchanged>" in place of each credential written in the file itself, such as a provider's api_key: copy each value from the .kdbx's Inline credentials group before you start the stack. db_restore --all follows the users config.toml names, so a user known only to the database gets no module databases back.

restore does not copy secrets/ or the push signing key. Write the deployment credentials from the .kdbx with istota-stack put-files, which reads JSON on stdin, so no value goes on a command line: open the backup only while you build that JSON, and delete the file afterwards. Write the push key from its Push signing key entry with istota-stack push-key import, the key on stdin, or once the stack runs, restore it from Admin → Configuration as above. The Nextcloud app password also has to match the mount's rclone.conf. Written while the stack is stopped, they are read when it starts; on a running stack, restart it afterwards.

A restored stack polls mail, runs scheduled jobs and sends messages with whatever credentials work, as soon as it starts. Removing credentials is not enough, since the restored database holds working ones. Keep it quiet until you have checked it with the hold that restore --hold puts in (restore --no-start on a Mac passes it):

  • What the hold blocks. Every connection the stack's containers open to anything outside their own networks, DNS included, and connections that were open before it went in. It is an nft table of its own (inet istota_egress_hold), loaded at boot before Docker starts, so it holds across reboots and the containers' restart policy cannot bring them back unheld. A run of provision.sh or a create re-run leaves it in place, and nothing the stack's own firewall rules do can open it. Image builds still work, since they use Docker's default bridge.
  • What it does not block. Processes on the VM itself, outside the containers: on a server that includes the rclone mount, certbot and the VM's own name lookups. Where the VM resolves names through its own resolver on 127.0.0.1 (dnsmasq, unbound), Docker forwards the containers' lookups from the VM, so those still resolve. A restart of nftables.service clears the hold's table; istota-stack hold on puts it back. Block the VM's outbound network from outside the guest as well if those matter (the host's firewall or the provider's network rules). On a Mac that is not possible, because the VM's traffic leaves through Lima on the Mac, where a firewall cannot tell it apart; the hold is what you have there.
  • While it is on, istota doctor warns runtime.egress_hold, and every check that reaches out (name resolution, the model, mail, Nextcloud) fails for that reason. istota-stack up starts the stack through istota-stack.service, so a clean shutdown stops it. The hold stays in until istota-stack hold off. istota-stack hold says whether it is on, and istota-stack hold on puts it back on any stack.
  • If the table is missing while the hold is on (a failed nft call, a script that was not installed), istota-stack up refuses to start the stack rather than start it unheld.

Then start the stack (istota-stack up), and check from inside the daemon container that an outside address does not answer, for example istota-stack exec python -c 'import socket; socket.create_connection(("1.1.1.1", 443), timeout=5)', which should time out. Lift the hold with istota-stack hold off only after the checks below. On a Mac, istota-stack create then turns the stack on at the VM's boot again, rebuilding the image first if the restored config needs Claude Code. A create re-run does not lift the hold.

Before you let it out​

  • Record which dates you restored: the configuration backup, the database snapshot and the credentials. They are separate stores, not one point in time; prefer a set taken together, and note any fallback or module that did not restore.
  • Use the release the old install ran, or a supported upgrade from it. Never select an older release to suit an older snapshot; restore refuses a snapshot newer than the image's schema.
  • Check the storage paths, mount mode, hostname, callback URLs and anything a management plan owned. A new hostname needs new OAuth callbacks, webhooks and TLS even when every credential is right.
  • Run istota doctor, sign in as an admin, and open a module's data. Check that stored credentials decrypt without showing them: istota secret export --user <user> --out <file> for a user who has some decrypts each one to build the file and fails when the key does not match. It refuses to run without a terminal, so run it from an interactive shell (istota-stack shell on a Mac, then istota secret export ...), not from a script. Delete the file afterwards.
  • Look at enabled scheduled jobs, pending tasks and outgoing mail before you lift the network block. A snapshot can put a job back to before something it already did, and nothing replays or skips that work for you.
  • Keep the original backups unchanged, so a failed attempt can be repeated on another clean VM.

A Mac restore and the configuration-only restore were rehearsed end to end on a disposable Lima VM in November 2026, before --no-start existed; the --no-start path with the hold, and the server path, have not been rehearsed yet.

Container logs​

On the VM every service logs to the systemd journal, under the container's name: journalctl CONTAINER_NAME=istota-daemon-1 reads the daemon, and anything that ships the host's journal ships the stack's output with it. docker logs and istota-stack compose logs still work. The journal's size cap from provision.sh (500 MB) bounds it. Devbox containers are the exception: they keep their own rotated json-file logs, because build and test output would push the host's own lines out of the journal.

The compose file's own default is Docker's json-file driver, which is what the test tiers get when they run it outside istota-stack, on hosts with no journald.

To hand logs to someone, use istota-stack logs [--since DURATION] (30m, 24h, 7d; the default is 24h). It prints the containers' logs, then the journal of istota's own units (istota-* and mount-nextcloud.service), with every line redacted: each value the stack holds in a secret file (secrets/, the master key and the web token key in data/, the code of a setup in progress, and the secret and password lines of .env and rclone-rc.env) is replaced with [redacted] wherever it appears, and so are the user name and password, the query and the fragment of every web address, which is where a setup code, a set-password link or an enrolment token travels. It takes no lock. When a secret file cannot be read, or is a link or anything but a plain file, it prints nothing and exits 78, because a value it cannot read is a value it cannot redact. A credential still written inline in config.toml is not covered: move it into its file first (doctor's security.inline_credentials names them). On the Mac, istota-stack logs runs the VM's verb.

Browser profiles​

Each user has a separate profile under /data/browser-profile/users/. Logins and site storage survive task completion, session closure, process reaping and container restarts. They are never shared between users. Later tasks for the same user inherit that user's authenticated access without another vault fetch. Cloudflare clearance warms up separately for each user. Profiles are not automatically deleted.

The compose file passes these settings to the browser service:

VariableDefaultPurpose
BROWSER_MAX_INSTANCES2Maximum live Chrome processes
BROWSER_INSTANCE_IDLE_S900Idle seconds before a process with no live sessions is reaped
MAX_BROWSER_SESSIONS2Session limit per user
BROWSER_MAX_TOTAL_SESSIONS4Session limit across all users
BROWSER_DISK_CACHE_BYTES104857600Chrome disk-cache limit per profile, not a limit on total profile size
BROWSE_WATCHDOG_DEADLINE_S90Seconds a request may run before Chrome is killed and relaunched; 0 disables the watchdog. Keep it between about 65 and 120: lower cuts off long type actions and Cloudflare challenge solving, and above 120 the skill's own client gives up first
BROWSE_WATCHDOG_POLL_S5Seconds between the watchdog's checks of the in-flight request; at least 1
BROWSER_CDP_FAILURE_THRESHOLD3Consecutive CDP failures that mark the container unhealthy; 0 disables this check
BROWSER_CDP_FAILURE_WINDOW_S900How long that verdict stays red after the last failure; values below 210 are raised to 210
BROWSER_WEDGE_RECOVERY_THRESHOLD3Watchdog recoveries within the window that mark the container unhealthy; 0 disables this check
BROWSER_WEDGE_RECOVERY_WINDOW_S900Window for counting those recoveries; values below 210 are raised to 210

The container retains its 3 GiB memory limit. Setting BROWSER_MAX_INSTANCES=1 reduces process memory while keeping separate profiles; switching users can require a cold start. A full process pool evicts only an instance with no live sessions, otherwise it returns a capacity error with a retry delay. Session limits are separate: opening a session evicts the requesting user's oldest first, and can evict another user's oldest at the global cap when the requester has none. Browser requests still execute serially.

Use istota-skill browse state to inspect the requesting user's profile size and cookie domains, never cookie values. Domains are null when its browser is stopped or disconnected; state inspection does not start Chrome. Close that user's sessions before browse forget --origin https://example.com or browse forget --all to clear cookies and origin storage. Origin clearing includes cookies shared through a parent domain and can log out sibling sites. browse forget --all --profile removes the complete profile only after verified browser shutdown, and resets history, permissions and caches too.

The browser console is for operators only. A web admin opens it from Admin > Browsers: View on a live browser asks for the admin's password or a mailed code, then shows that user's display in the page. A login completed there belongs only to that user. When VNC_PASSWORD is set, the console asks for it as well. Each open, refusal and close is logged by the web process with the admin, the user and the duration. A console closes after an hour, and within 30 seconds of the admin's credentials changing or their admin rights being removed (after the admins file is reloaded). VNC activity does not keep a browser alive, so a browser with no browse activity still closes when its idle time runs out.

The web container reaches each display through a Unix socket in the browser-console volume, which only the browser and web services mount. It has no route to the browser API. The noVNC listener on port 6080 still runs, bound to loopback, as the way in when the web app is down: open an SSH tunnel to the VM (ssh -L 6080:127.0.0.1:6080 <vm>), browse to https://localhost:6080/instances.html and choose the user. Its index lists live user IDs to anyone who can reach the port, so leave it on loopback. Do not give users console links or publish the port.

Upgrade: Rebuild and recreate the browser container when updating the skill (istota-stack update does both). On first boot the old shared profile is parked under legacy-profile/ in the same volume; no user inherits it. Each user signs in again unless an operator deliberately recovers the old profile. TLS certificates and existing per-user profiles stay in place. A parking collision needs operator attention and does not overwrite either copy. Until the image is updated, non-credential calls warn with shared_profile and credential fills refuse. After upgrading, verify /health advertises per_user_profiles: true. Direct API clients must send X-Istota-User on scoped requests; IDs must be single path components, ASCII, without control characters or surrounding whitespace.

API token: Every path on the browser API except /health needs Authorization: Bearer <token>. The token is secrets/istota_browser_api_token. istota-stack generates it, and an existing install gets one from its next update. A browser container with no token refuses everything but /health with 503. To replace the token, empty the file, run istota-stack up, and restart the stack so the daemon and the browser read the same value. istota doctor reports a mismatch as browser.api_token. If you start the stack without istota-stack, put a random value in that file yourself.

Security​

  • The network allowlist is the default. istota setup leaves [security.network] enabled at its default, on, so each task gets --unshare-net and the CONNECT proxy's host:port allowlist. A config the old entrypoint rendered says enabled = false, and keeps saying it until you change it
  • The filesystem sandbox runs here, under the run contract the daemon service carries. See below
  • Skill proxy: enabled by default and works inside the container. It is what keeps credentials out of the model's environment
  • All extras installed: every optional dependency included in the image
  • Devboxes are rendered per user into a second compose file, and each one's credential socket is a volume only it and the daemon mount. Details above

Running tasks sandboxed​

The daemon service in docker-compose.yml carries the grant bubblewrap needs and nothing wider:

security_opt:
- seccomp=./istota/seccomp-istota.json
- apparmor=istota
- systempaths=unconfined
- no-new-privileges:true
cap_drop: [ALL]
cap_add: [CHOWN, FOWNER, SETUID, SETGID, SETPCAP, SYS_ADMIN]
read_only: true
cgroup: private

seccomp-istota.json is Docker's default profile plus the six calls bwrap needs to build a namespace (clone, clone3, mount, pivot_root, umount2, unshare), without the default's CAP_SYS_ADMIN rule, so bpf, keyctl, userfaultfd, perf_event_open and the rest of the default denylist stay refused for every task. apparmor-istota is Docker's docker-default plus mount (with no bind or move out of /proc or /sys and no sysfs mount) and pivot_root; it keeps docker-default's refusal of writes to /proc/sys and /proc/sysrq-trigger, which systempaths=unconfined would otherwise leave open to a root docker exec. provision.sh installs the profile and istota-stack up loads it before starting anything; if it does not load, the stack is not started.

The container starts in a short root phase that delegates its own cgroup to the daemon, so each task gets memory.max, pids.max and cpu.max of its own, gives up CAP_SYS_ADMIN straight after the remount that needs it, and then drops to uid 10001 with every capability set empty. docker compose exec does not inherit that drop, which is why the machine's istota command and istota-stack exec both run through istota-drop. If the sandbox cannot be built (a profile missing, a compose file without these lines), the container exits at boot and its log names the lines to add, rather than running tasks unconfined.

These settings are why the machine has to be dedicated to the install: systempaths=unconfined would let a uid-0 process in the container reach host sysctls if AppArmor were not loaded, and nothing in the container runs as uid 0 after the root phase.

Acting on the browser container's unhealthy verdict​

The browser container's healthcheck probes the liveness endpoint's deep tier, which asks whether the Chrome process is alive, whether Chrome's DevTools endpoint answers, and (since ISSUE-384) whether the API process can still drive the browser it is reporting on. restart: unless-stopped reacts to a process exiting, not to a failing healthcheck, so compose alone leaves a wedged container running.

A watchdog timer that provision.sh installs (istota-browser-watchdog.timer, enabled when provision.sh last ran with the browser profile on) reads the verdict every minute, restarts the container after a debounce, stops and alerts if the restarts start looping, and restarts it once a day. To read the verdict yourself, use istota-stack compose ps, or /health on port 9223, which reports the CDP heartbeat in cdp_healthy and cdp_consecutive_failures.

Credentials​

Each is a file under /srv/app/istota/secrets/, named for the variable the daemon reads it from, lowercased: claude_code_oauth_token, istota_provider_anthropic_api_key (the Claude Code CLI's API key under [brain.claude_code] auth = "api_key"; anthropic_api_key is still read for one release), istota_nextcloud_app_password, istota_web_oauth2_client_secret, istota_web_session_secret_key, istota_email_imap_password, istota_caldav_password, istota_developer_gitlab_token, istota_developer_github_token, istota_email_smtp_password, istota_sms_telnyx_api_key, istota_sms_telnyx_public_key, istota_sms_telnyx_messaging_profile_id, istota_google_workspace_client_secret, and one API key per arr app for the servarr skill (istota_servarr_sonarr_api_key, istota_servarr_radarr_api_key, istota_servarr_lidarr_api_key, istota_servarr_prowlarr_api_key), the three Twilio credentials (istota_sms_twilio_auth_token, istota_sms_twilio_api_key_sid, istota_sms_twilio_api_key_secret), the three WhatsApp Cloud API ones (istota_whatsapp_access_token, istota_whatsapp_app_secret, istota_whatsapp_verify_token), the built-in model providers' keys and extra headers (istota_provider_anthropic_api_key, istota_provider_anthropic_extra_headers, istota_provider_openrouter_api_key, istota_provider_openrouter_extra_headers, the headers as one JSON object), and for one release the native brain's old key and headers (istota_brain_native_api_key, istota_brain_native_extra_headers), still read as native's provider's. An empty file is a credential the install does not use; the SMTP password falls back to the IMAP one. Every installation credential has a file here; tests/test_installation_credentials.py fails when a new one is added without one.

The stack has no settings of its own for Nextcloud: there is no bundled one to configure.

Upload limits​

nginx is given a generous NGINX_CLIENT_MAX_BODY_SIZE (default 512M), so the binding limit on a chat attachment is the application's own [web.chat] max_attachment_mb — 25 MB unless you raise it in config.toml. A proxy in front of the stack needs a ceiling at least as large.

The web service also runs uvicorn without --timeout-graceful-shutdown, so a restart with a browser tab holding the chat room stream open waits out the stop timeout before the container is killed.

Signing in without Nextcloud​

Set [web] auth = ["email"] and [site] hostname to the public hostname in config.toml, and configure SMTP for email sign-in codes and password resets; istota setup writes email sign-in by default when there is no Nextcloud login to offer. Restart the stack after changing the config. See email login setup for the CLI bootstrap and recovery commands. These settings change authentication only; storage and Talk are separate (see Storage).

To migrate an existing installation, set auth = ["nextcloud", "email"], attach an email identity to each existing user, and inspect istota auth list. Once every user has an enabled identity and a working password or email-code path, change the value to email. Existing Nextcloud sessions then stop working. Dropping Nextcloud for storage, Talk and CalDAV is a separate change.

none is refused by the stack's web launcher. A loopback backend behind a public proxy is still public. Custom outer proxies must exclude /istota/auth/set-password, or omit query strings from access logs; the shipped nginx and uvicorn suppression cannot control an outer proxy. The shipped nginx also caps request bodies on /istota/login/email and /istota/auth/ at 32k, since those forms are posted without a session; an outer proxy should set a similar limit there rather than its general upload limit.