Self-hosted agents

Install the agent

Install on macOS, Linux or Windows; it logs in and starts as a background service.

Install

The install script downloads the agent for your system, connects it to your organization, and installs it as a background service for the current user. Run it as yourself, not as root or Administrator.

Terminal

curl -fsSL https://downloads.gov.vin/install.sh | sh

Installs to ~/.local/bin/si-agent and clears the download quarantine flag, then runs si-agent login and si-agent install. Apple silicon and Intel are both supported.

Terminal

curl -fsSL https://downloads.gov.vin/install.sh | sh

Installs to ~/.local/bin/si-agent, then runs si-agent login and si-agent install. x64 and arm64 are supported. The service is a systemd user service, so it stops when you log out unless lingering is on:

loginctl enable-linger $USER

PowerShell

irm https://downloads.gov.vin/install.ps1 | iex

Installs to %LOCALAPPDATA%\si-agent\si-agent.exe, then runs si-agent login and si-agent install. Windows on x64 is supported.

login opens your browser to approve the device; see Login and approval. If the machine has no browser, open the printed link on another device.

Download directly

The binaries are single files, published at:

https://downloads.gov.vin/agent/latest/si-agent-darwin-arm64
https://downloads.gov.vin/agent/latest/si-agent-darwin-x64
https://downloads.gov.vin/agent/latest/si-agent-linux-x64
https://downloads.gov.vin/agent/latest/si-agent-linux-arm64
https://downloads.gov.vin/agent/latest/si-agent-windows-x64.exe

Each release is also kept under agent/<version>/, with manifest.json listing every binary's SHA-256 and manifest.json.sig, its Ed25519 signature. After downloading, run si-agent login and si-agent install yourself. On macOS, a downloaded binary may need its quarantine flag cleared first: xattr -d com.apple.quarantine si-agent. Signed and notarized macOS and Windows binaries are coming. Coming soon

The background service

si-agent install registers the agent to start at login and restart if it stops:

System	Service	Logs
macOS	launchd agent `vin.gov.si-agent` in `~/Library/LaunchAgents`	`~/Library/Application Support/si-agent/logs/agent.log`
Linux	systemd user unit `si-agent.service`	`journalctl --user -u si-agent`
Windows	Scheduled task `si-agent`, at logon	Run `si-agent run` in a terminal to see output

si-agent uninstall removes the service. The agent's credential is kept in:

System	File
macOS	`~/Library/Application Support/si-agent/credentials.json`
Linux	`$XDG_CONFIG_HOME/si-agent/credentials.json`, or `~/.config/si-agent/credentials.json`
Windows	`%APPDATA%\si-agent\credentials.json`

The file is readable only by your user.

Commands

Command	Does
`si-agent login [--name <name>]`	Connects this machine to an organization. The name defaults to the computer's hostname.
`si-agent install`	Installs and starts the background service. Needs a login first.
`si-agent uninstall`	Removes the background service.
`si-agent run`	Runs in the foreground, logging to the terminal.
`si-agent status`	Shows the connected device, organization and version.
`si-agent update`	Installs the latest release now.
`si-agent logout`	Removes the service and the local credential.
`si-agent --version`	Prints the version.

logout doesn't disconnect the device on the platform side; revoke it in Cloud → Agents to invalidate its credential.

Update

The background service updates itself: when idle (never during a job) it checks for a new release at start and every 6 hours, verifies the release's signature and the binary's SHA-256, replaces itself and restarts. A foreground si-agent run installs the update and keeps running the old version until you restart it. si-agent update checks now. To turn automatic updates off, set SI_AGENT_AUTO_UPDATE=0 in the service's environment.

Services installed by agents before 0.2.0 don't restart on their own after updating; run si-agent install once to refresh the service. To update by hand, download the new binary over the old one (Download directly) and restart the service:

System	Restart
macOS	`launchctl kickstart -k gui/$(id -u)/vin.gov.si-agent`
Linux	`systemctl --user restart si-agent`
Windows	`schtasks /End /TN si-agent`, then `schtasks /Run /TN si-agent`

Running the install script again also updates, but it logs in again, which connects the machine as a new device; revoke the old one in Cloud → Agents.