# Connect to servers

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

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

**Linux and macOS**

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

**Windows**

```powershell
irm https://get.nokku.sh/nk.ps1 | iex
```

No admin rights are needed on macOS and Windows. Pinned versions and the other options are in the [nk README](https://github.com/nokku-sh/nokku/tree/main/cli#install-options).

## Sign in

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

```bash
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:

```bash
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](https://github.com/nokku-sh/nokku/tree/main/cli#where-your-key-lives) has the details, including what a security key needs from your `ssh`.

## Find your servers

```bash
nk ls
```

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

## Connect

```bash
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

```bash
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](/docs/reference/troubleshooting) covers the common ones.

## Sign out

```bash
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.
