Self-hosted agents

Troubleshooting agents

What to check when a device is offline, a job doesn't start, or a page comes back empty.

Read the logs

The agent logs one JSON object per line: agent.started, job.started, job.done, job.failed, poll.error, and for browser jobs browser.started, browser.robots (what each site's robots.txt said) and browser.page.

System	Logs
macOS	`~/Library/Application Support/si-agent/logs/agent.log`
Linux	`journalctl --user -u si-agent`
Windows	Stop the scheduled task and run `si-agent run` in a terminal

The device shows offline

A device is online when it polled in the last 90 seconds.

Check the service is running. macOS: launchctl list | grep si-agent. Linux: systemctl --user status si-agent. Windows: schtasks /Query /TN si-agent.
Linux, after logging out: user services stop at logout unless you run loginctl enable-linger $USER.
During long jobs: a device doesn't poll while it runs a job, so a long browser job shows it offline until it finishes. Heartbeats during jobs are planned. Coming soon
After network trouble: a failed poll is retried after 1 second, doubling up to 60 seconds.

The device was revoked or its credential is no longer valid. Run si-agent login, approve it again, then si-agent install.

A job stays queued

No device that polls is allowed to run it. Check, in Cloud → Agents:

A device has the job's capability (HTTP requests, Browser pages or Shell commands).
For exec, the device has full network access.
Otherwise, the device has full network access or every host in the job's hosts on its allowlist.
The device is online and not busy with a long job.

Jobs that nobody claims are dropped after 7 days. Seeing why a job is waiting is planned. Coming soon

network_denied

The job needed a host the device doesn't allow. The agent filed a network request: Allow it under Network requests in Cloud → Agents, or add the host with Edit hosts, then queue the job again.

robots_disallowed

The site's robots.txt doesn't allow the page, or the site's robots.txt couldn't be read. The browser.robots log line shows which (status 403, html page, timeout, …). The agent respects robots.txt by design; there's no override.

browser_unavailable

The agent didn't find Chrome, Chromium or Edge, or the browser stopped. Install one, or point SI_AGENT_CHROME at the browser's executable. The service doesn't read your shell's environment, so set the variable in the service itself (the launchd plist's EnvironmentVariables, or Environment= in the systemd unit via systemctl --user edit si-agent). The browser.unavailable log line names what was tried.

A page loads but data is missing

Data loaded after the page settles: add waitForSelector for an element that appears with it, or waitMs.
Content loaded on scroll: set scroll: true.
Data comes from an API call: capture it with capture.urlPattern.
Try the page with si-agent browser-test <url>, which prints what each extraction found (Browser jobs).

macOS won't open the binary

Downloaded binaries carry a quarantine flag and aren't code-signed yet. The install script clears the flag; for a manual download, run xattr -d com.apple.quarantine si-agent. Signed and notarized binaries are planned. Coming soon

Troubleshooting agents

On this page