Documentation / SSH keys

How to create an SSH key

Use this guide before pasting a key into Dashboard → SSH keys.

← Documentation overview

What you need

SSH uses two files: a private key (secret, stays on your computer) and a public key (one line you can share). AgenticHosting only asks you to paste your public key. We never need — and you should never send us — your private key.

After your server is created, you connect with ssh agentic@<server-ip> from the same machine that holds the matching private key (or point ssh -i at that key file).

Windows 10 or 11

Recommended: PowerShell (Windows 10/11)

Open Start → type PowerShell → run Windows PowerShell (not Command Prompt).

  1. Create a key (press Enter for default path; empty passphrase is OK for simplicity):
    ssh-keygen -t ed25519 -C "[email protected]"
    If ed25519 is not supported: ssh-keygen -t rsa -b 4096 -C "[email protected]"
  2. Show and copy your public key (one line):
    Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
    Select the whole line starting with ssh-ed25519.
  3. Paste into the dashboard Public key field.
Alternative: Command Prompt

Use cmd from the Start menu. Same ssh-keygen -t ed25519, then show the public key with:

type %USERPROFILE%\.ssh\id_ed25519.pub

Note: cat is not a built-in in cmd — use type or stay in PowerShell.

Alternative: PuTTY (PuTTYgen)

Download puttygen.exe from the official PuTTY site. Generate a key, then copy the entire contents of “Public key for pasting into OpenSSH authorized_keys file” into the dashboard.

WSL: open a WSL terminal and follow the Linux steps; keys live inside Linux, not Windows, unless you configure otherwise.

macOS

  1. Open Terminal (Spotlight → Terminal).
  2. Generate a key:
    ssh-keygen -t ed25519 -C "[email protected]"
  3. Copy the public line to the clipboard:
    pbcopy < ~/.ssh/id_ed25519.pub
    Or run cat ~/.ssh/id_ed25519.pub and copy manually.
  4. Paste into the dashboard.

If you use iTerm2, the steps are the same.

Linux

  1. Open a terminal (Ctrl+Alt+T on many distros, or your app menu).
  2. ssh-keygen -t ed25519 -C "[email protected]"
    Press Enter to accept defaults if you want a simple setup.
  3. cat ~/.ssh/id_ed25519.pub
    Copy the entire single line (often Ctrl+Shift+C or right-click copy).
  4. Paste into the dashboard.

Chromebook

  1. Enable Linux: Settings → search “Linux” → Turn on (first-time setup can take several minutes).
  2. Open Terminal from the launcher.
  3. Create your key:
    ssh-keygen -t ed25519 -C "[email protected]"
    Press Enter for defaults if you want no passphrase.
  4. Show your public key:
    cat ~/.ssh/id_ed25519.pub
    Select all → copy → paste into the dashboard.

Already use SSH elsewhere?

If you use GitHub, GitLab, or another host, you may already have ~/.ssh/id_ed25519.pub (or id_rsa.pub). Use that same public line here — it is normal to reuse one key with multiple services.

Using a non-default key file

By default, ssh-keygen creates id_ed25519 (private) and id_ed25519.pub (public) under ~/.ssh. To use a different filename or folder, pass -f with the path to the private key you want (do not add .pub — ssh-keygen writes the matching .pub next to it).

You still paste only the public line into the dashboard; provisioning never sees your private key.

Generate with a custom path (macOS / Linux)

ssh-keygen -t ed25519 -f ~/.ssh/agentichosting_ed25519 -C "[email protected]"

Show the line to paste into the dashboard (starts with ssh-ed25519):

cat ~/.ssh/agentichosting_ed25519.pub

Generate with a custom path (Windows PowerShell)

ssh-keygen -t ed25519 -f $env:USERPROFILE\.ssh\agentichosting_ed25519 -C "[email protected]"
Get-Content $env:USERPROFILE\.ssh\agentichosting_ed25519.pub

Connect with that private key

