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 | shirm https://get.nokku.sh/nk.ps1 | iexNo 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.
nkuses 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
HostorMatchentry in your config sends it somewhere, with aHostName,ProxyJumporProxyCommand. Files you pull in withIncludecount 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 yesunder yourHost *. Passssh -Aorssh -Xfor the one connection that needs it. - A short name that only DNS or
/etc/hostsknows has no entry in your config, so a Nokku server of that name wins. Give it aHostentry with aHostNameto 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.