Install & Enroll

Use nokkud when Nokku should manage the server-side SSH integration. The daemon runs an embedded SSH server on port 4022 and replaces the system sshd for Nokku access. It needs root access so sessions can be dropped to the target user’s privileges.

The system’s sshd is never touched: it stays on port 22 as a break-glass path, while all Nokku traffic goes through the daemon on port 4022.

The current nokkud commands and flags are maintained in the nokkud README and in nokkud --help.

Where things live

All daemon state lives under /var/lib/nokkud/. The daemon does not write to /etc/ssh:

• config.json holds the enrollment state and daemon configuration (target and daemon IDs, API URL, CA ID, SSH listen address).
• cache.json holds the cached principal map: which subject UUIDs are authorized for which Linux username.
• state.json holds the machine’s signing identity (TPM-backed or a software key wrapped to the machine).
• ssh_host_ed25519_key{,.pub,-cert.pub} is the daemon’s own SSH host key, generated on first boot, and its signed host certificate.
• nokku_ca.pub is the trusted SSH CA public key.
• recordings/ holds gzipped asciicast session recordings.
• audit/ holds the local JSONL security audit log.

Protect the daemon state: it contains the enrollment credentials and the machine’s signing identity.

Install

Run on the target server:

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

The installer prefers your distro’s package (deb/rpm/apk) via the Cloudsmith repository and falls back to the GitHub release tarball. The packaged installation provides the binary and service integration for supported Linux distributions. It also installs firewall definitions so opening the SSH port is a named one-liner. See the daemon README for release package details, or the Cloudsmith package repository for manual apt/dnf/apk install instructions.

Firewall

Because the daemon serves SSH directly on each host, port 4022 (or your custom --ssh-addr port) must be reachable by your users.

With the packaged firewall definitions:

# ufw (Debian, Ubuntu)
sudo ufw allow nokkud

# firewalld (Fedora, RHEL)
sudo firewall-cmd --permanent --add-service=nokkud
sudo firewall-cmd --reload

On a manual install, or if you changed the listen address, allow the port directly:

# ufw
sudo ufw allow 4022/tcp

# firewalld
sudo firewall-cmd --permanent --add-port=4022/tcp
sudo firewall-cmd --reload

On cloud instances, also open TCP 4022 in the provider’s security group or network firewall.

Enroll

Generate an enrollment token for the workspace, then run:

sudo systemctl stop nokkud
sudo nokkud --enroll <TOKEN>

The enrollment command starts the daemon in the foreground. The token is sent to the core, which creates a target for the daemon. Successful enrollment stores daemon credentials and target information under /var/lib/nokkud/config.json. Once enrollment succeeds, stop the foreground process with Ctrl-C and start the service:

sudo systemctl enable --now nokkud

The enrollment command must be run with the token available. The installed service does not invent or retrieve an enrollment token by itself.

What the daemon runs

Once enrolled, the daemon:

1. Serves an embedded SSH server on :4022 (configurable with --ssh-addr or NOKKUD_SSH_ADDR; set to empty to disable).
2. Generates and manages its own SSH host key and refreshes the signed host certificate before it expires.
3. Authenticates every SSH login with a short-lived user certificate signed by the trusted CA, and checks the certificate principal against the locally cached principal map.
4. Runs sessions, commands, and the SFTP subsystem as the target Linux user, with that user’s home directory and shell.
5. Keeps an outbound control stream to the core to synchronize principal assignments, certificates, and status.

The daemon does not configure or restart sshd, and it never reads the system host keys under /etc/ssh. nk connects to the endpoint reported by the daemon (the private IPs plus the SSH port).

Principal synchronization

The daemon receives principal assignments over its control stream and stores them in:

/var/lib/nokkud/cache.json

When a user connects over SSH, the embedded server checks the certificate principal (the subject’s UUID) against the cache for the requested Linux username. The check is done in-process from the local cache; it does not call the core during a login.

Service management

On a systemd host:

sudo systemctl enable --now nokkud
sudo systemctl status nokkud
sudo journalctl -u nokkud -f

The daemon also contains support for other service managers. Use the service manager installed on your operating system.

Offline behavior

The daemon reconnects and synchronizes after a control-stream interruption. While the core is unavailable, the embedded SSH server keeps serving from the last synchronized principal cache. New policy changes and certificate renewals require a connection to the core.

Reset and re-enroll

sudo nokkud reset
sudo nokkud --enroll <NEW-TOKEN>

reset asks the core to delete the daemon and removes all local daemon state under /var/lib/nokkud/. Because the daemon never wrote to /etc/ssh, there is nothing else to clean up.