SSH must be told which private file to use with -i (the file without .pub):

ssh -i ~/.ssh/agentichosting_ed25519 agentic@YOUR_SERVER_IP

Windows (PowerShell): ssh -i $env:USERPROFILE\.ssh\agentichosting_ed25519 agentic@YOUR_SERVER_IP

Optional: ~/.ssh/config

To avoid typing -i every time, add a host block (adjust names and paths):

Host my-agentic-server
  HostName YOUR_SERVER_IP
  User agentic
  IdentityFile ~/.ssh/agentichosting_ed25519

Then run ssh my-agentic-server. On Windows, IdentityFile can use a path such as C:\\Users\\YourName\\.ssh\\agentichosting_ed25519.

Stale host key or “REMOTE HOST IDENTIFICATION HAS CHANGED”

Your computer saves the server's host key the first time you connect. If the same IP later points to a new VM (reinstall, reprovision, or cloud IP reuse), SSH refuses to connect and may show an Offending … key in … known_hosts message. That usually means the old entry must be removed, not that your login key is wrong.

Remove the saved entry for that address, then connect again and verify the new fingerprint when prompted:

ssh-keygen -R YOUR_SERVER_IP

Non-default SSH port (example 2222): ssh-keygen -R "[YOUR_SERVER_IP]:2222"

Windows: OpenSSH stores host keys in %USERPROFILE%\.ssh\known_hosts. The command above updates that file; or delete the line number SSH prints (for example line 14).

Only accept a new host key if you expect the server to have changed. If you did not, stop and confirm you are reaching the right machine.

After your server is ready

The dashboard shows something like ssh [email protected]. Run that in the same environment where your private key lives. If your private key is not the default ~/.ssh/id_ed25519, use -i (see Using a non-default key file above).

ssh -i ~/.ssh/id_ed25519 agentic@YOUR_SERVER_IP

If SSH reports a host key error for an IP you recently reused, see Stale host key (ssh-keygen -R).

Keys are attached when the server is first created. Adding a key in the dashboard later does not automatically update an existing VM — contact support if you need a different setup.

Common problems

  • “ssh-keygen is not recognized” (Windows): Use PowerShell or install OpenSSH Client (Windows optional features), not an outdated cmd-only environment.
  • “cat is not recognized” (Windows cmd): Use type %USERPROFILE%\.ssh\id_ed25519.pub or switch to PowerShell / WSL.
  • Nothing happens when I paste: Windows terminal often uses right-click → Paste; Mac ⌘V; Linux often Ctrl+Shift+V.
  • “Permission denied” or file exists: You may already have a key — show it with the same cat/Get-Content/type commands and reuse the public line.
  • SSH works from one machine but not another: Each device needs the private key (or -i / ~/.ssh/config). See Using a non-default key file.
  • “Host key verification failed” after a new server: Remove the old IP entry from known_hosts — see Stale host key.

Troubleshooting

  • Permission denied (publickey): you are not offering the private key that matches the public key you registered. Check ssh -v agentic@IP for clues, or specify -i with the correct private key (see Using a non-default key file).
  • Host key verification failed / REMOTE HOST IDENTIFICATION HAS CHANGED: your machine still has an old host key for that IP. Run ssh-keygen -R YOUR_SERVER_IP (details under Stale host key).
  • Invalid public key in dashboard: paste exactly one line, with no line breaks in the middle. It must start with ssh-ed25519, ssh-rsa, or ecdsa-sha2-…
  • I only see a “private” file: never paste that. Create or locate the matching .pub file instead.

Video tutorial

A short walkthrough video is coming soon. The written steps above match the intended flow (PowerShell or Terminal → ssh-keygen → copy .pub → paste in the dashboard).

Security reminder

Treat your private key like a password. Do not email it, paste it into chat, or upload it to AgenticHosting. If you think it was exposed, generate a new pair and update your key here (and remove the old public key from the dashboard after adding the new one).