Susan

Workstation

Available

This setup runs the dashboard and the operator with Docker Compose on your computer. The operator uses its docker engine: it starts each run (one execution of a workflow; see the glossary) in a container of your Docker engine instead of a Kubernetes Job. Runs keep going as long as the computer and Docker are on.

Before you start

Install the suite

curl -fsSL https://heysusan.dev/install.sh | sh

The script writes a Compose file and its settings to the .susan folder of your home directory (set SUSAN_HOME to choose another folder), pulls the three images (nexus-runner, nexus-operator, nexus-dashboard), starts the suite and waits until the dashboard answers on http://localhost:8090. It creates the key that signs run tokens and the operator’s API token once, in Docker volumes. Running it again updates the images and keeps your data. SUSAN_VERSION chooses the image tag.

The operator container reads the Docker socket of your computer to start the runs, so it holds the same rights as Docker on this computer. Read the script before you run it.

Isolation with gVisor

Every run container runs without Linux capabilities and without privilege escalation. On Linux with Docker Engine, the script also runs it under gVisor, by default: a user-space kernel that intercepts its system calls, so the code an agent runs no longer talks to the kernel of your computer directly.

The script downloads gVisor from its release bucket, checks the download against its SHA-512 sum, installs runsc in /usr/local/bin and declares it to Docker with runsc install, then makes Docker reload its settings (signal SIGHUP) without stopping your containers. sudo asks for your password at that step. When runsc is already declared, the script installs nothing. Before it starts the suite, it starts one container under runsc to check that Docker can use it. The end of its output contains The containers of the runs run under gVisor (runsc).

On Ubuntu with Docker installed by snap, Docker runs confined and does not see /usr/local/bin. The script then installs gVisor in /var/snap/docker/common/gvisor and declares it in /var/snap/docker/current/config/daemon.json. If the confinement still prevents Docker from starting runsc, the test container fails and the script names the cause; install Docker Engine from the Docker repository instead of the snap.

gVisor needs pkill, sha512sum, and zstd or bzip2. When one is missing, the script installs its package with the package manager of your distribution (apt-get, dnf, yum, zypper, pacman, apk or xbps-install) and names the packages before it does. It gets root rights with sudo, or with doas when sudo is missing, as on Alpine. To choose the command, set SUSAN_SUDO:

curl -fsSL https://heysusan.dev/install.sh | SUSAN_SUDO=doas sh

Without persist in /etc/doas.conf, doas asks for your password at each step, up to four times.

Running the script again keeps the choice of the first install. If Docker no longer declares runsc, the operator does not start, so no run starts without the isolation you chose. gVisor slows down commands with many file operations, such as npm install or composer install.

With Docker Desktop (macOS, or Windows without WSL2), Docker runs in its own virtual machine where the script cannot add gVisor: the runs use the default runtime of Docker, and the script says so. On Windows, install Docker Engine inside an Ubuntu distribution of WSL2 and run the command there. With rootless Docker, or to troubleshoot, install without gVisor:

curl -fsSL https://heysusan.dev/install.sh | SUSAN_GVISOR=0 sh

Build from the repository instead

From the root of a clone, docker compose up --build -d builds the three images from the sources and starts the same suite. Check the services with docker compose ps -a: operator and dashboard are running, and runner and keys have exited with code 0. In this mode, NEXUS_DASHBOARD_PORT sets the port, and NEXUS_PROJECTS lists the projects, separated by commas (default: one project named local).

Connect a forge (optional)

Without a forge, runs, questions and answers work, and the dashboard follows no pull request. To follow the pull requests of a Forgejo or Gitea forge, give its address, a token and the secret of its webhooks when you install:

curl -fsSL https://heysusan.dev/install.sh | FORGEJO_URL=https://forge.example FORGEJO_TOKEN=<your token> FORGEJO_WEBHOOK_SECRET=<secret> sh

The same variables apply to docker compose up from the repository. Susan is tested with Forgejo; Gitea serves the same API routes and webhook signature according to its documentation, without a test on a live instance yet. GitHub and GitLab are not supported yet.

Run a first workflow

From a clone of the repository, deploy/smoke-test.sh plays a full request through the dashboard API. It creates an item (a unit of work the dashboard follows), starts a run of the ask workflow, answers the question the run asks, and waits for the run to end.

NEXUS_DASHBOARD_URL=http://127.0.0.1:8090 deploy/smoke-test.sh local

The script ends with a line RÉUSSI that names the item and the two runs. Follow them on http://localhost:8090.

Serve your projects in HTTPS with the local proxy

proxyctl runs a Traefik reverse proxy on port 443 for every project of your computer, containerised or not. Domains end in .localhost, which systemd-resolved resolves to 127.0.0.1 without any DNS or /etc/hosts entry. Certificates come from mkcert.

sudo apt install mkcert && mkcert -install
make -C cmd/proxyctl install
proxyctl up

To expose a Docker service, add it to the external proxy network with two Traefik labels, then declare its domain once:

proxyctl domains add '*.myproject.localhost'

For a service that runs outside Docker, such as a dev server on port 8001:

proxyctl routes add web.myproject.localhost 8001

proxyctl routes lists every route with its backend and its health. The full reference is in cmd/proxyctl/README.md.

Stop the suite

Run containers are not Compose services, so docker compose down does not stop them. Wait for the runs to end, or remove their containers, then stop the suite:

docker rm -f $(docker ps -aq --filter label=nexus.dashboard/run)
docker compose down

Volumes are kept: runs, the dashboard database and the keys come back at the next start. Add -v to delete them.

Limits of this setup

On a clusterOn a workstation
nexus-collector keeps the messages of a run in an on-disk journal and delivers them after the pod ends.No collector. If the operator does not answer, a question fails after 10 seconds, and a run whose container disappears ends as lost.
The run stream and the operator API use mutual TLS.Plain text on the nexus-local Docker network, which does not leave the computer.
A network policy limits what the pod of a run can reach.A run container reaches everything your computer reaches.
Kueue admits runs under a cluster-wide limit.Only the operator limits apply (NEXUS_OPERATOR_LIMIT_GLOBAL, NEXUS_OPERATOR_LIMIT_PER_PROJECT).
A run can start the services its project’s Compose file describes.A run request that carries such services is rejected.

Docker starts the operator and the dashboard again after a reboot, in both modes (restart: unless-stopped).

The detailed guide, in French, is docs/lancer-un-run-en-local.md.