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.
- Built into Donezo:
signal, which you connect once. - Your servers: servers you added. Check tests one. A small tag shows which CLI has it.
- Add a server: enter a name, an address and an optional token. Test tries it without saving. Add tests first and writes nothing if the server refuses.
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.
| Variable | Default | When to set it |
|---|---|---|
ORCH_PORT | 8992 | Port 8992 is taken. |
CLAUDE_BIN | claude | The app cannot find your Claude Code CLI. |
ORCH_AGY_BIN | agy | The app cannot find your Antigravity CLI. |
ORCH_NVIM_BIN | empty (download) | The editor download fails, or you want your own nvim 0.12+. See below. |
ORCH_NVIM_MIRROR | GitHub | GitHub is blocked and you host the nvim release files yourself. |
ORCH_HOST | 127.0.0.1 | Only to reach it from another machine. Read the warning below. |
ORCH_CORS_ORIGINS | empty (off) | Only for a web app of your own that calls the API from a browser. |
ORCH_SUBAGENTS_MAX | 4 | Active sub-agents per director. |
ORCH_SUBTASK_MAX_ATTEMPTS | 3 | Failed verifications before a sub-agent's work is marked failed. |
ORCH_MAX_CONCURRENT | 3 | Background runs at the same time. |
CLAUDE_CODE_AUTO_COMPACT_WINDOW | 300000 | Claude 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_EFFORT | high | Effort for agents that do not set one. |
ORCH_PAIR_SIGNAL_CAP | 2 | Messages two agents may exchange per task. |
ORCH_PAIR_SIGNAL_WINDOW_MIN | 60 | Minutes of silence before that count resets. |
ORCH_MAX_RUNS_PER_DAY | 0 (off) | Daily run limit per agent. |
ORCH_DAILY_ALLOW_STEP | 10 | Runs added each time you press Allow +. |
ORCH_MAX_RUNS_PER_SESSION | 0 (off) | Total run limit per agent. |
ORCH_SESSION_TOKEN_BUDGET | 0 (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:
- No network, or GitHub is blocked: install Neovim 0.12 or newer yourself and set
ORCH_NVIM_BINto its path, or put the release files on a server of your own and setORCH_NVIM_MIRRORto that folder's URL. The hash is still checked. - It failed its integrity check: the file was damaged or changed on the way, and nothing was installed.
Press Try again. If it repeats, use
ORCH_NVIM_BIN. - It will not run on this machine or there is no build for it: use
ORCH_NVIM_BIN.
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
- From source: run
git pull, thenpip install -r requirements.txt, then restart. - Prebuilt: download the new zip and replace the folder, keeping your
.env.
See what changed in the changelog.
Troubleshooting
| What you see | What to do |
|---|---|
| The dashboard does not open, or the server says the port is in use | Set ORCH_PORT in .env and open that port instead. |
| Windows SmartScreen flags the download | The 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 version | Use Homebrew's python3.12, as in the macOS steps. |
An agent cannot find send_signal or spawn_subagent | Press Connect next to signal in Connections, then press reload on the card. |
| A CLI is not found | Set 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 reload | Press the reload button on the card's left edge. |
| A terminal says terminal opens when it finishes | That 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 workspace | Each field is required. New workspace on Home makes one if you have none. |
| A sub-agent card says no worktree | The 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 runs | Check whether the agent is paused, the workspace is suspended, or it is waiting for approval. See how to stop things. |
A message shows blocked | A 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 files | The read-only agent really changed files. Nothing was undone. Check them with git status. |
| The computer feels slow | Open 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.