Customer agent setup

When to use a customer agent vs cloud crawl

Cloud crawls run on Signal Diff infrastructure. A customer agent pulls work from the API, runs checks locally, and reports results over HTTPS.

Prerequisites

1. Paid API access — Create an API key on Developers → API keys (for CI triggers and schedules).
2. Outbound HTTPS — The agent host must reach your API origin (e.g. https://signaldiff.dev) on port 443 for enroll, heartbeat, claim, and report endpoints.
3. Agent routing enabled — The API must have configuration Features:EnableAgentRouting set to true. On signaldiff.dev this is enabled; self-hosted API operators must set it in app settings or environment variables.
4. No repository access — Install from published downloads or hosted install scripts.

Setup: enroll → install → configure → verify

1. Enroll in the UI

1. Open Customer agents and sign in (requires an active paid API key).
2. Under Agent management, optionally set Agent ID, name, and pool.
3. Click Enroll agent. Copy the one-time credential from the install commands. Re-enrolling the same agent ID rotates the previous credential.

2. Install and configure

After enrollment, use the Windows, Linux, or Docker tab on Customer agents:

• Install — Downloads /install/agent.ps1 or /install/agent.sh.
• Configure — Downloads the release zip, verifies SHA256, extracts, and writes appsettings.json.
• Start — Runs the agent in the foreground (use a service for production; see below).

Default foreground paths: Windows %LOCALAPPDATA%\SignalDiff\Agent; Linux ~/.local/share/signaldiff/agent. Docker image: ghcr.io/funkysi1701/signaldiff-agent with SignalDiffAgent__* environment variables.

3. Verify heartbeat

1. Start the agent (foreground, service, or container).
2. On Customer agents, click Send test heartbeat.
3. Confirm the agent row shows a recent Last heartbeat and a semver under Version (see Version tracking).

Agent pools and CI

Pools route jobs to specific agents. Use the same agentPoolId on the enrolled agent and on the crawl (schedule, dashboard, or CI). An empty pool on both sides uses the default pool.

curl -X POST https://signaldiff.dev/api/trigger/ci \
  -H "x-ci-api-key: sck_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"sitemapUrl":"https://internal.example/sitemap.xml","failMode":"never","executionMode":"agent","agentPoolId":"production"}'

In Schedules, choose Customer agent as execution mode. See the Schedules guide for pool alignment. For GitHub Actions, set execution_mode: agent and agent_pool_id on signal-diff-action (CI key examples on API keys; agent routing on Customer agents).

Run as a service

Re-run the install script with elevated privileges:

• Windows (Administrator): -InstallService — service signaldiff-agent, default %ProgramData%\SignalDiff\Agent
• Linux (sudo): --install-service — systemd signaldiff-agent, default /opt/signaldiff/agent
• macOS (v1): foreground or nohup until launchd support is added

Credential rotation

1. On Customer agents, enroll again with the same Agent ID.
2. Update appsettings.json, environment variables, or container secrets on every host.
3. Restart the agent process or service.

Version tracking

Each agent reports its build version on heartbeat (User-Agent: SignalDiff.Agent/<version>). On Customer agents, the Version column shows the reported semver and a badge:

When updates are pending, the fleet summary shows Need update and a Latest agent release link. Download pages list each zip with an approximate file size and a .sha256 sidecar.

Upgrades

When Update available appears, click Deploy on the agent row. An Update available banner shows copy-paste commands pinned to the latest release (-UpdateOnly / --update-only, optional version flag). Your credential and appsettings.json are preserved.

1. Check downloads/agent or index.json for the latest release.
2. From Deploy wizard: use the pinned update snippet when the banner is shown (recommended).
3. Manual script: re-run the install script with -UpdateOnly / --update-only and -RestartService / --restart-service for service installs.
4. Manual binary: stop the agent, replace binaries, keep appsettings.json, restart.
5. Docker: docker pull with an explicit version tag and recreate the container.

Troubleshooting

More scenarios (stuck Running, report chunk limits, CI pool alignment): Troubleshooting — customer agents.