Skip to content

Installation

This guide covers all installation methods for agentwatch.

Requirements

  • Python 3.10+ - Required for the daemon
  • tmux - Required for terminal capture
  • uv - Python package manager (installed automatically)

Optional: - cloudflared - For manual Cloudflare Tunnel setup (not needed for agentwatch.sh tunnels)

Production Install

For most users, the one-liner install is recommended:

curl https://agentwatch.sh | bash

This downloads the latest release and installs it to ~/.local/bin/agentwatch.

Unstable Channel

To install the latest green build of main instead of the latest tagged release (both are signed tarballs, verified the same way):

curl https://agentwatch.sh/unstable | bash

The /unstable URL serves the standard install script with UNSTABLE=1 prepended. Equivalent forms: UNSTABLE=1 curl https://agentwatch.sh | bash, or ./install.sh --unstable from a local copy. (Passing flags through a bare pipe doesn't work — bash consumes them — hence the URL form.)

Unstable builds carry a +<sha> version suffix, and the box keeps tracking main automatically: the gateway self-updates on the unstable channel and, on each reconnect, pulls every connected per-user daemon up to its build. The update channel is a gateway-only setting — per-user daemons have no channel of their own; they follow whatever the gateway runs (see Architecture & Installation).

Install Options

Control installation with environment variables:

# Force reinstall (overwrites existing)
FORCE=1 curl https://agentwatch.sh | bash

# Unstable channel (latest green main build)
UNSTABLE=1 curl https://agentwatch.sh | bash

Version pinning is intentionally unsupported for production installs. The installer verifies the signed release manifest before downloading artifacts, and only the latest signed release has a verifiable manifest. If VERSION is set to anything other than the latest signed release, the installer fails closed rather than installing unverifiable code.

What Gets Installed

The installer creates:

Path Description
~/.local/bin/agentwatch Main executable
~/.config/agentwatch/config.yaml Configuration file
~/.config/agentwatch/hooks.d/ Hook scripts directory
~/.config/agentwatch/tokens/ Authentication tokens
Service file System service (see below)

Service files:

  • Linux: ~/.config/systemd/user/agentwatch.service
  • macOS: ~/Library/LaunchAgents/com.agentwatch.plist

Development Install

For contributors or those wanting to run from source. A dev install symlinks ~/.local/bin/agentwatch to your git checkout, so the prerequisite is an existing clone, and the installer must be run from inside it:

# Clone the repository
git clone git@github.com:agentwatch-sh/agentwatch.git
cd agentwatch

# Install in development mode
./install.sh --dev

# Linux only: the root-run gateway needs its own symlink (same checkout)
sudo ./install.sh --dev

Updating is just git pull in the checkout — services pick up the new code on their next restart. There is no auto-clone and no auto-pull; git state stays entirely under your control.

Development Options

# Force overwrite config (backs up existing)
./install.sh --dev --force

# Skip service file installation
./install.sh --dev --no-service

Post-Install Setup

After installation, run the setup wizard:

agentwatch setup

The wizard:

  1. Generates an API token for authentication
  2. Configures remote access (optional)
  3. Creates the service configuration
  4. Offers to start the daemon

For non-interactive setup (CI/automation):

# With device token for remote access
agentwatch setup --token <DEVICE_JWT> --yes --start

# Strict mode (fail fast on errors)
agentwatch setup --token <DEVICE_JWT> --strict --start

Service Management

After setup, manage the daemon with:

# Start in background
agentwatch start

# Start in foreground (for debugging)
agentwatch start -f

# Stop
agentwatch stop

# Restart
agentwatch restart

# Check status
agentwatch status

Manual Service Control

If needed, use system service commands directly:

systemctl --user start agentwatch
systemctl --user stop agentwatch
systemctl --user status agentwatch
systemctl --user enable agentwatch  # Start on boot

launchctl load ~/Library/LaunchAgents/com.agentwatch.plist
launchctl unload ~/Library/LaunchAgents/com.agentwatch.plist
launchctl list | grep agentwatch

Manual Service Setup

For systems without systemd or launchd (OpenRC, runit, etc.), see Manual Service Setup.

Updating

Check for and install updates:

# Check and install
agentwatch update

# Check only (don't install)
agentwatch update --check

Rolling Back

If an update causes issues, restore the previous version:

agentwatch rollback

This restores from the automatic backup created during updates.

Uninstalling

Remove agentwatch:

# Keep configuration files
./uninstall.sh

# Remove everything including config and tokens
./uninstall.sh --purge

Or use the installed command:

agentwatch uninstall
agentwatch uninstall --purge

Verifying Installation

Check that agentwatch is working:

# Check version
agentwatch --version

# Check daemon status
agentwatch status

# Health check (if daemon is running)
curl -sk https://localhost:8081/health
# Expected: {"status": "ok"}

Troubleshooting

Command not found

If agentwatch isn't found after installation, add ~/.local/bin to your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Then reload
source ~/.bashrc  # or source ~/.zshrc

Permission denied

The install script requires write access to ~/.local/bin. If you get permission errors:

mkdir -p ~/.local/bin
chmod 755 ~/.local/bin

Service won't start

Check the logs:

# View daemon logs
agentwatch logs

# Or directly
tail -f ~/.cache/agentwatch/daemon.log

Common issues:

  • Port in use: Another process is using port 8081
  • tmux not found: Install tmux first
  • Python version: Requires Python 3.10+

See Troubleshooting for more.