Skip to content
Nokku LogoNokku
GuidesLearn the concepts

Install nk, sign in, find your servers and connect with plain ssh.

Last updated on

This guide is for everyone who logs in to servers. You install nk once, sign in, and then use ssh like always. If someone invited you to a workspace, this page is all you need.

Install nk

curl -fsSL https://get.nokku.sh/nk | sh

No admin rights are needed on macOS and Windows. Pinned versions and the other options are in the nk README.

Sign in

The first time, tell nk where your workspace lives. That’s the address you open the web app at:

nk --api https://nokku.example.com login

Your browser opens with a short code. Check that it matches the one in your terminal, then approve. On a machine without a browser, open the printed link on your phone or another computer.

nk then sets up SSH for every server you can reach. It remembers the address, so from now on nk login is enough. Run it again whenever you want to refresh your session.

Where your key lives

Your SSH key is created on your machine at sign-in, and a sign-in only ever gets certificates for that one key. Where the key lives depends on the machine:

  • A TPM, the security chip many laptops have. nk uses it automatically on Linux and Windows. The key never leaves the chip.
  • A software key tied to the machine, when there is no TPM. This is the default on a Mac.
  • A FIDO2 security key, like a YubiKey, on any machine. Sign in with nk login --security-key. Every login then needs a touch.

On Linux your user needs access to the TPM first:

sudo usermod -aG tss $USER    # then log out and back in

Do this before your first nk login. Switching to the TPM or a security key later means nk logout, then signing in again. nk doctor shows which key is in use. The nk README has the details, including what a security key needs from your ssh.

Find your servers

nk ls

This lists every server you can reach, with the Linux accounts you may use.

Connect

ssh my-server              # uses your first account on it
ssh root@my-server         # pick another account you've been granted

A server’s name can already be taken by an entry in your own ~/.ssh/config. Then nokku/ goes in front: ssh nokku/web-01. Your own entry keeps pointing where you pointed it. nk ls shows the exact names to use.

Under the hood
  • A name counts as yours when a Host or Match entry in your config sends it somewhere, with a HostName, ProxyJump or ProxyCommand. Files you pull in with Include count too.
  • An entry that only adds options, like a port forward, still applies to the Nokku server of that name.
  • Agent and X11 forwarding are the exception. They are off for every Nokku server, also with ForwardAgent yes under your Host *. Pass ssh -A or ssh -X for the one connection that needs it.
  • A short name that only DNS or /etc/hosts knows has no entry in your config, so a Nokku server of that name wins. Give it a Host entry with a HostName to keep it.
  • Two Nokku servers with the same name can’t share it. Both are reached as nokku/ plus their ID.

scp, rsync, sftp and other tools that use your SSH config work the same way.

From the browser

Servers running nokkud can also be opened in the web app’s terminal, without nk. It’s handy when you are on a machine you don’t normally use.

When something fails

nk doctor         # checks sign-in, SSH setup and TPM
nk doctor --fix   # repairs local files and permissions

The messages from nk say what to do next. Troubleshooting covers the common ones.

Sign out

nk logout

This signs you out and removes everything nk stored: credentials, certificates, the cached server list, and the Include line it added to ~/.ssh/config. Your own SSH keys and settings are not touched.