Install Syndicate on Linux#

The supported release path is the immutable, signed Linux release asset.

Before you start#

Linux x64 or arm64.
A normal unprivileged user with a writable home directory.
Git and at least one supported coding-agent CLI.
Provider login completed through that CLI.
curl and the system tools required by the release installer.

Install the current stable release#

curl --proto '=https' --tlsv1.2 -fsSL \
  https://github.com/packetloss404/syndicate-releases/releases/download/v0.2.1/install.sh \
  | bash -s -- --version v0.2.1

For stronger review, download the exact installer and signed checksum assets, verify them, inspect the script, then run it locally. The installer installs versioned files as the current user and does not authenticate coding agents.

Each version is installed under PREFIX/versions/<version>, and PREFIX/current is switched to it only after the tree is verified. The default prefix is ~/.local/share/syndicate, and ~/.local/bin/syndicate links to the launcher inside current.

Useful installer options:

Option	Effect
`--version VERSION`	Install a specific release tag.
`--prefix PATH`	Install root; default `~/.local/share/syndicate`.
`--dry-run`	Print the planned actions without downloading or writing.
`--no-service`	Install the files but do not write or enable a user service.
`--defer-activation`	Write the user services but leave them stopped.
`--enable-linger`	Keep the user services running after logout.
`--uninstall`	Remove the user services and the selected prefix.

Configure the installation#

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

Start the user services with the installed service command appropriate to the host, then run diagnostics. See Configuration for executable paths, retention and dashboard access.

Verify#

syndicate version
syndicate doctor
syndicate host status
syndicate agent status all

Installation is ready when Doctor passes, the Host reports running and at least one installed agent reports a usable local state. Provider authentication may still require the provider CLI's own login command.

Upgrade#

Run the same installer with the new --version. The installer replaces the current link, so:

~/.local/bin/syndicate and the user services follow the new version.
Repositories, worktrees and the Syndicate state directory are untouched.

Restart the Host and terminal-host services after the upgrade, then re-run the verification commands above. If you reach the dashboard from another machine, re-establish the SSH tunnel afterwards. See Browser access.

Uninstall#

bash install.sh --uninstall --prefix "$HOME/.local/share/syndicate"

Uninstall disables and removes the Syndicate and terminal-host user services — including the legacy host service name, if an older install left one — removes the prefix, and removes ~/.local/bin/syndicate only when that link resolves into the prefix being removed. Repositories, worktrees and the Syndicate state directory outside the prefix are left in place; remove them yourself once you no longer need the session history.

If it does not work#

Symptom	Check	Recovery
`syndicate` is not found after install	Whether `~/.local/bin` is on `PATH`	Add it to the login shell; the installer warns instead of editing a shell profile
An agent CLI installed after the service started reports as missing	`syndicate agent list` and `syndicate doctor`	Both re-resolve the executable on each run; if it is still missing, set the path as described in Configuration
Doctor reports the Host is reachable but not ready	`syndicate host status` and the terminal-host service	Start or restart the terminal-host user service, then re-run `syndicate doctor`