Updates & on-site delivery

Stoa updates aren't pulled from a public package repository or downloaded automatically in the background. They're delivered intentionally, by your engineering partner, on a schedule that respects your environment. This page covers how that works for both internet-connected and locked-down sites.

Two delivery models

Internet-connected sites with the maintenance license

If your deployment can reach our staging infrastructure, and you've purchased the optional maintenance license, updates are staged remotely. Your engineering partner will:

1. Notify you that an update is available, with release notes.
2. Schedule a maintenance window with you.
3. Stage the new version on your host without disrupting the running platform.
4. At the agreed time, apply the update.
5. Run post-update health checks and confirm everything is green.

You should be on a call (or at least reachable) during the window itself.

Locked-down or air-gapped sites

If your deployment is on a network that can't (or by policy won't) reach the public internet, updates are delivered on-site. An engineer travels to your location, or coordinates with your infrastructure team, and hand-delivers the update on physical media (typically an encrypted, signed USB or removable drive). Then they:

1. Verify the media's signature against a known fingerprint before any data is touched.
2. Walk through the same staging and apply steps as above, with you in the room or on a call.
3. Run health checks and walk you through what's new.

Air-gapped delivery is the default for banks, hospitals, government departments, and other regulated environments. It's slower than remote staging, but you get a complete audit trail of every artifact that crossed your security boundary.

What an update includes

A typical update contains some combination of:

• Bug fixes for issues found since the last release.
• New features across the platform, user interface, agent runtime, KB pipeline, and admin tooling.
• Security patches for the platform and its dependencies. These are the highest priority and get scheduled faster than feature releases.
• Updated AI model artifacts if a new recommended local model has shipped.
• Documentation updates matching the new release.

Your engineering partner provides release notes for every update so you know what's changing before the maintenance window.

What to expect during an update window

A typical window looks like:

1. Pre-update backup. The engineer takes a fresh snapshot of the database and documents directory. This is your rollback safety net. See Backups.
2. Brief downtime. The platform is stopped while the update is applied. For most updates this is a few minutes; some updates that touch the database take longer.
3. Version bump and apply. The new platform image and any associated assets are put in place.
4. Restart and warm-up. Background services come up, models load, the cache warms.
5. Post-update health checks. Every internal service is verified green on the System status page. The engineer runs a sample chat, a sample KB query, and a quick admin action.
6. Hand-off. Your engineer walks you through any new admin features and confirms the window is closed.

TIP

Pick a low-traffic time for your update window. End of day, end of week, or a weekend is typical. Communicate the window to your users in advance so a chat that fails mid-conversation isn't a surprise.

Rolling back if something goes wrong

If health checks fail or a critical regression appears, the rollback path is:

1. Stop the platform.
2. Restore the pre-update backup taken at the start of the window.
3. Start the platform on the previous version.
4. Confirm health.
5. Open a ticket with your engineering partner so the regression can be reproduced and fixed.

Rollbacks are rare. Most updates apply cleanly, especially when the engineer is on the call.

How often updates land

Cadence varies by license and urgency.

• Security patches: as soon as they're ready, within days of the underlying fix.
• Bug fix releases: every few weeks.
• Feature releases: every one to two months.
• Major releases: less frequent, with longer release notes and a slightly longer window.

For air-gapped sites, cadence depends on how often your engineer can travel. Most air-gapped customers settle into a quarterly rhythm, with security patches landing out of cycle when needed.

Permissions and visibility

The currently installed version isn't surfaced anywhere in the admin UI today: your delivery engineer or engineering partner is the source of truth for what's running, and release notes are how you'll know what changed. Keep the release notes from each update alongside your own change records if your policy calls for a version history.

Next

• Backups for the pre-update snapshot discipline.
• System status for the post-update health verification.
• Installation for the initial delivery workflow your update process mirrors.