Donezo logoDonezo Download

Settings

What is on the Settings page, how to configure the server, and what to do when something goes wrong.

Settings sections

Open Settings in the sidebar.

Connections

Tool servers (MCP servers) for every agent on this machine, in every CLI installed here.

Media tools

Agents can edit video and audio by running commands such as ffmpeg in their own terminal. This page shows which of those commands are installed on the machine: ffmpeg, ffprobe and ImageMagick are the main ones; yt-dlp, SoX and ExifTool are optional. Nothing here ships with the app. If a main one is missing, a red dot appears on Settings. Install it, then press Re-check. You can ignore this page if your agents do not touch media.

Performance

CPU and memory for the computer, Donezo and this page, plus a table of each agent's processes. It also gives plain advice, such as closing terminals you are not using. Each open terminal is a whole CLI program, so they add up.

Removed agents

Unregister takes an agent off the canvas but keeps its runs, messages and transcript. This page deletes those for good, one at a time or with Delete all. What the agent sent, its playbook file in the project folder, and what you typed in the CLI's own history stay.

General

The theme: Auto follows your computer, or choose Light or Dark. The theme button at the bottom of the sidebar cycles through them.

The .env file

Put settings in a file named .env next to session_orchestrator.py (or next to agent-orch.exe), one NAME=value per line, then restart the server.

VariableDefaultWhen to set it
ORCH_PORT8992Port 8992 is taken.
CLAUDE_BINclaudeThe app cannot find your Claude Code CLI.
ORCH_AGY_BINagyThe app cannot find your Antigravity CLI.
ORCH_NVIM_BINempty (download)The editor download fails, or you want your own nvim 0.12+. See below.
ORCH_NVIM_MIRRORGitHubGitHub is blocked and you host the nvim release files yourself.
ORCH_HOST127.0.0.1Only to reach it from another machine. Read the warning below.
ORCH_CORS_ORIGINSempty (off)Only for a web app of your own that calls the API from a browser.
ORCH_SUBAGENTS_MAX4Active sub-agents per director.
ORCH_SUBTASK_MAX_ATTEMPTS3Failed verifications before a sub-agent's work is marked failed.
ORCH_MAX_CONCURRENT3Background runs at the same time.
CLAUDE_CODE_AUTO_COMPACT_WINDOW300000Claude agents compact their context at about this many tokens. Larger keeps more detail and costs more per call. Donezo leaves it unset if your Claude settings already have autoCompactWindow.
ORCH_DEFAULT_EFFORThighEffort for agents that do not set one.
ORCH_PAIR_SIGNAL_CAP2Messages two agents may exchange per task.
ORCH_PAIR_SIGNAL_WINDOW_MIN60Minutes of silence before that count resets.
ORCH_MAX_RUNS_PER_DAY0 (off)Daily run limit per agent.
ORCH_DAILY_ALLOW_STEP10Runs added each time you press Allow +.
ORCH_MAX_RUNS_PER_SESSION0 (off)Total run limit per agent.
ORCH_SESSION_TOKEN_BUDGET0 (off)Total token limit per agent.

Security warning

Agents run shell commands with permissions bypassed, and there is no API key. Anyone who can reach the dashboard can make your agents do anything on your computer. ORCH_HOST=0.0.0.0 hands that to everyone on your network.

By default the server listens on your own machine only and refuses requests from other websites. It prints a warning at startup if you open it up. Run it as your own user, never as root, and give agents only projects you are happy for them to change.

If the editor will not download

The first time you open the editor, the app downloads Neovim 0.12.6 from GitHub into .session_orch_db/nvim in your home folder and checks it against a fixed hash. A Neovim already on your system is not used, because older versions break the bundled plugins. If the card says it could not start, try one of these:

With tmux installed, editor cards run on a private tmux server, separate from your own sessions. List them with tmux -L orch-nvim ls.

Keep it running

This is optional. Replace the paths with where you unzipped or cloned it.

Windows: Task Scheduler
$exe = "$HOME\agent-orch-windows-x64\agent-orch.exe"
Register-ScheduledTask -TaskName "Donezo" `
  -Action  (New-ScheduledTaskAction -Execute $exe -WorkingDirectory (Split-Path $exe)) `
  -Trigger (New-ScheduledTaskTrigger -AtLogOn) `
  -Settings (New-ScheduledTaskSettingsSet -StartWhenAvailable `
               -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1))

Remove it with Unregister-ScheduledTask -TaskName "Donezo".

macOS: launchd
cat > ~/Library/LaunchAgents/com.donezo.plist <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.donezo</string>
  <key>ProgramArguments</key><array>
    <string>$HOME/donezo/.venv/bin/python</string>
    <string>$HOME/donezo/session_orchestrator.py</string>
    <string>serve</string>
  </array>
  <key>WorkingDirectory</key><string>$HOME/donezo</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>$HOME/Library/Logs/donezo.log</string>
  <key>StandardErrorPath</key><string>$HOME/Library/Logs/donezo.err</string>
</dict></plist>
PLIST

launchctl load -w ~/Library/LaunchAgents/com.donezo.plist

Stop it with launchctl unload -w ~/Library/LaunchAgents/com.donezo.plist.

Linux: systemd user service
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/donezo.service <<'UNIT'
[Unit]
Description=Donezo
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/donezo
ExecStart=%h/donezo/.venv/bin/python %h/donezo/session_orchestrator.py serve
Environment=PYTHONUNBUFFERED=1
Restart=on-failure
RestartSec=3
TimeoutStopSec=15

[Install]
WantedBy=default.target
UNIT

systemctl --user daemon-reload
systemctl --user enable --now donezo
loginctl enable-linger "$USER"     # start at boot, not only when you log in

Logs: journalctl --user -u donezo -f.

Updating

See what changed in the changelog.

Troubleshooting

What you seeWhat to do
The dashboard does not open, or the server says the port is in useSet ORCH_PORT in .env and open that port instead.
Windows SmartScreen flags the downloadThe builds are not code-signed. Compare the hash with SHA256SUMS.txt from the release, then run Unblock-File on the zip.
macOS: the install fails on a Python versionUse Homebrew's python3.12, as in the macOS steps.
An agent cannot find send_signal or spawn_subagentPress Connect next to signal in Connections, then press reload on the card.
A CLI is not foundSet CLAUDE_BIN or ORCH_AGY_BIN to its full path. Also check you are logged in to that CLI.
A terminal shows disconnected — press 🔄 to reloadPress the reload button on the card's left edge.
A terminal says terminal opens when it finishesThat is normal. A background run is using the conversation; the terminal opens by itself when it ends.
Create agent says Pick a model or Pick a workspaceEach field is required. New workspace on Home makes one if you have none.
A sub-agent card says no worktreeThe director's folder is not a git repository, so the sub-agent shared it. Run git init and make a first commit, or point the director at a repository.
A message sits there and nothing runsCheck whether the agent is paused, the workspace is suspended, or it is waiting for approval. See how to stop things.
A message shows blockedA run or token limit was reached. Press Allow + in the agent's panel if it is the daily limit, or raise the limit in .env.
Reflect fails with a read-only sub-agent changed filesThe read-only agent really changed files. Nothing was undone. Check them with git status.
The computer feels slowOpen Performance. It names what is using the machine.

The server's health and API docs are at /health and /docs on the dashboard's address. If you are still stuck, report a bug.