Quick start

This guide is for team owners and managers setting up their first managed server. When you finish, you will have an active server running the open-source GrantSSH agent, a permission connecting your SSH key to a server account, and a verified login in the activity log.

For product context, read the welcome page first.

Before you begin

You'll need:

• A Linux server with SSH enabled and sudo or root access. GrantSSH supports Ubuntu, Debian, CentOS, RHEL, and Amazon Linux.
• An SSH key pair on your machine. Use the ssh-keygen command generator or SSH key generator if you need to create one.
• A GrantSSH account. The free tier includes one server and two team members.

Set up your first server

1. 1

   Create your team

   Sign up with your name, email, password, and a team name. After registration you land on the dashboard as the team owner.

2. 2

   Add a server

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

3. 3

   Install the agent

   On the server, run the install script as root or with sudo. Replace YOUR_CLAIM_CODE with the code from step 2. The agent downloads, registers with GrantSSH, and begins checking in.

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

   For bulk or automated installs with an enrolment token instead of a claim code, see Installing the agent.

4. 4

   Approve the server

   New servers start as pending. After the agent checks in, open the server in the dashboard or the servers list and choose Approve server. Until the server is active, the agent will not receive permissions or SSH keys to sync.

5. 5

   Add server accounts

   GrantSSH does not auto-discover Linux users on the host. Open the server, go to Accounts, and choose Add for each user you want to manage — for example deploy or ubuntu. You must add at least one account before you can grant access.

6. 6

   Add your SSH public key

   Open SSH keys and choose Add key. Paste your public key only — GrantSSH never stores private keys. The key is assigned to you automatically.

7. 7

   Grant access

   On the server page, open Team access and choose Grant access. Select the team member (yourself for a first test), the server accounts they may use, and an optional schedule. When the permission is active, the agent adds their public key to each account's authorized_keys on the next sync.

8. 8

   Connect

   Open Servers, then My accounts, and choose Connect on the account you were granted. Run the shown ssh user@host command using the private key that matches the public key you added in step 6.

Verify it worked

• Allow one agent sync cycle — typically 30–120 seconds — after granting access.
• Confirm you can open a new SSH session to the server account.
• Open Activity in the dashboard and look for ssh_login events from your connection.

Troubleshooting

• Server stuck pending — approve it from the server page or servers list after the agent has checked in.
• Grant access shows no accounts — add server accounts in step 5 first.
• Key not on the host yet — confirm the server is active, wait for the next sync, then retry SSH.
• Cannot grant access — only team owners and managers can grant permissions. Members should use access requests instead.

What to read next

• How it works — the full access model: permissions, schedules, keys, and auditing.
• Installing the agent — enrolment tokens, re-installs, and uninstall.
• Managing permissions — schedules, groups, and ending access.
• Working with SSH keys — how public keys are uploaded and synced.
• Auditing activity — logins, disconnects, sudo usage, and failed login summaries.
• Security — how GrantSSH handles keys, data, and responsible disclosure.