Installing the agent

The GrantSSH agent is a small open-source program that runs on each managed server. It checks in with the app, syncs SSH public keys to authorized_keys, and reports authentication events for auditing. This guide covers both install methods — claim code and team enrolment token — plus updates, verification, and removal.

For a full first-server walkthrough including permissions and SSH access, start with the quick start guide. For how claim codes and enrolment tokens differ in the product model, see Claim code vs enrolment token.

Overview

Every managed host runs one agent instance. The agent does not proxy SSH and never stores private keys — it only adds or removes public keys on the server while a permission is active.

There are two ways to connect an agent to your team:

• Claim code — create a named server in the dashboard first, then install the agent with the one-time code shown on that server page.
• Team enrolment token — install on one or many hosts without pre-creating each server. Each host registers as a new pending server in your team.

In both cases the server starts as pending. An owner or manager must choose Approve server before the agent receives permissions or SSH keys to sync.

Requirements

• Operating system — Linux (systemd) or FreeBSD. The install script sets up a systemd unit on Linux; on FreeBSD you enable the agent with your system's service manager after install.
• Architecture — amd64 (x86_64) or arm64 (aarch64).
• Access — root, or a user who can run sudo to write to /usr/local/bin and install system services.
• Network — outbound HTTPS to your GrantSSH app URL and the agent binary download host configured for your environment.
• SSH — SSH must already be enabled on the host. GrantSSH manages authorized_keys; it does not replace OpenSSH.

GrantSSH is commonly used on Ubuntu, Debian, CentOS, RHEL, and Amazon Linux. Other Linux distributions work when systemd and the supported architecture are available.

Install with a claim code

Use this flow when you want a named server record in the dashboard before the agent connects.

1. 1

   Add the server in the dashboard

   Open Servers and choose Add server. Give the host a name your team will recognise. GrantSSH shows a claim code on the server page — copy it immediately. The code is shown once and cannot be retrieved later.

2. 2

   Run the install script on the host

   On the server, run the script as root or with sudo. Replace YOUR_CLAIM_CODE with the code from step 1.

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

   Start the agent

   On Linux, start and verify the systemd service:

   sudo systemctl start grantssh-agent

   sudo systemctl status grantssh-agent

   On FreeBSD, enable and start the agent using your system's service manager after the script completes.

Install with an enrolment token

Use a team enrolment token for scripted installs, golden images, or rolling the agent out across a fleet without creating each server in the dashboard first.

1. 1

   Generate a team enrolment token

   In the app, open Settings → Team management and choose Generate enrolment token (or Rotate enrolment token if one already exists). Copy the token before closing the dialog — it is shown once.

   Only team owners and managers can generate or rotate enrolment tokens.

2. 2

   Run the install script on each host

   Replace YOUR_ENROLMENT_TOKEN with the token from step 1. Run the same command on every server you want to enrol.

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

   Start the agent and review pending servers

   Start the agent on each host (see the claim-code flow above). Each enrolled machine appears in Servers as a pending server. The dashboard may show hostname metadata after the agent's first heartbeat — rename servers in the app if you need clearer labels.

What the install script does

The script is served from your GrantSSH app at https://app.grantssh.com/install.sh. It downloads the agent binary for your OS and architecture, installs it, and writes initial configuration.

• Binary — /usr/local/bin/grantssh-agent
• Configuration — /etc/grantssh-agent/config.json (mode 600)
• Data directory — /var/lib/grantssh-agent
• Linux service — grantssh-agent.service (enabled on install)

On first install the script writes your --app-url plus either the claim code or enrolment token into config.json. The agent exchanges that credential for long-lived agent credentials on its first connection. After registration, the claim code or enrolment token is no longer needed on the host.

You can override install paths with environment variables when running the script: INSTALL_BIN_DIR, INSTALL_CONFIG_DIR, and INSTALL_DATA_DIR.

After installation

1. Confirm the agent is running — on Linux, sudo systemctl status grantssh-agent should show an active service.
2. Wait for check-in — the server should move from Awaiting claim to showing agent metadata in the dashboard, usually within one or two heartbeat cycles.
3. Approve the server — open the server page or servers list and choose Approve server. Until the server is active, the agent will not sync permissions or keys.
4. Add server accounts — define the Linux users you want to manage under the server's Accounts section before granting access.

Update or re-install

To update the agent binary on a host that is already enrolled, run the install script again with only --app-url. If /etc/grantssh-agent/config.json already exists, the script replaces the binary and refreshes the systemd unit without overwriting agent credentials or requiring a new claim code or enrolment token.

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

Then restart the service:

sudo systemctl restart grantssh-agent

Troubleshooting

• Script exits with a missing claim code or token — provide exactly one of --claim-code= or --enrolment-token= on first install, not both.
• Invalid or already used claim code — claim codes are one-time. Create a new server in the dashboard and use the new code.
• Enrolment returns unauthorized — confirm the token was copied correctly and has not been rotated since you deployed it.
• Unsupported architecture or OS — the script supports Linux and FreeBSD on amd64 and arm64 only.
• Agent installed but server still pending approval — installation is separate from approval. An owner or manager must approve the server before keys sync.
• Server shows stale — the agent has stopped checking in. Verify the service is running, outbound HTTPS is allowed, and config.json is intact.
• Binary download fails — your GrantSSH environment must have agent release URLs configured. Contact your administrator if the script reports that the download URL is not set.

Uninstall the agent

Deleting a server in the GrantSSH dashboard removes it from your team but does not remove the agent from the machine. To fully uninstall on Linux:

sudo systemctl stop grantssh-agent
sudo systemctl disable grantssh-agent
sudo rm -f /etc/systemd/system/grantssh-agent.service
sudo systemctl daemon-reload
sudo rm -f /usr/local/bin/grantssh-agent
sudo rm -rf /etc/grantssh-agent /var/lib/grantssh-agent

On FreeBSD, stop and disable the agent through your service manager, then remove the binary and /etc/grantssh-agent and /var/lib/grantssh-agent directories.

Uninstalling the agent does not remove GrantSSH-managed keys from authorized_keys immediately. After removal, review each managed account's authorized_keys and delete any keys that should no longer be trusted.

What to read next

• Quick start — approve the server, add accounts, and grant your first permission.
• Core concepts — servers, accounts, permissions, and how the agent fits in.
• Agent configuration — configuration options and agent behaviour (coming soon).
• Managing permissions — grant, schedule, and end access.
• Security — how GrantSSH handles keys, data, and responsible disclosure.