Your first task

1. Create the agent home

Unpack your download into a permanent folder. Run these commands from that folder; Windows PowerShell requires the .\ executable prefix shown below.

.\zagent.exe init

./zagent init

2. Connect your model

Edit .env next to the executable:

PROVIDER=openai_compatible
BASE_URL=https://your-provider.example/v1
API_KEY=your-key-here
MODEL=your-model-id
VISION=false
AUDIO=false
PDF=false
VIDEO=false

Replace the example endpoint and model with actual values from your provider. Enable media only if that endpoint and model accept it. See providers for all wire formats.

Keep credentials in ZAGENT_API_KEY instead of .env when appropriate. Never paste them into this website.

3. Start with a narrow tool set

For a first evaluation, use an isolated folder containing non-sensitive example files. In config.json:

{
  "tools": { "enabled": ["view_file", "list_dir", "find_files"] },
  "permissions": { "run_command": "deny" }
}

This example limits the tools offered to the model. It is not OS-level isolation.

4. Check and run

.\zagent.exe doctor
.\zagent.exe --workspace C:\demo --session first -p "List the files and summarize what is here."

./zagent doctor
./zagent --workspace ~/demo --session first -p "List the files and summarize what is here."

doctor validates configuration and makes a small request to your configured endpoint. Model-provider charges may apply.

5. Choose an interface

zagent --session first --ui cli
zagent --session first --ui web
zagent --session first -p "Continue with a short summary."

These examples assume the executable folder is on your PATH. Otherwise use its full path, ./zagent, or .\zagent.exe.

While the agent works, type a note to steer its next request. /stop interrupts an ordinary task. /exit detaches an interface; /quit stops the engine process. Manual compaction currently has a cancellation limitation; see security and limitations.