Continuous execution
Run recoverable conversations, host persistent work, and attach clients with zot continuous.
zot continuous is zot's experimental persistent execution layer. It records model requests and tool calls before and after execution so interrupted work can recover from its last committed boundary. Ordinary interactive, print, JSON, and RPC workflows are unchanged.
Use it when a conversation should outlive its terminal, multiple clients should share the same history, or a job needs explicit recovery after a restart. Unlike ordinary session transcripts, the continuous store is the authority for queued prompts, execution state, approvals, and results.
Run without a daemon
zot continuous run "summarize the README" --store ./continuous-store --tools read,glob
zot continuous run "now list every TODO" --store ./continuous-store --tools read,glob
zot continuous run --resume --store ./continuous-store --tools read,globrun submits a prompt to the workspace's root conversation, executes its work, and prints the final answer. Reusing the store and workspace continues the same conversation. --resume continues interrupted work without submitting another prompt. Use --workspace <id> to select an explicit workspace identity and --json to stream JSON-line events.
Ordinary engine flags such as --provider, --model, --reasoning, --tools, --cwd, and --ext configure execution. Provider credentials are required for model requests, just as in ordinary zot. Session flags such as --continue, --session, and --session-name (-s), and mode flags such as --print, do not apply here. Readable local session aliases do not name continuous conversations. Use the host's conversation title controls instead.
For integrations that may retry a submission, supply a stable --request-id:
zot continuous run "review the latest changes" --store ./continuous-store --workspace main --request-id review-001 --tools read,globRetrying with the same request ID returns the original submission instead of admitting another prompt while its deduplication record is retained. Use a new ID for new work. Deduplication does not make arbitrary tool effects idempotent.
Host work independently of clients
Start the host in one terminal:
zot continuous serve --store ./continuous-store --tools read,globSubmit from another terminal:
zot continuous attach "summarize the README" --socket ./continuous-store/host.sock --workspace main
zot continuous attach --follow --socket ./continuous-store/host.sock --workspace mainserve owns the store, recovers interrupted runs according to policy, and executes queued work across conversations. It holds the provider credentials and tool configuration. attach connects to the host, submits an optional prompt, waits for its answer, and exits. --follow keeps streaming committed entries until interrupted. --json emits JSON-line output.
Closing or interrupting a client only detaches it, it does not cancel admitted host work. Interrupting the host stops serving and leaves interrupted work recoverable.
For local stores, the default endpoint is <store>/host.sock. PostgreSQL hosts use <state-dir>/host.sock. It is a mode 0600 Unix socket on macOS and Linux. On Windows, that path identifies a private named pipe derived from the absolute path. The same --socket syntax works on both. Use --socket <path> on serve to choose a different endpoint.
Attach the interactive TUI
zot --continuous ./continuous-store/host.sock --continuous-workspace mainThe status bar identifies the attached host. Prompts go to the host, and committed history, partial assistant text, tool progress, and waiting states appear in the TUI. Multiple views of the same workspace receive each other's updates even while idle. Closing the TUI detaches without cancelling host work.
The host store replaces local session persistence. New workspace roots use the host's provider, model, and reasoning defaults. Explicit client --provider, --model, or --reasoning selections can configure a new root, but opening an existing root does not replace its configuration. The CLI host routes each conversation to its saved provider and model using credentials available on the host.
A dropped watch reloads committed history and resumes automatically. New TUI prompts wait until the history snapshot and replacement watch are restored, so a fast answer is not mistaken for historical context. A disconnected host connection is not automatically redialed, reconnect the TUI to resume. The initial view loads the newest history page, not necessarily the entire conversation.
Enable /settings > **show reasoning** or pass --show-reasoning on the attached TUI to show readable reasoning separately from answer text. The host commits a rolling live suffix of at most 32 KiB at the partial-stream flush cadence, not per provider token. Joining or reconnecting restores the live suffix without duplicating overlapping chunks. Completed assistant messages retain up to 8,192 Unicode characters of display-only reasoning, so a compact tail remains before each reply and is restored with history. Disabling the display hides saved tails without deleting them. These tails are not model context and never display signatures or encrypted payloads.
Hosts with partial streaming enabled request readable summaries where supported, without changing reasoning effort. Older hosts may omit live reasoning or saved tails. Both host and client need builds with reasoning-display support for the complete behavior. As with other session content, historical store commits may retain readable reasoning after live partial records are removed.
Go integrations using AttachedDriver replay missed committed tool results and assistant messages before reporting completion, even if the submission settled while its watch was disconnected. If those commits are no longer retained, the driver restores a fresh transcript snapshot instead of replaying the individual events.
Compaction belongs to the host. Local /compact is unavailable while attached, manual compaction uses the host protocol's conversation.compact method. Attached /swarm agents run as owned conversations on the host rather than local agent subprocesses.
Hosts load $ZOT_HOME/COMPACT.md and repeatable --append-compaction-prompt values when configured. A nonblank file replaces the built-in summary template for manual and automatic compaction, including its format requirements. Missing or blank files retain the default. Flag values are appended to the selected template in command-line order, followed by any per-request conversation.compact instructions. They do not come from the attached client's ordinary system prompt. Reconfigure the host after changing the file.
The CLI host also reads compaction_mode from its own $ZOT_HOME/config.json at startup. side (default) keeps separate summarization. Set it to in_place and restart the host to preserve the selected conversation model's system prompt, tool definitions, reasoning settings, and structured message prefix for summarization. This is not an attached-client setting or a per-request conversation.compact field. Both modes use the configured custom summary guidance. See Sessions for cache limitations, fallback behavior, and provider-hosted tool caveats.
Switch providers and models
Use the host protocol's conversation.configure method to change provider and model within the same durable conversation. No host restart or new conversation is needed. History and the saved selection remain in the store. Subsequent model requests use the current selection, while a request already in flight finishes with its original client.
Credentials stay on the host. Use zot's /login there, set the provider's API key environment variable before starting the host, or configure a local/custom connection. Host --api-key, --base-url, and inference TLS overrides stay scoped to the startup provider. Other providers resolve their own connection settings. Unknown providers, invalid built-in model IDs, and unavailable credentials are rejected before saving rather than silently substituted. Custom/local endpoints retain open-catalog model support.
New owned subagents inherit their parent's selection when created. Existing children keep their own configuration. Switching providers does not load different extensions or change host filesystem permissions. Automatic compaction uses the selected model's catalog context window. An unknown context window disables automatic compaction.
Clients can check capabilities.providers and request model.list with available: true to list the host's available models across providers. Entries include a provider alongside the model ID. Listing models does not execute stored API key commands and is not a guarantee of upstream account access. Older hosts retain single-provider model lists. SDK hosts control routing through Engine.Build and can opt into listing and validation through HostServer.AvailableModels and HostServer.ValidateConfig.
Hosts apply disabled_providers and hide_speculative_models from the host's config.json to available-model listings. Disabled providers are also rejected when routing a conversation, including keyless or inherited host connections. Hiding speculative entries does not prevent explicit selection. Restart the host after changing provider policy to replace existing clients.
Send files and images
CLI clients can repeat --file:
zot continuous attach "review these files" --socket ./continuous-store/host.sock --workspace main --file ./notes.txt --file ./screenshot.pngThe TUI can send explicitly selected files and clipboard images. Select files with @ or !@, or drag them into the editor. Unlike local chat, where @ inserts a path, both forms send file content while attached, including in attached Swarm editors. Files are captured on submission before queueing. The client reads them and transfers their bytes, so the host does not need access to the client's filesystem. Attachments provide prompt context, not workspace uploads. Directory references and ordinary paths in prose do not transfer directory trees or implicitly read files.
A submission accepts up to 16 attachments and 1 MiB of combined decoded file and image bytes. Supported content is UTF-8 text plus PNG, JPEG, GIF, and WebP images. Unsupported binary files and mismatched image types are rejected. The selected model must support vision to interpret images. Attachment-aware clients refuse transfers to older hosts that do not advertise support.
Recovery and interruption
Inspect interrupted work while the host is stopped:
zot continuous recover --dry-run --store ./continuous-store
zot continuous run --resume --store ./continuous-store --tools read,globRecovery follows each tool's stored replay contract and rechecks authorization. Read-only tools such as read and glob can be replayed. Unsafe tools such as bash, write, and edit are not blindly repeated after an unknown outcome. Idempotent tools require receiver-enforced operation keys, and reconcilable tools must establish whether an effect completed before execution can resume.
The scheduler collects finished invocations and checks for follow-up task phases before reporting idle. Recovery does not stop between committed phases just because a handler finished. Work waiting for approval or blocked on an unresolved dependency still needs that condition resolved before it can continue.
Choose startup recovery policy on the host:
A model request may be sent again after interruption, and the provider may have charged for the earlier attempt. An unsafe tool may have acted before its result was committed. Inspect the actual files or external service before deciding what to do next.
Nested tool calls
Tools that call other tools, such as codemode scripts and extension call_tool requests, get the same durability as model tool calls. Each nested call is recorded as its own task owned by the calling tool, with its own intent, approval, replay policy, and committed result. Nested calls pass the conversation's allowlist, extension hooks, and host guard, and each receives its own call identity and operation key.
When an interrupted parent replays, completed nested calls return their stored result instead of running again. Nested calls are matched by key. Calls without an explicit key are numbered in call order, so a parent that issues nested calls concurrently or in a different order on replay should pass explicit keys. Reusing a key with a different tool or different arguments is refused and executes nothing.
Recovery previews list nested calls under their parent. Aborting a parent aborts its nested calls first and never overwrites a nested call's recorded result.
Nested calls can require approval like model calls. The approval names the parent tool and survives restarts. When every parent above the waiting call replays safely, the execution step returns as it does for a top-level approval, and the decision resumes the same nested call. A parent whose replay policy is never or reconcile keeps waiting for the decision instead.
Nested results are data for the calling tool and are limited to 256 KiB. They never appear in the model transcript. Control results, such as handoff or ending the run, only take effect when the model makes the call. A nested handoff returns its text to the caller without resetting the context. Nested progress appears in the parent's tool panel, and nested usage is recorded separately. Nesting is limited to four calls in a chain, including the original call, and nested calls cannot run as background work.
Inspect work and decide approvals
Store-management commands operate without provider credentials. They acquire the store's exclusive writer lock, so stop serve or any active run before using them against that store. Connected integrations can inspect a live host through its protocol instead.
zot continuous status --store ./continuous-store
zot continuous conversations --store ./continuous-store --limit 100
zot continuous tasks <conversation-id> --store ./continuous-store
zot continuous inspect <task-id> --store ./continuous-store
zot continuous usage <conversation-id> --store ./continuous-store
zot continuous approvals <conversation-id> --store ./continuous-store
zot continuous decide <approval-id> --allow --scope call --reason "reviewed" --store ./continuous-store
zot continuous abort <conversation-id> --store ./continuous-storeUse IDs returned by the listings, not the workspace name. Pending approvals survive restarts. decide records an allow or deny decision, and the next execution step continues the parked run. abort records abort intent rather than promising to undo an effect. Use --include-background when aborting a task tree should include background work.
Status and conversation listings emit JSON. --after <id> continues a paginated listing. search, budget, prompts, outbox, and retain provide additional inspection and management, see zot continuous --help. Retention removes auxiliary records, it does not physically erase journal history or reclaim its log bytes.
Choose a store backend
The journal backend is the default. Choose SQLite when creating a store:
zot continuous serve --store ./sqlite-store --backend sqlite --tools read,globThe journal and SQLite backends use local exclusive writer fencing and keep committed history. SQLite runs through an embedded WebAssembly runtime, with no system SQLite library or C toolchain requirement. Existing local stores are detected from their files. For local stores, --backend is accepted by run, serve, and import, and must match an existing store. PostgreSQL is an explicit remote backend, described below.
Strict durability is the default for writes. The journal backend requires explicit --durability process on Windows, there is no automatic downgrade:
zot continuous serve --store ./continuous-store --durability process --tools read,globProcess durability is not a promise that the newest acknowledged writes survive power loss. Use local filesystems, network filesystems are unsupported. Keep the store private, it contains conversation and tool data.
PostgreSQL and Neon
Continuous execution can store its history and execution state in an external PostgreSQL 15 to 18 server. zot uses a pure Go driver, with no native PostgreSQL client library requirement. It does not provision a database or run PostgreSQL for you.
Save one connection string in a private UTF-8 file, outside the store and source control. On Unix, it must be a regular, non-symlink file owned by your user with no group or other permissions, for example chmod 600 ./zot-postgres.dsn. On Windows, it must be owned by your user with an access list granting only that user and SYSTEM. Remote TCP connections require sslmode=verify-full, with certificate and hostname verification. sslmode=require alone is not accepted. Plaintext is allowed only for numeric loopback addresses or Unix-domain sockets, not the hostname localhost.
zot continuous serve --backend postgres --store-name main --postgres-dsn-file ./zot-postgres.dsn --state-dir ./continuous-host --tools read,glob--store-name selects a logical store in the database. It is case-sensitive, at most 128 characters, starts with an ASCII letter or digit, and otherwise permits letters, digits, dots, underscores, and hyphens. --workspace still selects a root conversation inside that store. Do not combine PostgreSQL with --store, which remains a local directory.
run with a prompt, serve, and import create the logical store if absent. Other commands, including run --resume, require it to exist. Inspection and administration commands still acquire exclusive writer ownership, so stop the host first or inspect it through the host protocol. Only strict durability is supported, --durability process is refused. PostgreSQL is not a multi-writer backend.
zot continuous status --backend postgres --store-name main --postgres-dsn-file ./zot-postgres.dsn
zot continuous check-state --backend postgres --store-name main --postgres-dsn-file ./zot-postgres.dsn
zot continuous run "summarize the README" --backend postgres --store-name main --postgres-dsn-file ./zot-postgres.dsn --tools read,globThe local state directory contains state.lock, store.json, host.sock, and, when generated for browser access, web-token. Use a private local filesystem directory. It is bound to the database store's UUID and cannot be reused for another store. It is not a copy of the database history. CLI, TUI, and browser clients still connect to the host, never directly to PostgreSQL:
zot continuous attach "summarize the README" --socket ./continuous-host/host.sock --workspace main
zot --continuous ./continuous-host/host.sock --continuous-workspace mainDatabase credentials and provider credentials stay on the host. An explicit DSN file that fails validation is an error, not a reason to fall back to the environment. zot creates its zot_continuous schema and tables when permitted, but never creates databases, roles, grants, or extensions. Initial schema creation requires database CREATE permission. Logical store names are not authorization boundaries against a role that can modify the tables.
For Neon, use the copied connection string with sslmode=verify-full. A Neon ep-...-pooler hostname is automatically routed to its direct counterpart, with TLS verifying the direct hostname. Credentials and other connection settings are preserved, and the DSN file is not edited. The direct endpoint must be reachable. This is direct routing, not support for transaction pooling. Other proxy hostnames are not rewritten.
Neon and some other managed services report fsync=off because durability comes from replicated remote storage. Those servers require an explicit opt-in:
zot continuous serve --backend postgres --store-name main --postgres-dsn-file ./zot-postgres.dsn --state-dir ./continuous-host --postgres-trust-remote-durability --web 127.0.0.1:7787 --web-origin https://web.zot.sh --tools read,globThe writer lock requires a persistent session. Use a direct connection or a session-affine proxy, not transaction or statement pooling. A lost database session, heartbeat failure, operation timeout, or commit failure stops the store and host execution. Neon compute suspension can drop that session. There is no automatic reconnect or takeover. A commit whose reply was lost may already be durable, zot reports an unknown outcome and does not retry it. Reopen explicitly and use recovery rather than repeating external effects blindly. After a network partition, stop or fence the old host and its tool processes before starting a replacement.
Use PostgreSQL or managed-service backup tooling for this backend. The journal-only backup, restore, verify, format, and migrate commands do not accept PostgreSQL. A complete database backup must preserve the schema, store UUIDs, counters, commits, and all record versions. Keep host configuration and local state backed up separately. Restore into an isolated database, run check-state, and inspect interrupted external effects before executing recovered work.
Back up, restore, and transfer history
The backup CLI is journal-only. Stop the writer before backing up:
zot continuous backup ./history.zotbackup --store ./continuous-store
zot continuous verify-backup ./history.zotbackup
zot continuous restore ./history.zotbackup --store ./restored-store
zot continuous verify --store ./restored-storeBackups preserve the complete committed journal prefix, not just a transcript projection. Archives must be outside the source store and must not already exist. Restore requires a new directory. Destination parents must exist. Archives are private data, not encrypted or authenticated packages, and referenced external artifacts are not bundled. Interrupted processes may leave incomplete destinations, verify them before use.
On Windows, add --durability process to journal backup and restore. verify and verify-backup are read-only and reject --durability.
For an open store, Go integrations can call (*journal.Store).Backup(ctx, archive, opts) or (*sqlite.Store).Backup(ctx, destination) without stopping the writer. SQLite's online backup creates a consistent database snapshot at a new filesystem path, not a SQLite URI. It reserves a mode 0600 file before copying and refuses existing destinations. These APIs do not add SQLite support to the backup CLI. Never copy a live SQLite database file as a substitute for an online backup.
Import and export bridge ordinary session transcripts:
zot continuous import ./old-session.jsonl --store ./continuous-store
zot continuous export <conversation-id> --store ./continuous-store --format session --output ./projection.zotsessionImport is explicit and bounded to 4 MiB and 10000 rows. Export is a snapshot-consistent projection, not a full store backup. Original session files and exported projections are not recovery authorities after import.
Remote access and authorization
A local socket without a token file grants admin access to connected clients. Restrict access to trusted processes. Raw TCP listeners (--listen) require a token file, and non-loopback listeners also require TLS:
zot continuous serve --store ./continuous-store --listen 0.0.0.0:7443 --token-file ./host-tokens.txt --tls-cert ./server.pem --tls-key ./server-key.pem --tools read,glob
zot continuous attach "summarize the README" --address zot.example.com:7443 --tls-ca ./ca.pem --token-file ./client-token.txt --workspace mainThe host token file contains one <token> <role> pair per line. Roles are read, submit, approve, and admin. Tokens must be at least 16 characters, use randomly generated secrets rather than example values. On Unix, the token file must not be accessible to group or other users. A client token file supplies its token as the first whitespace-separated value.
TLS uses a minimum of version 1.3. --tls-client-ca on the host optionally requires client certificates in addition to tokens. Loopback TCP may be plaintext, but still requires tokens. Do not expose an unauthenticated endpoint or treat a workspace ID as an authorization boundary.
Browser access over WebSocket
--web adds a WebSocket endpoint alongside the local socket or raw TCP listener:
zot continuous serve --store ./continuous-store --web 127.0.0.1:7787 --web-origin https://app.example --tools read,globFor local plaintext access, browser clients connect to ws://127.0.0.1:7787. HTTPS applications should use wss:// through TLS or a tunnel to avoid mixed-content restrictions. Clients send one protocol frame per text message. Each frame is a single-line JSON object without a trailing newline. The first request must be hello with the token in params.token. Requests, responses, watches, and roles are the same as on the socket. attach and the interactive TUI still use the local socket or raw TCP transport, not a WebSocket URL.
The WebSocket endpoint always requires a token. With --token-file, it uses the configured tokens and roles. Otherwise the host generates an admin token and stores it in <store>/web-token for local backends or <state-dir>/web-token for PostgreSQL (mode 0600 on Unix), reusing it across restarts. Startup logs show only its path. Read the file locally to retrieve the token, keep it private, and delete it before restarting the host to rotate it. Enabling --web does not change the local socket's authentication.
Repeat --web-origin to allow multiple browser origins. When set, requests with a missing or unlisted Origin are rejected. This is defense in depth, not authentication, because non-browser clients can forge the header. The token remains the access check.
A non-loopback --web address requires --tls-cert and --tls-key and serves wss://. For remote access, another option is a loopback endpoint behind a TLS tunnel:
tailscale serve --bg --https=443 http://127.0.0.1:7787Alternatively, use cloudflared tunnel --url http://127.0.0.1:7787. Connect through the tunnel with wss:// and allow the browser application's origin, not necessarily the tunnel host. Token authentication is still required.
Inbound text messages are limited to 1 MiB of encoded JSON, including attachment data and protocol fields. Binary and unmasked client frames are rejected. WebSocket extensions and subprotocols are not supported. Go hosts can expose the same transport with HostServer.WebSocketHandler.
Browser session settings and subagents
The zot browser client connects to the WebSocket endpoint above. Its source and setup guide are at https://github.com/patriceckhart/zot-web-ui. Click the model in the chat header to open session settings. With an updated host, the model picker lists models across providers configured on the host. Rows show the provider, and search accepts provider names and model IDs.
Selecting a model closes only the dropdown. Click the selected model to reopen it. Session settings remain open so you can adjust reasoning and instructions, then click Save to apply the provider and model together. Credential or selection errors leave the previous saved configuration intact. The browser does not provide provider login flows.
Cross-provider selection requires both an updated browser client and an updated host binary. Rebuild or upgrade and restart an older continuous host once to enable this capability. After that, switching providers does not require restarting it. An updated client connected to an older host keeps the single-provider picker.
The sidebar nests owned subagents under the conversation that created them, including deeper levels. Use the arrow beside a parent to collapse or expand its children. Branches start expanded, and expansion state lasts until reload or disconnect. Click a child to open its transcript, with model and activity indicators on each row. Unnamed children appear as subagent <first eight ID characters>.
The conversation list refreshes every 15 seconds. Search results stay flat so matching children remain accessible even when a parent is collapsed. Children whose parent is absent from the loaded list appear at the top level. Forks stay top-level. This display uses existing ownership metadata, requires no host configuration changes, and does not change the TUI dashboard.
Conversation titles
Conversations have an optional persisted title alongside their stable id. Titles work with the file journal, SQLite, and PostgreSQL backends, survive host restarts, and are shared between clients. Existing conversations remain untitled until renamed, with no schema migration. New roots, forks, and owned conversations start untitled.
In the updated browser client, right-click a conversation and choose Rename. Press Enter or click the save button to persist it, or Escape or cancel to discard the edit. Reset name clears the title. Saving requires an updated host and a submit, approve, or admin token. Errors remain visible instead of silently saving only in the browser. Older browser-only aliases are not automatically imported into the host.
Integrations call conversation.rename with {id, expected_revision, title} and receive the updated conversation. Use the conversation's revision from a snapshot or list, not the global store revision. A stale revision returns conflict. Titles are trimmed, limited to 120 Unicode characters, and must not contain control characters. An explicit empty string clears the title, a missing or null title is rejected.
Renaming changes display metadata only. IDs, workspace identity, transcript, provider session, and configuration stay unchanged, and a conversation can be renamed while work is running. Lists and snapshots include the title. View watches publish a metadata put containing {title}, which older clients can ignore. The open browser chat receives live title changes, while the sidebar refreshes on its 15-second interval. Titles are not added to model prompts or legacy session exports.
Repository-scoped workers
zot continuous worker --root project=./project --root library=./library --ledger ./worker-ledger.jsonl --environment desktopworker serves the remote tool protocol as newline-delimited JSON on stdin/stdout. It exposes read, write, edit, glob, and bash. Each tool call carries {repo, args}, where repo names a shared root and args contains the ordinary tool arguments. Unknown repositories are refused. Optional --token requires a matching hello handshake. --ledger persists operation lookup state across restarts.
This is a worker endpoint for a host integration, not a model-running daemon or automatic worker discovery. Go hosts can connect through WorkerClient and register RemoteTool instances. A lost connection leaves an unknown outcome until lookup or reconciliation establishes what happened. The reference worker does not schedule work across machines.
EOF or interruption closes the worker's streams and stops serving. File tools check paths against the selected root. Bash jail checks are best-effort accident prevention, not a security boundary. Only connect trusted hosts, and protect any relay or network transport separately.