Updates and the UI service

This page shows how to update Istok, how to keep the web UI always available as a background service on Linux and macOS, and how the two work together.

Update Istok

istok update

Istok checks for a newer stable release, shows the current and target version, the download size and the release notes, and asks before installing. Answer y to continue.

• istok update --check only checks and changes nothing.
• istok update --yes installs without asking, for scripts.

During the update Istok:

1. downloads the release and verifies its signature;
2. makes a temporary backup of the database;
3. replaces the binary and applies database changes for the new version;
4. if that step fails, puts back the old binary and the database backup and reports the error.

The temporary backup is removed after a successful update. It covers only the database, not the code indexes or run artifacts. For your own backups, see Configuration.

If you use a custom database, pass it so the right file is backed up and migrated: istok update --database /path/to/istok.db, or set ISTOK_DATABASE.

A binary built from source cannot update itself. istok update says so and explains how to install an official release.

Agents after an update

Your agent starts istok mcp as its own process. A session that was already open keeps the old process until the agent restarts its MCP servers, so start a new session after updating.

Run the UI as a service

You can keep the UI running in the background, always at the same address. On Linux this uses a systemd user service, on macOS a launchd agent:

istok ui service install

This creates the service, enables it and starts it. No sudo is needed. The service runs the istok binary you used for install, on http://127.0.0.1:7700, and starts again after a crash or a reboot.

On macOS the UI writes its log to ~/Library/Logs/istok/ui.log. On Linux, read it with journalctl --user -u istok-ui.

To use another port or database, pass them to install:

istok ui service install --port 7800 --database /path/to/istok.db

A service does not see your shell’s environment, so the database path you give (or ISTOK_DATABASE at install time) is written into the service file. Run install again whenever you want to change these; it updates the file and restarts the service. The file is regenerated each time, so do not edit it by hand.

Manage it with:

istok ui service status
istok ui service restart
istok ui service stop
istok ui service start
istok ui service uninstall

uninstall stops and disables the service and deletes its file.

On macOS, stop unloads the agent, because launchd would otherwise start it again right away. It loads again on start or at your next login.

Keep it running after logout (Linux)

systemd stops user services when you log out. To keep the UI running, enable lingering for your user:

loginctl enable-linger

On macOS the agent belongs to your login session: it starts when you log in and stops when you log out.

Updates and the service

After a successful update, Istok restarts the UI service by itself when all of these are true:

• the service is installed;
• it is running;
• it runs the binary that was just updated.

You then see Restarted the web UI service on the new binary. A service that runs a different istok binary is left alone.

If the restart fails, the update still counts as successful and Istok prints a warning. Restart the service yourself:

istok ui service restart

If you installed the service from one binary and later moved to another, for example from a source build to the installer, run istok ui service install with the new binary so the service follows it.

All flags are in the istok ui reference.