Connect

Sign in

nk login

If the browser cannot open, use the verification URL printed by the command. The first login registers the machine’s signing identity (TPM-backed when available) with the core; later requests are authenticated with signed challenges, not a stored token.

Inspect the current state

nk status
nk ls

nk ls lists targets and the principals available to the current identity.

Connect

ssh ubuntu@target-name

You do not normally invoke nk proxy yourself. OpenSSH invokes it through the generated configuration.

Before connecting, nk checks the certificate stored for the target’s certificate authority. If it is missing or no longer valid, it requests a new certificate while the core is reachable.

Diagnose a failed connection

nk doctor
nk status

Common errors:

• target not found: the target is not in the synchronized cache or its name is ambiguous.
• all endpoints failed: the target endpoint cannot be reached from the workstation.
• certificate expired or not yet valid: the local certificate cannot be used and a replacement could not be obtained.
• access denied on the target: the identity is not assigned to the requested Linux username. Check the daemon’s principal cache on the target with sudo cat /var/lib/nokkud/cache.json.

Headless login

Use a service-account token in CI or another environment without a browser:

export NK_TOKEN=<TOKEN>
nk login
ssh ubuntu@target-name

Service-account tokens are passed through NK_TOKEN or --token and are never written to disk. Keep the token in the environment’s secret store.

For service-account authentication, the core uses the workspace associated with the token. A script does not need to select a workspace separately for SSH certificate signing.