Agent configuration

The GrantSSH agent is a small open-source binary that runs on each managed server. It polls the GrantSSH app for permission changes, keeps authorized_keys in sync, and reports SSH activity for auditing. This page documents where it stores configuration, how it connects to your team, and what to expect at runtime.

For a first-time install walkthrough, start with the quick start guide. For product concepts — claim codes, enrolment tokens, and server approval — see Core concepts.

Overview

The agent:

• Authenticates to GrantSSH with credentials issued during setup.
• Sends periodic heartbeats with host metadata (hostname, OS, architecture, agent version).
• Fetches the current permission and key set for each managed server account.
• Writes the resulting public keys into each account's authorized_keys file.
• Reports authentication events — logins, disconnects, sudo usage, and failed login summaries — from the host.

The agent does not:

• Proxy or terminate SSH connections.
• Store or handle private SSH keys.
• SSH into your servers from GrantSSH's infrastructure.
• Record full command history or keystrokes.

File layout

On a default Linux install, the agent uses these paths:

The install script accepts overrides for the binary, config, and data directories via INSTALL_BIN_DIR, INSTALL_CONFIG_DIR, and INSTALL_DATA_DIR environment variables when you run it.

Configuration file

The agent reads a JSON file at /etc/grantssh-agent/config.json by default. You can point it elsewhere with the GRANTSSH_CONFIG_FILE environment variable.

First install

The install script writes an initial config with your GrantSSH app URL and either a claim code or an enrolment token — never both.

Claim-code install (one pre-created server):

{
  "app_base_url": "https://app.grantssh.com",
  "claim_code": "YOUR_CLAIM_CODE"
}

Enrolment-token install (fleet or scripted setup):

{
  "app_base_url": "https://app.grantssh.com",
  "enrolment_token": "YOUR_ENROLMENT_TOKEN"
}

After registration

On first run, the agent exchanges the claim code or enrolment token for persistent credentials: agent_id and agent_token. It stores these in config.json and removes the one-time claim code or enrolment token from the file. Subsequent API calls authenticate with X-Agent-ID and X-Agent-Token headers.

Environment variables

At runtime, the agent recognises:

The Linux systemd unit sets both variables. If you run the binary manually or under another service manager, set them explicitly when using non-default paths.

Install script flags

The install script is served from your GrantSSH app at https://app.grantssh.com/install.sh. Pass flags after sh -s -- when piping the script:

Claim-code example:

curl -sSL "https://app.grantssh.com/install.sh" | sudo sh -s -- --claim-code=YOUR_CLAIM_CODE --app-url=https://app.grantssh.com

Enrolment-token example:

curl -sSL "https://app.grantssh.com/install.sh" | sudo sh -s -- --enrolment-token=YOUR_TOKEN --app-url=https://app.grantssh.com

If config.json already exists, the script treats the run as an update: it downloads the latest binary and refreshes the systemd unit, but does not overwrite existing credentials. Claim codes and enrolment tokens are not required on update.

Runtime loop

While running, the agent repeatedly:

1. Heartbeat — POST /api/agent/heartbeat with host metadata and agent version. GrantSSH updates last_seen_at and may return latest_agent_version and agent_release_url when a newer release is available.
2. Sync — GET /api/agent/sync to fetch the current server status and, when active, the list of server accounts with their active grants and public keys.
3. Enforce — write the allowed public keys into each managed account's authorized_keys file.
4. Report events — POST /api/agent/events with SSH authentication events read from the host (logins, disconnects, sudo commands, failed login summaries).

The agent polls on a fixed interval — typically every 30–60 seconds. Access changes therefore apply within one sync cycle, usually 30–120 seconds depending on timing and network conditions. GrantSSH does not push changes into your infrastructure; the agent always initiates outbound HTTPS connections.

Server status and sync

What the agent receives depends on the server's status in the dashboard:

• Pending — sync returns only {"status": "pending"}. No accounts or keys are sent. The agent checks in, but enforcement does not begin until a manager approves the server.
• Active — sync returns the full payload: server accounts (username, home directory) and active grants with their public keys and schedule metadata.

Server accounts must be defined in the dashboard before grants can sync. The agent does not auto-discover Linux users on the host. If an account's home directory is wrong, key writes may fail — match the username and home path to what exists on the server.

systemd service

On Linux, the install script registers and enables grantssh-agent.service:

sudo systemctl start grantssh-agent

Common operations:

• sudo systemctl status grantssh-agent — check whether the service is running.
• sudo systemctl restart grantssh-agent — restart after manual config changes.
• sudo journalctl -u grantssh-agent -f — follow agent logs.

The unit restarts the agent on failure (Restart=on-failure, 10 second delay). On FreeBSD and other non-Linux systems, enable and start the binary through your platform's service manager — the install script installs the binary and config but does not create a service unit.

Updating the agent

Two ways to update:

1. Re-run the install script — downloads the current binary without touching config.json if it already exists:

   curl -sSL "https://app.grantssh.com/install.sh" | sudo sh -s -- --app-url=https://app.grantssh.com
2. Self-update via heartbeat — when GrantSSH advertises a newer latest_agent_version, the agent can download and replace itself from agent_release_url.

After updating, restart the service so the new binary is running.

Supported platforms

The install script detects architecture and OS at install time:

• Architectures — amd64 (x86_64) and arm64 (aarch64).
• Operating systems — Linux (with systemd) and FreeBSD.

The agent needs outbound HTTPS to your GrantSSH app, permission to modify authorized_keys for managed accounts (typically run as root), and read access to system logs for auth event reporting on Linux.

Troubleshooting

• Agent will not start — confirm config.json exists, is valid JSON, and is readable by the service user. Check journalctl -u grantssh-agent for errors.
• Server stays pending in the dashboard — the agent may be running but the server has not been approved yet. Approve it from the server page. Until then, keys will not sync.
• 401 Unauthorized from the API — credentials in config.json may be invalid or out of date. Re-installing with a fresh claim code or enrolment token on a host without existing config issues new credentials; deleting config and re-running first-time install also works but requires re-approval if a new server record is created.
• Keys not appearing on the host — confirm the server is active, server accounts exist in the dashboard, a permission is currently active, and the account home directory is correct. Wait one sync cycle before retrying SSH.
• No activity events — the agent reports events from host logs. If log sources are unavailable or accounts do not match dashboard entries, events may be missing or unattributed.

What to read next

• Quick start — end-to-end setup for your first server.
• Core concepts — claim codes, enrolment tokens, and server approval.
• Installing the agent — enrolment workflows and fleet installs (coming soon).
• Access model — how permissions and schedules drive key presence.
• Security — keys, outbound-only connectivity, and responsible disclosure.