Sessions & context

Home and workspace

The home stores settings, memory, skills, tools, and sessions. It defaults to the executable folder. Override it with --home or ZAGENT_HOME.

The workspace is the folder a task operates on. It defaults to your current directory. Override it with --workspace.

zagent --home /opt/agents/demo --workspace /srv/demo --session weekly -p "Prepare a draft report."

Separate homes are useful configuration boundaries. They do not isolate processes or credentials at the operating-system level.

Resume a conversation

zagent --session weekly -p "Summarize the outstanding work."
zagent --session weekly --ui web

A session reuses its saved history. A new prompt against a running session is queued into that engine. Use --new for an unrelated task.

Attach and detach

The terminal and browser interfaces attach to the local engine process. Closing an interface does not necessarily stop it. Use /exit to detach and /quit to request engine shutdown. service.idle_exit_minutes controls idle service exit.

Context compaction

The full transcript is retained on disk. The request context may be shortened through attachment pruning and model-written summaries. COMPACT_AT sets a token threshold. context.request_body_limit_mb limits encoded request size. Summary quality depends on the model, so keep critical requirements in task instructions and independently check results.

Attachments

zagent --session scan -p "Describe this document." --attach report.pdf

Set the corresponding .env capability before using images, audio, PDF, or video. File limits and provider support both apply. The browser can upload attachments into the scratchpad. Same-name uploads can overwrite previous paths after server restart in this preview; use unique filenames.

Background work and subagents

Command tools and external tools can leave background tasks. Task results can wake an idle agent. A subagent has a fresh conversation and reports back to its parent, with a read-only tool set by default.

Subagents share the workspace and normally the parent's configured model. They are not tenant isolation. The round limit is not a shared token or spending budget; parent usage totals do not preserve child totals across restart in v0.1.1.

Backup and recovery

Stop the engine and back up the entire home plus required workspace inputs. Preserve .env, config.json, memory, skills, tools, sessions, and attachment blobs. Keep backups access-controlled because they can contain sensitive data. Do not manually edit live session logs or delete lock files to force concurrent access.