This guide puts nokkud inside a container, so you can ssh into it like into any server. It fits anything short-lived that people or scripts need a shell in: a devbox per developer, a CI runner you want to debug, or a sandbox an AI agent works in. Every session is checked, audited and recorded like on a server.
How it works
The container runs nokkud as its main process. On start it enrolls itself with the token you give it and connects to the core. Sessions travel through the relay, so nothing has to be exposed. See What happens when you type ssh.
Two things make containers different from servers, and a token handles both:
- Grants are on the token. A container is new every time, so nobody can grant access to it in advance. An enroll token can carry the login accounts and who may use them. Every container it enrolls starts with those grants.
- Containers go away. An ephemeral token tells the core to remove the container’s record once it has been offline for a while, and tells the container to remove itself when it stops.
Create the token
In the web app, open Servers and enroll servers to create an enroll token. That needs the admin role.
- Turn on Ephemeral hosts and pick how long a container may be offline before it is removed.
- Under Login accounts, add
devand grant it to the people or the team who should get in. The image ships with that account. Add your own accounts when you build your own image. - Add a tag like
sandboxif you want the containers grouped in the access graph.
The token is shown once. Keep it where your orchestrator can read it, like a Kubernetes secret.
Run a container
docker run -d --hostname alice -e NOKKUD_ENROLL_TOKEN='<token>' ghcr.io/nokku-sh/nokkud
ssh dev@alice
The web app shows this command with your token and workspace address filled in, under Container after you create the token.
The container shows up as a target named alice right away. People granted on dev can log in right away. When you stop the container it removes itself. When it is killed without warning, the core removes it after the time you picked.
Names
The target is named after the container’s hostname when a person chose it, so pass --hostname. A random Docker hostname gets a generated name like brave-otter instead. Kubernetes pod names are used as they are, since that is what kubectl shows you.
A new container from the same ephemeral token that starts under the name of one that went offline takes its place. One that starts while the old one is still online gets a generated name.
Build your own image
Start from the image and add what the people inside need:
FROM ghcr.io/nokku-sh/nokkud
RUN apt-get update \
&& apt-get install -y --no-install-recommends git nodejs \
&& rm -rf /var/lib/apt/lists/* \
&& useradd -m -s /bin/bash agent
Every login account you add can be granted on the token. The container has to run as root, which is the default, because nokkud starts each session as the account that was granted. Only the sessions run as that user.
Kubernetes
A pod works the same way. The pod name becomes the target name and the relay means it needs no Service:
apiVersion: v1
kind: Pod
metadata:
name: sandbox-7
spec:
containers:
- name: nokkud
image: ghcr.io/nokku-sh/nokkud
env:
- name: NOKKUD_ENROLL_TOKEN
valueFrom:
secretKeyRef:
name: nokku-enroll
key: token
A Deployment names its pods with a hash. Those names are kept as they are, so what you see in Nokku matches kubectl get pods.
A devbox that stays
A box someone keeps for weeks is the same image with a volume:
docker run -d --hostname alice -v alice-nokkud:/var/lib/nokkud \
-e NOKKUD_ENROLL_TOKEN='<token>' ghcr.io/nokku-sh/nokkud
The volume holds the enrollment, so the box comes back as the same target with the grants it had. Use a normal token for it, not an ephemeral one, and keep the hostname fixed. The container’s identity is bound to the machine it runs on, so keep the volume on the same host. A volume moved to another one refuses to start.
Under the hood
nokkudreadsNOKKUD_ENROLL_TOKENonly while nothing is enrolled. Once the state directory holds an enrollment, the variable is ignored. That is why a token left in a pod spec cannot move a devbox or spend another use.- The token’s grants and tags are copied onto the target when the daemon is created, and never again. A change you make under the target in the web app stays, also after a restart.
- Removing an ephemeral daemon works like deleting one by hand. Its target, accounts and grants go with it, and the audit log gets one event per removal.
- The image is a slim Debian with
tinias PID 1, which reaps the shells that sessions leave behind. The daemon resolves accounts withgetent, so a custom base image needs it too.