Installation Guide for agentd¶

This guide covers installation of the agentd system on macOS.

Overview¶

The agentd system consists of:

• agent - Command-line interface for interacting with services
• agentd-orchestrator - Core agent lifecycle service (REST + WebSocket on port 17006 dev / 7006 prod)
• agentd-notify - Notification service (REST API on port 17004 dev / 7004 prod)
• agentd-ask - Ask service for interactive questions (REST API on port 17001 dev / 7001 prod)
• agentd-wrap - Tmux session launcher (REST API on port 17005 dev / 7005 prod)
• agentd-hook - Hook service for shell integration (planned)
• agentd-monitor - Monitoring service (planned)

Prerequisites¶

• macOS (tested on macOS 14+) or Linux
• Rust toolchain (1.75+) and Git - only for installing from source

Installation Methods¶

Choose one of two installation methods:

1. Release installer - Downloads prebuilt binaries from GitHub Releases (recommended)
2. cargo xtask - Builds and installs from source

Quick Start¶

Option 1: Release installer (Recommended)¶

curl -fsSL https://github.com/geoffjay/agentd/releases/latest/download/install.sh | sh

No Rust toolchain or source tree required. The script:

1. Detects your platform (Linux x86_64/aarch64 via static musl binaries, macOS Intel/Apple Silicon)
2. Downloads the release tarball and SHA256SUMS, and verifies the checksum
3. Extracts to a temporary directory
4. Runs agent install to install binaries, service definitions (launchd/systemd), configuration, the web UI, and database migrations

Environment variables:

# Pin a specific version instead of the latest release
AGENTD_VERSION=v0.5.0 sh -c "$(curl -fsSL https://github.com/geoffjay/agentd/releases/latest/download/install.sh)"

# Override the install prefix (default: /usr/local on macOS or as root, ~/.local otherwise)
PREFIX=$HOME/.local sh -c "$(curl -fsSL https://github.com/geoffjay/agentd/releases/latest/download/install.sh)"

After installation:

agent service start
agent service status

Web UI service discovery¶

The installed web UI needs no build-time configuration: at startup the SPA fetches /config.json from the agentd-ui service, which derives the browser-facing service locations from the agentd config file (the same config.toml the installer gap-fills with production ports). By default each service is reached at the page's own hostname with the service's configured port, which works for direct access to the host.

