# Add a server

> Install the Nokku daemon on a Linux server and enroll it in your workspace.

This guide adds a Linux server to Nokku with **`nokkud`**, the Nokku daemon. It's the recommended way: access changes reach the server right away, sessions can be recorded, and the server can be reached without opening ports. Can't install software on a server? See [Servers without the daemon](/docs/servers/without-daemon).

## What the daemon does

`nokkud` runs its own small SSH server on port `4022`, next to your normal `sshd`. It checks Nokku certificates, keeps the list of who may log in, and runs each session as the right Linux user.

Your system `sshd` on port `22` is **never touched**. It keeps working exactly as before, as a way back in if you ever need one.

## Install

On the server:

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

The installer uses your distro's package when it can. Manual installs are covered in the [nokkud README](https://github.com/nokku-sh/nokku/tree/main/daemon).

## Enroll

In the web app, open **Servers** and enroll a server. That creates an **enroll token** and needs the **admin** role. The web app shows the commands with your address filled in, so copy them from there:

```bash
sudo nokkud --api https://nokku.example.com enroll   # paste the token, it is not shown
sudo systemctl restart nokkud
```

The server appears in your workspace under its hostname. You can rename it in the web app. Unless the token approves servers automatically, someone with the **editor** role or higher approves it there first.

**More about enroll tokens**

- **Many servers, one token:** one token can enroll a whole fleet. You can give it an expiry or a limit on how many servers it may add.
- **Grants on the token:** a token can carry Linux accounts and who may use them, plus tags. Every server it enrolls starts with them. They are copied once, and what you change under the server later stays.
- **Unattended installs:** set `NOKKUD_ENROLL_TOKEN` in the environment instead of answering the prompt. The service enrolls itself on start when the variable is set and nothing is enrolled yet. The token is never accepted as a command-line argument, because other users on the machine could read it there.
- **Names:** a default hostname from a cloud image, like `ip-10-0-1-23`, gets a readable generated name instead.
- **Enrolling again** is safe. Enrolling in another workspace moves the server there and drops everything the old workspace trusted.
- **Containers** are covered in [SSH into containers](/docs/servers/containers).

## Network

Nokku sessions reach the server in one of two ways, and `nk` tries both at once:

- **Through the relay.** Works out of the box. The daemon keeps an outbound connection to the core, and sessions travel over it, encrypted end to end. Nothing needs to be opened.
- **Directly** on port `4022`. Faster. Open it for the networks your users connect from:

**Debian, Ubuntu**

```bash
sudo ufw allow nokkud
```

**Fedora, RHEL**

```bash
sudo firewall-cmd --permanent --add-service=nokkud
sudo firewall-cmd --reload
```

On cloud servers, also allow TCP `4022` in the provider's firewall or security group.

## Restarts and upgrades

A restart ends the sessions that are open on the daemon. A package upgrade is gentler: under systemd the daemon keeps serving and switches to the new binary once the open sessions end, or after a while at the latest.

## Where its files live

Everything the daemon owns is under `/var/lib/nokkud/`. It never writes to `/etc/ssh`. Treat the directory as sensitive: it holds the server's identity in Nokku and its SSH host key.

**Under the hood**

- One file holds the enrollment and the synced access: the access list, the trusted CA keys and the session rules.
- The daemon's identity toward the core is a separate key. With a TPM it never leaves the chip. Without one it is a software key wrapped to the machine, and `--require-tpm` refuses that fallback.
- The SSH host key is a normal OpenSSH key file, readable by root only, like `sshd`'s own. Every enrollment makes a new one. The host certificate sits next to it.
- Recordings that are not uploaded yet wait in a folder next to them.
- Logins, commands and forwards are written to the service log as `audit` lines, so `journalctl -u nokkud` has them.
- Password and plain-key logins are refused. Only certificates work.

## Remove a server

```bash
sudo nokkud reset
sudo systemctl disable --now nokkud
```

`reset` removes the server from Nokku and deletes all local daemon state. Uninstall the package afterwards if you like.

## Next steps

- [Grant access](/docs/access/grants) to the new server.
- Choose what sessions may do: [Session rules](/docs/servers/session-rules).
- Every flag and environment variable: [nokkud README](https://github.com/nokku-sh/nokku/tree/main/daemon).
