Skip to main content
Russel runs on one Linux host. A single control plane, russel-ctrl, takes a git repo, builds it with Nix, and runs the result as a rootless container (or, experimentally, a microVM). Traefik, if you run it, routes host names to the apps.

​
Overview

The design in short:
  • One host, one control plane. There is no cluster and no scheduler.
  • Nix is the only build system. Every build produces a /nix/store path, and both runtimes run it from there. Nothing is copied into an image.
  • Two runtimes, one pipeline. service.type picks a rootless container (the default) or a microVM after the shared fetch and build steps. See Runtimes.
  • Apps publish on loopback. Each app gets a 127.0.0.1 host port. Traefik routes Host() names to those ports. See Networking.
  • Restarting the control plane doesn’t stop apps. On start-up it finds the running apps again and takes them back over. See Lifecycle.

​
A deploy, step by step

The CLI prints each stage as it arrives: resolve, build, create, start, ready. If a deploy fails and an earlier version exists, Russel restores it and reports rolled_back; the CLI still exits non-zero so scripts notice. At most 4 deploys run at once (RUSSEL_MAX_CONCURRENT_DEPLOYS), and only one per service. Checks on this path:
  • Service names are limited to A-Z a-z 0-9 _ -, 128 characters, before they touch the filesystem.
  • The Russelfile must be a real file inside the repo (no symlinks) and under 1 MiB.
  • Env vars are validated when the Russelfile loads and again after secrets are filled in.
  • Nix builds run code from the repo. Only deploy repos you trust, or turn on RUSSEL_NIX_RESTRICTED=1. See Nix build security.

​
State and restarts

Everything lives under /var/lib/russel, one folder per service: When the control plane starts, it reads each metadata.json and checks whether the app is still running. For a microVM it checks the process id and its command line, so a reused process id isn’t mistaken for the app. For a container it asks Podman. Running apps are taken back over; the rest are marked stopped. A lock file stops a second control plane from starting on the same folder.

​
Security boundaries

More: Security overview.

​
Source layout

For contributors: