Install nk on the machine from which you will run SSH:
curl -fsSL https://get.nokku.sh/nk | shThe installer downloads the latest release. It prefers your distro’s package (deb/rpm/apk) via the Cloudsmith repository and falls back to the GitHub release binary. On Windows, download the binary from the GitHub releases page.
Prefer manual packages? See the Cloudsmith package repository for apt/dnf/apk install instructions.
Sign in
nk loginThe browser login flow authenticates you and registers this machine’s signing identity with the core. From then on, nk authenticates every request with a signed challenge from that device-bound key instead of a stored token. nk also maintains local configuration, cached API data, SSH configuration, keys, known hosts, and certificates under ~/.config/nk/.
Hardware-backed keys (TPM 2.0)
On machines with a TPM 2.0, nk can keep two different keys inside the chip:
- Request signing — a key generated in the TPM signs the challenges that authenticate CLI requests to the core.
- SSH key storage — with
--key-type tpm, the SSH identity is a deterministic key generated in the TPM. Only the public key is written to disk; during a connection,nk proxyserves the private key over an embedded SSH agent (~/.config/nk/agent.sock) that OpenSSH reads through the generatedIdentityAgentdirective.
In both cases the private key never leaves the chip and the same key is re-derived on every run, so nothing secret needs to be stored on disk. Machines without a TPM fall back to a software key — for request signing, encrypted with a key derived from the machine’s identity; for SSH, a default ed25519 key on disk. Pass --require-tpm to refuse the software fallback for request signing. --key-type tpm needs a working TPM to enroll the SSH identity: if the TPM is unavailable it falls back to ed25519 (or fails when a TPM identity was already enrolled, rather than silently downgrading).
On Linux, the TPM device (/dev/tpm0 and /dev/tpmrm0) is owned by root with group tss, so your user must be a member of that group to use the TPM:
sudo usermod -aG tss $USERLog out and back in (or run newgrp tss) for the group change to apply, then confirm the device is accessible:
ls -l /dev/tpm0 /dev/tpmrm0If the device shows group tss with mode rw-rw----, nk can use it. Add your user to the tss group before the first nk login: the request-signing key is registered with the core during login, and switching the signing identity later (for example from the software fallback to the TPM) requires re-registering the device (nk logout, then log in again). Changing --key-type only affects the SSH key and is picked up on the next sync.
Not on tss?
Some distributions use a different group. Check the ownership shown by the ls -l command above and add your user to the group that owns the TPM device
instead.
TPM is supported on Linux and Windows. On macOS (and other platforms) nk has no TPM backend: it always uses the software fallback key there, and --require-tpm fails. On Windows, nk uses the TPM through the Windows TPM stack and no group membership is required.
Service accounts
For automation, pass a service-account token through NK_TOKEN:
NK_TOKEN=<TOKEN> nk loginDo not place service-account tokens in source control or command history.
Self-hosted core
Point the CLI at another core with --api or NK_API_URL:
NK_API_URL=https://api.example.com nk loginRemove local state
To remove the installed binary and local CLI data:
rm -f /usr/local/bin/nk
rm -rf ~/.config/nkThe exact binary path depends on how nk was installed.