Key Authentication (Preview)

Log in with a key

Instead of a token, the agent can log in to its tunnel with a key, like SSH. The private key stays on your machine and you never paste it anywhere. Needs an agent newer than v0.4.2.

Create a key just for ngris: mkdir -p ~/.config/ngris && ssh-keygen -t ed25519 -N "" -f ~/.config/ngris/agent_key. On Windows, use the Windows PowerShell block.
Register it. In the dashboard, open Security → Agent keys and click Upload key. Run the command it shows, ngris key sign <code>, and paste the output. The key then logs in as you, in that account.
Use it: ngris auth --private-key-file ~/.config/ngris/agent_key.
Start a tunnel as usual, for example ngris http 3000 --url myapp.ngris.dev.

You can also set the key in config.yaml, or pass --auth-method key --private-key-file <file> to a tunnel command. Environment variables can't set it: in a container, mount the key file and a config file, or pass the flags.

Never paste or share the private key. The dashboard needs only the output of ngris key sign. A private key you pasted anywhere is no longer secret: create a new one.

Key authentication (Preview)

# 1. Create a key
mkdir -p ~/.config/ngris && ssh-keygen -t ed25519 -N "" -f ~/.config/ngris/agent_key

# 2. Sign the code from Security → Agent keys → Upload key,
#    then paste the output there
ngris key sign <code>

# 3. Use the key
ngris auth --private-key-file ~/.config/ngris/agent_key
ngris http 3000 --url myapp.ngris.dev

Windows PowerShell

# 1. Create a key (press Enter twice when asked for a passphrase)
New-Item -ItemType Directory -Force $HOME\.config\ngris | Out-Null; ssh-keygen -t ed25519 -f $HOME\.config\ngris\agent_key

# 2. Sign the code from the dashboard, then paste the output there
ngris key sign <code>

# 3. Use the key
ngris auth --private-key-file $HOME\.config\ngris\agent_key

config.yaml — key login

authentication:
  method: key                                  # token or key
  private_key_file: ~/.config/ngris/agent_key

What still needs a token

A key logs in tunnels only. Keep a token for:

edge protection set from the agent: --basic-auth, --mutual-tls / --client-ca, --traffic-policy and its shorthand flags, webfm --rw, and the same settings in the config file. With any of them, the agent logs in with its token; without a token it doesn't start.
removing endpoint auth an earlier run set from the agent (or remove it in the dashboard)

Protection you set on an endpoint in the dashboard works with a key too. The app commands (deploy, apps, env, promote, rollback, cron, hooks, client-cert, api) use neither: they need an API key or account key, whatever the tunnel logs in with (see App commands: an API key, and The ngris API from your terminal for ngris api).

Key and token together

If a token is also configured, it stays as a backup. The key goes first after ngris auth --private-key-file (it sets method: key), otherwise the token. If the first one is not accepted (for example, a deleted key), the agent tries the other once and prints a warning. Use a key and a token of the same account. For key-only login, remove the token from the config and delete it in the dashboard. A token kept only as a backup is deleted after 90 days unused, like any token.

Limits

Keys: ed25519 (recommended) or RSA with 2048 to 4096 bits.
Not supported: keys with a passphrase, hardware security keys, ECDSA keys, keys held only in ssh-agent, and PuTTY .ppk files (convert them with PuTTYgen).
A key can be registered once on ngris. For a second account, create a second key.
A key opens any endpoint of its account. To limit an agent to one endpoint, use a token restricted to it.
The Kubernetes operator and the Python SDK use tokens only.
Networks that inspect encrypted traffic (TLS-inspecting proxies) block key login. Use a token there.
Register keys in the dashboard or with an API key, also from your terminal with ngris api (ngris api help agent-keys). Assistants connected through MCP, and Iris, can't register keys.

Good to know

Use the key only for ngris, not for SSH logins.
Deleting a key stops new logins. An agent already connected stays up until it reconnects.
When a member leaves the account, their keys are deleted.
Members who can see the account's tokens can see its keys; members who can manage endpoints can delete any of them.
Keys don't expire.

Troubleshooting

passphrase-protected: create a new key with the command in step 1. On Windows, press Enter twice when asked for a passphrase.
permissions … are too open: run chmod 600 ~/.config/ngris/agent_key.
PuTTY .ppk key: in PuTTYgen, use Conversions → Export OpenSSH key and point the agent at the exported file.
already registered: the key is in another account or belongs to another member. Delete it there, or create a new key.
does not match: open Upload key in the account you want, run its command again unchanged, and paste the new output.
The key type or size isn't supported, or the key can't be used: create a new key with the command in step 1.
key login refused when a tunnel starts: the key was deleted or isn't registered in this account. The agent prints Using key SHA256:… at start; that fingerprint must be in Security → Agent keys.