Configuration#

Syndicate keeps its settings in one file, ~/.config/syndicate/config.json, and its state in ~/.local/state/syndicate. Configuration defines repository roots, worktree storage, agent executable paths and dashboard access. Both the CLI and the Host read the same file, and environment variables set on the service override it.

Before you start#

• Know the canonical absolute paths for your repositories and worktrees.
• Confirm those directories are private to the Syndicate user.
• Stop other syndicate commands that write configuration; a mutating command holds an exclusive lock on config.json while it runs.

Write the base configuration#

syndicate setup --non-interactive \
  --allowed-repository-root /srv/code/project \
  --max-concurrent-agents 3 \
  --managed-worktree-root "$HOME/.local/state/syndicate/worktrees"

setup never prompts. It probes the installed agent CLIs and records the absolute executable path it found for each one under agentPaths. The Host stays on loopback; see Browser access for the ways a browser reaches it.

--max-concurrent-agents accepts 1 to 64. --minimum-free-disk-bytes accepts a whole number of bytes.

Where Syndicate looks for an agent CLI#

The Host resolves each agent executable to an absolute path every time it probes or launches one, in this order:

1. The configured path — SYNDICATE_<AGENT>_PATH on the service, otherwise agentPaths.<agent> in config.json.
2. Each directory on PATH, in order.
3. ~/.local/bin, which is where the vendor installers write and which a service started at boot does not normally carry on PATH.

A configured path that contains a directory separator is treated as a path and must exist. If it does not, the agent is reported as not found with that path in the message; Syndicate never falls back to a different binary than the one you named. Because resolution happens at every probe, a CLI installed after the Host started is picked up without restarting the service.

Important: syndicate agent list and syndicate agent status do not read agentPaths from config.json. They honour SYNDICATE_<AGENT>_PATH from their own environment and otherwise search PATH and ~/.local/bin. An executable pinned only in config.json therefore governs what the Host launches and what the dashboard shows, while these two commands can name a different binary. Pin the path with the environment variable when you need every surface to agree.

Environment variables#

Set these in the user service unit so the Host uses them. A variable set only on the unit is not visible to a syndicate command you type in a shell, so export it in your shell too when you want syndicate agent list to resolve the same executables the Host does.

Session events and finished terminal-session rows are kept indefinitely on this release. Neither has a retention sweep, so plan disk for a store that only grows, and archive or replace the state directory when it becomes large. See Operations and upgrades.

Boundaries#

• Allowed repository roots limit what the Host will accept.
• Managed worktrees need a persistent local filesystem.
• Codex, Claude Code and PacketCode keep their credentials in their own stores. Syndicate records where each executable is, never how it authenticates.
• PacketCode must already be installed; Syndicate drives it, and does not install it.
• The execution Host stays on 127.0.0.1; browser exposure is configured separately.

Verify#

syndicate doctor --json
syndicate agent list
syndicate workspace list --json

Check that the configuration checks pass, paths are canonical and the Host control socket is ready. syndicate agent list names the executables that command resolved; when a path is pinned only in config.json, compare it with the path the dashboard reports for the same agent before trusting either as the one the Host will launch.

If it does not work#