Deployments that front services with a reverse proxy or TLS can override the full URL per service. core handles login/registration (/auth/*), so it must resolve to a host the browser can reach — override it too when the default hostname + port derivation does not apply:

[services.ui.public_urls]
core = "https://agentd.example.com"
orchestrator = "https://agentd.example.com/orchestrator"
notify = "https://agentd.example.com/notify"

Option 2: cargo xtask (from source)¶

# Clone the repository
git clone https://github.com/geoffjay/agentd.git
cd agentd

# Fix /usr/local permissions (one-time setup)
sudo chown -R $(whoami) /usr/local

# Install and start services
cargo xtask install-user
cargo xtask start-services
cargo xtask service-status

Alternative: Install to your home directory (no sudo needed):

# Install to ~/.local
PREFIX=$HOME/.local cargo xtask install-user

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

# Start services
cargo xtask start-services

Detailed Installation with cargo xtask¶

Step 1: Fix Permissions (if using /usr/local)¶

# Give yourself write access to /usr/local (one-time)
sudo chown -R $(whoami) /usr/local

This allows installing to /usr/local/bin without sudo for each installation.

Step 2: Install¶

cargo xtask install-user

This will: 1. Build all binaries in release mode 2. Install to /usr/local/bin/ (or $PREFIX/bin) 3. Copy plist files to ~/Library/LaunchAgents/ 4. Create log directory at /usr/local/var/log/

Step 3: Start Services¶

cargo xtask start-services

Step 4: Verify¶

cargo xtask service-status

What Gets Installed¶

Binaries (in /usr/local/bin/ or $PREFIX/bin): - agent - CLI - agentd-orchestrator - Core agent lifecycle service - agentd-notify - Notification service - agentd-ask - Ask service - agentd-wrap - Tmux session launcher - agentd-hook - Hook service - agentd-monitor - Monitor service

Service Files (in ~/Library/LaunchAgents/): - com.geoffjay.agentd-orchestrator.plist - com.geoffjay.agentd-notify.plist - com.geoffjay.agentd-ask.plist - com.geoffjay.agentd-wrap.plist - com.geoffjay.agentd-hook.plist - com.geoffjay.agentd-monitor.plist

Log Files (in /usr/local/var/log/ or $PREFIX/var/log): - agentd-orchestrator.log / agentd-orchestrator.err - agentd-notify.log / agentd-notify.err - agentd-ask.log / agentd-ask.err - agentd-wrap.log / agentd-wrap.err - agentd-hook.log / agentd-hook.err - agentd-monitor.log / agentd-monitor.err

xtask Commands¶

# Installation
cargo xtask install-user    # Install for current user
cargo xtask install          # System-wide (requires sudo)

# Service Management
cargo xtask start-services   # Start all services
cargo xtask stop-services    # Stop all services
cargo xtask service-status   # Check service status

# Uninstallation
cargo xtask uninstall        # Remove everything

CLI Usage¶

After installation, use the agent command:

# Create a notification
agent notify create --title "Test" --message "Hello" --priority high

# List notifications
agent notify list

# List only actionable notifications
agent notify list --actionable

# Get specific notification
agent notify get <UUID>

# Respond to a notification
agent notify respond <UUID> "My response"

# Delete a notification
agent notify delete <UUID>

# Trigger ask service checks
agent ask trigger

# Answer a question
agent ask answer <QUESTION_UUID> "yes"

Service Management¶

Using cargo xtask¶

# Check service status
cargo xtask service-status

# Stop services
cargo xtask stop-services

# Restart services
cargo xtask stop-services
cargo xtask start-services

Manual Service Control¶

You can also use launchctl directly:

# Start a specific service
launchctl load ~/Library/LaunchAgents/com.geoffjay.agentd-notify.plist

# Stop a specific service
launchctl unload ~/Library/LaunchAgents/com.geoffjay.agentd-notify.plist

# Check if service is running
launchctl list | grep agentd

# View service status
launchctl list com.geoffjay.agentd-notify

Configuration¶

Service Ports¶

Each service uses a development port (17xxx) by default when started with cargo run, and a production port (7xxx) when running as a LaunchAgent:

All ports are configurable via the AGENTD_PORT environment variable.

source .env   # sets AGENTD_*_SERVICE_URL vars to dev ports (17xxx)

Custom Installation Location¶

Use the PREFIX environment variable to install to a custom location:

# Install to ~/.local
PREFIX=$HOME/.local cargo xtask install-user

# Install to /opt
PREFIX=/opt cargo xtask install-user

Note: When using a custom PREFIX, you may need to update plist files to use the correct binary paths.

Choosing user vs system install¶

By default agent install picks the layout from the platform and privileges (system-wide on macOS or when running as root, per-user otherwise). Force the choice explicitly with --user or --system:

# Per-user install: ~/.local/bin, systemd --user units on Linux
# (equivalent to `cargo xtask install-user`)
agent install --user

# System-wide install: /usr/local/bin, system systemd units on Linux
# (equivalent to `cargo xtask install`; requires root on Linux)
sudo agent install --system

$PREFIX still takes precedence over the scope when set. The flags are mutually exclusive.

Log Files¶

Service logs are written to: - Standard output: /usr/local/var/log/agentd-<service>.log - Standard error: /usr/local/var/log/agentd-<service>.err

If using custom PREFIX: - $PREFIX/var/log/agentd-<service>.log - $PREFIX/var/log/agentd-<service>.err

View logs:

# View specific service log
tail -f /usr/local/var/log/agentd-notify.log

# Or with custom PREFIX
tail -f $HOME/.local/var/log/agentd-notify.log

Troubleshooting¶

Permission Denied Errors¶

If you get "Permission denied" during installation:

Option 1: Fix /usr/local permissions (recommended)

sudo chown -R $(whoami) /usr/local
cargo xtask install-user

Option 2: Install to user directory

PREFIX=$HOME/.local cargo xtask install-user
export PATH="$HOME/.local/bin:$PATH"

Services Won't Start¶

1. Check if binaries are installed:

   ls -la /usr/local/bin/agentd-*
   # Or with custom PREFIX
   ls -la $PREFIX/bin/agentd-*
   

2. Check plist files are installed:

   ls -la ~/Library/LaunchAgents/com.geoffjay.agentd-*
   

3. Check for errors in logs:

   cat /usr/local/var/log/agentd-notify.err
   

4. Verify port availability:

   lsof -i :17004
   lsof -i :17001
   

Service Keeps Restarting¶

Check logs for errors:

cat /usr/local/var/log/agentd-notify.err

Common issues: - Database file permissions (for notify service) - Port already in use - Missing dependencies

Cannot Connect to Service¶

1. Verify service is running:

   cargo xtask service-status
   

2. Check if port is listening. Installed services use production ports (7xxx):

   curl http://localhost:7004/health    # notify
   curl http://localhost:7001/health    # ask
   curl http://localhost:7006/health    # orchestrator
   curl http://localhost:7010/health    # communicate
   

If running with cargo run (dev), use dev ports (17xxx) instead.

1. Restart services:

   cargo xtask stop-services
   cargo xtask start-services
   

Uninstallation¶

To completely remove agentd:

cargo xtask uninstall

On an installed host (no source tree), use the shipped binary. Like install, the layout is auto-detected unless you force it with --user / --system:

agent uninstall              # auto-detect
agent uninstall --user       # remove a per-user install
sudo agent uninstall --system  # remove a system-wide install

This will: 1. Stop all services 2. Remove all binaries from /usr/local/bin (or $PREFIX/bin) 3. Remove plist files from LaunchAgents 4. Remove log files

Manual cleanup if needed:

# Remove database files
rm -rf ~/.local/share/agentd

# Remove configuration files (if any)
rm -rf ~/.config/agentd

Development Installation¶

For development, you can run services directly without installing:

# Terminal 1: Run notify service
cargo run -p agentd-notify

# Terminal 2: Run ask service
cargo run -p agentd-ask

# Terminal 3: Use CLI
cargo run -p agentd-cli -- notify list

Or use the short alias:

# After building
cargo build --release

# Run directly
./target/release/agent notify list

Next Steps¶

After installation:

1. Test the CLI:

   agent notify create --title "Test" --message "Installation successful!"
   agent notify list
   

2. Check service health:

   curl http://localhost:17004/health
   curl http://localhost:17001/health
   

3. View logs to ensure services are running:

   tail -f /usr/local/var/log/agentd-notify.log
   

4. Trigger an ask service check:

   agent ask trigger
   

Getting Help¶

• Check logs: tail -f /usr/local/var/log/agentd-*.log
• Check status: cargo xtask service-status
• View all xtask commands: cargo xtask

License¶

MIT OR Apache-2.0