Installation & updates

zagent is a single self-contained program. There is nothing to install besides the file itself: no additional language runtime for the engine. The terminal and web interfaces can start a local background engine process.

1. Download and check

Download the archive for your system from the downloads page and the SHA256SUMS.txt beside it.

Verify the download (the output must match the line for your archive in SHA256SUMS.txt):

Get-FileHash .\zagent-0.1.1-windows-amd64.zip -Algorithm SHA256        # Windows

sha256sum zagent-0.1.1-linux-amd64.tar.gz                              # Linux   (macOS: shasum -a 256 ...)

2. Unpack: the folder is the agent

Unpack the archive somewhere permanent, for example C:\Tools\zagent or ~/zagent. That folder is the agent's home: your settings, memory, skills, third-party tools and all sessions live next to the binary. To move or back up the agent, copy the folder. To use several independent agents, unpack several copies (or point one binary at different folders with --home DIR or the ZAGENT_HOME environment variable).

zagent/
  zagent(.exe)   GETTING_STARTED.txt  THIRD_PARTY_NOTICES.txt
  (created on first run)  .env  config.json  system_instruction.md  memory/  skills/  tools/  commands/  sessions/  scratchpad/

• Linux / macOS: run chmod +x zagent if needed. The macOS build is unsigned and not notarized. If macOS blocks it, verify the checksum and use the system’s approved application-opening workflow.
• Run from anywhere: add the folder to your PATH, or make a shortcut/alias. The home is found from the real location of the binary, so a symlink to it works too.

3. Create the home and configure the model

zagent init            # creates .env, config.json, system_instruction.md and the folders

Open .env and fill in four lines (see PROVIDERS.md for ready-made examples for each service):

PROVIDER=gemini                        # gemini | openai_compatible | anthropic | custom
BASE_URL=https://generativelanguage.googleapis.com
API_KEY=your-key-here
MODEL=your-model-id

Also set what the model can accept as input, so the agent never sends something the model would reject:

VISION=true      # images
AUDIO=false
PDF=false
VIDEO=false
CONTEXT_LIMIT=1000000     # the model's context window, in tokens
COMPACT_AT=80%            # summarise the conversation when it reaches this much of it

Keeping the key out of files: leave API_KEY= empty and set the environment variable ZAGENT_API_KEY instead (any .env setting can be given as ZAGENT_<NAME>). The variable wins over the file.

4. Check that it works

zagent doctor

It prints the settings it will use (including the exact request URL), lists the tools, and sends a one-word test request. Fix anything it reports before going further. Typical output ends with Connection: OK in 1.2s.

5. First tasks

cd path/to/your/project                          # the folder you are in is the agent's workspace
zagent --prompt "Summarise what this project does and list its main entry points."

The agent works, prints a short progress trail on stderr, and prints its final answer. Useful variations:

Shell commands are off until you turn them on. The default permissions.run_command is ask, but interactive approval is not implemented yet in any interface, so ask currently behaves like deny: the agent is told it may not run commands and works with the file tools only. When you trust a task (and understand that commands run with your user's permissions), allow them in config.json:

{ "permissions": { "run_command": "allow" } }

Use "deny" to make the refusal explicit. You can also remove the tool entirely with "tools": {"disabled": ["run_command", "terminal"]}.

Using the interfaces

• --ui web starts the agent as a background service, prints a link and opens your browser. The link contains a private access token; it only works on your own computer.
• --ui cli opens a full-screen terminal view of the same session.
• In both: type to send a message. While the agent is working, what you type becomes a note that is attached to the end of its next request, and a Stop control interrupts it. /help lists the slash commands.
• Closing a window never stops the agent. /exit (or Ctrl-C when idle) leaves the interface; the agent keeps working in the background. To end the background process type /quit. It also exits by itself after 30 idle minutes (service.idle_exit_minutes).

Updating

Replace the zagent binary with the new one. Your .env, config.json, sessions, memory, skills and tools are untouched. New releases may add config.json options with sensible defaults; see CHANGELOG.md and CONFIG.md. Nothing is migrated or rewritten automatically.

Uninstalling

Delete the folder. If a background service is still running, end it first: zagent --session NAME --ui cli, then /quit.

Troubleshooting

Updating and backing up

Stop the engine before updating. Back up the whole agent home, including configuration, memory, skills, tools, and sessions. Replace the executable with the new build for the same platform. Keep your existing home files; do not delete them as part of an update. Test a restored copy before relying on a backup.

Release verification

The checksums on the downloads page refer to the binary-only client packages published with this website. They differ from earlier developer archives. The engine source is not included.