Engines
An engine is what runs a workflow: a container per step, a microVM,
or a machine in your own Namespace workspace. Every workflow picks one
with the required engine field, and
each workflow in a pipeline can pick a different one.
The common fields apply to every workflow. Each engine then adds its own fields on top, for images, dependencies and machines, described below.
| Engine | Runs on | Use it for |
|---|---|---|
nixery | A fresh Docker or Podman container for each step, with the image built from your Nix packages by Nixery | Short, stateless builds and tests. |
microvm | The whole workflow inside its own microVM, with a choice of images | Stronger isolation, NixOS services such as PostgreSQL, Docker inside CI. |
namespace | A machine in your own Namespace workspace, Linux or macOS | If you’re already using Namespace for CI, or need easy multi-arch machines. |
With nixery, state persists across steps only in the
/tangled/workspace directory. With microvm and namespace, files,
packages and services persist for the whole workflow.
Which engines and images exist depends on the spindle operator. You can even write your own engines.
Nixery engine
Section titled “Nixery engine”Each step runs in a fresh container built by Nixery from your dependencies. The workspace is shared between steps; nothing else is.
engine: nixerydependencies: nixpkgs: [go]Dependencies
Section titled “Dependencies”The dependencies field lets you define which dependencies to get, and
from where. It’s a key-value map, with the key being the registry to
fetch dependencies from, and the value being the list of dependencies to
fetch.
The registry URL syntax can be found in the Nix manual.
Say you want Node.js and Go from nixpkgs, and a package called
my_pkg you’ve made in your own repository at
https://tangled.org/@example.com/my_pkg:
dependencies: # nixpkgs nixpkgs: - nodejs - go # unstable nixpkgs/nixpkgs-unstable: - bun # custom registry git+https://tangled.org/@example.com/my_pkg: - my_pkgThese dependencies are now available to every step.
Complete nixery workflow
Section titled “Complete nixery workflow”# .tangled/workflows/build.yml
when: - event: ["push", "manual"] branch: ["main", "develop"] - event: ["pull_request"] branch: ["main"]
engine: "nixery"
# using the default valuesclone: skip: false depth: 1 submodules: true
dependencies: # nixpkgs nixpkgs: - nodejs - go # custom registry git+https://tangled.org/@example.com/my_pkg: - my_pkg
environment: GOOS: "linux" GOARCH: "arm64" NODE_ENV: "production" MY_ENV_VAR: "MY_ENV_VALUE"
steps: - name: "Build backend" command: "go build" environment: GOOS: "darwin" GOARCH: "arm64" - name: "Build frontend" command: "npm run build" environment: NODE_ENV: "production"For another example, see the workflow Tangled uses to build the project.
microVM engine
Section titled “microVM engine”The whole workflow runs in one QEMU microVM, so files, installed
packages and running services carry over from one step to the next.
Steps run as the unprivileged spindle-workflow user in
/workspace/repo. The VM has outbound network access only, with private
address ranges blocked.
engine: microvmimage: nixosdependencies: [go, "unstable#zig", "github:nixos/nixpkgs#hello"]registry: nixpkgs: github:nixos/nixpkgs/nixos-unstablesubstituters: https://nix-community.cachix.org: "nix-community.cachix.org-1:..."services: postgresql: truevirtualisation: docker: trueA workflow picks the image to boot with the top-level image field:
engine: microvmimage: nixosThere are two flavours of images:
- NixOS images (e.g.
nixos): the whole guest is built with Nix, so you can configure it from the workflow file itself. Thedependencies,services,virtualisation,registryandsubstitutersfields below are all understood here, and the guest builds and activates that configuration before any of your steps run. - Non-NixOS images (e.g.
alpine,almalinux10): there’s no NixOS to configure, so the workflow-level config fields above have no effect. You still get a full machine to run steps in.
The available image names depend on what the spindle operator has
installed. nixos, alpine and almalinux10 are the images built from
the Tangled repository. If image is omitted, the spindle’s configured
default image is used (nixos-x86_64 unless the operator changed it).
In every image, nixpkgs (as in nix shell nixpkgs#hello or
<nixpkgs>) is the nixpkgs revision the image was built from, and
nix flake metadata nixpkgs prints it. unstable is the latest
nixpkgs-unstable, as in nix shell unstable#hello.
Dependencies
Section titled “Dependencies”On the microVM engine, dependencies is a flat list of packages that
are made available to every step. This field only applies to NixOS
images; for other images, use the image’s package manager in a step.
The guest builds a
nix develop-style
devshell from your dependencies and uses it for each step. For example,
adding pkg-config and openssl is enough for the openssl-sys crate
to build in a Rust project.
A bare name like go is looked up in the image’s nixpkgs, so it is the
same go as nixpkgs#go in a step. You can also point at any flake with
the flakeref#attr syntax, so unstable#go takes go from
nixpkgs-unstable and github:nixos/nixpkgs#hello pulls hello straight
out of that flake.
dependencies: - go - unstable#zig - github:nixos/nixpkgs#helloRegistry
Section titled “Registry”The registry field remaps flake references, the same way
nix registry does. This lets you pin or alias the flakes used by
dependencies.
For example, pin nixpkgs to nixos-unstable so that the bare go
above resolves from unstable, and alias your own flake so you can use
myflake#tool in dependencies:
registry: nixpkgs: github:nixos/nixpkgs/nixos-unstable myflake: github:me/xSubstituters
Section titled “Substituters”The substituters field is a map of Nix binary cache URL to its trusted
public key. These are fed into the spindle’s read proxy, so the guest
can substitute prebuilt paths from them instead of building everything
from scratch.
substituters: https://nix-community.cachix.org: "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="Services and virtualisation
Section titled “Services and virtualisation”The services and virtualisation fields are passed straight through
to NixOS. Anything you could write under services.* or
virtualisation.* in a NixOS configuration, you can write here, and
it’s brought up before any of your steps run.
As a convenience, true works as shorthand for .enable = true
anywhere an enable option exists (e.g. virtualisation.docker: true).
services: postgresql: enable: true ensureDatabases: ["spindle-workflow"] ensureUsers: - name: spindle-workflow ensureDBOwnership: true
virtualisation: docker: trueDebugging a failed run
Section titled “Debugging a failed run”If the operator enabled debug SSH, a microVM whose step fails is kept
alive for a grace period (5 minutes by default). The step’s log ends
with a Debug shell entry containing the exact ssh command. You
need an SSH key with push access to the repository.
Namespace engine
Section titled “Namespace engine”The workflow runs on a fresh Namespace instance in your own workspace. This is done using Workload Federation with the spindle’s OIDC tokens. This way the spindle does not store persistent credentials.
Steps run one after another on the same machine, so files and installed packages persist across the steps. Depending on the OS configuration you pick, workflows either run inside a container or directly on the instance itself:
- On Linux: they run inside a container, specified by
image. Onamd64machines the container gets the machine’s/dev/kvmtoo, so steps can boot virtual machines of their own. - On macOS: they run on the machine itself
The basic workflow configuration fields you need to know about are:
# this is required to run the workflow on namespaceengine: namespace
# namespace specific configuration fieldsnamespace: # your workspace identifier, required workspace: tenant_2dlq9rc32sn20
# machine configuration machine: linux/amd64:2x4
# base "image", mostly for macos versions selectors: [macos.version=27.x]
# install nix nix: false
# whether to enable kvm, linux/amd64 only kvm: true
# cache volume configuratoin cache: # GB per cache volume size: 20
# keep /nix between runs nix: true
# keep pulled images, linux only images: true
# choose the base image to run workflows on linuximage: docker.io/nixos/nix:latest
# dependencies to install, these are specified as nix package identifiersdependencies: [go, "unstable#zig"]
# directories to cache across runscache: - key: go paths: [/tangled/home/.cache/go-build]Each field is explained in more detail below.
Image and dependencies
Section titled “Image and dependencies”On Linux, image is any OCI image Namespace can pull. Without it the
spindle’s default image is used. The image needs bash and git, for
the checkout and the steps, and coreutils’ chroot. If you select an
image without these tools, it will fail.
macOS machines take no image; pick a macOS base with
selectors instead.
dependencies is a list of Nix packages installed before your steps, as
on the microVM engine. A bare name like go comes
from nixpkgs, and flakeref#attr takes a package from any flake. On
Linux it requires Nix. The default spindle image comes with nix, but if
your selected image does not, then set namespace.nix: true to install it.
Trusting the spindle
Section titled “Trusting the spindle”Once per repo, the owner of the workspace’s needs to run the following:
nsc auth trust-relationships add \ --issuer https://tokens.spindle.tangled.network \ --subject-match 'did:plc:yourrepodid:*:engine:namespace' \ --audience federation.namespaceapis.com \ --grant '{"resource_type":"instance","resource_id":"*","actions":["create","get","wait","destroy","exec"]}'--issueris your spindle’s OIDC issuer.--subject-matchis your repo’s DID, then:*for any branch or:refs/heads/mainfor one, then:engine:namespace.--grantlets the run’s token manage instances and nothing else in the workspace.
Workspace and machine
Section titled “Workspace and machine”engine: namespacenamespace: workspace: tenant_2dlq9rc32sn20 machine: linux/arm64:4x8image: docker.io/nixos/nix:latestdependencies: [go]steps: - name: test command: go test ./...engine: namespacenamespace: workspace: tenant_2dlq9rc32sn20 machine: macos/arm64:6x14 selectors: [macos.version=26.x, image.with=xcode-26]steps: - name: test command: xcodebuild test -scheme Appworkspace(required) is the workspace’s ID, you can grab this by runningnsc workspace describe, “Tenant ID” is your workspace’s ID.machineisos/arch:CPUxGB, as innsc create --machine_type. Workflows run onlinuxandmacos. The exact architectures and machine configurations depend on your workspace. If unspecified,linux/amd64:2x4is typically selected.selectorsis a list ofname=valuepairs that pick the machine’s base image, such asmacos.version=27.xorimage.with=xcode-26. See Namespace’s base image selection.nix: trueinstalls Nixkvmgives the container access to the machine’s/dev/kvm. It’s on by default forlinux/amd64and can be turned off withkvm: false. On all other OS/arch configurations, this is not present.
Caching
Section titled “Caching”On the namespace engine, caches are Namespace cache volumes in your own workspace, not archives the spindle stores. There are three kinds, and a workflow can use any of them:
engine: namespacenamespace: workspace: tenant_2dlq9rc32sn20 machine: linux/amd64:4x8 nix: true cache: size: 20 nix: true images: true
image: docker.io/library/golang:1.27dependencies: [nodejs]cache: - key: go hash: [go.sum] fallback: true paths: - /tangled/home/.cache/go-build - /tangled/home/go/pkg/modnamespace.cache.nixputs/nixon its own volume, and installs Nix onto it if it isn’t there yet. Later runs start with the store earlier runs left, so nothing they built or downloaded is fetched or built again.namespace.cache.imageskeeps the images Namespace pulls for this repository’s Linux runs.namespace.cache.size: size of each volume in GB.cachekeeps directories, with the same fields as on the other engines. The entries share one volume, mounted at/tangled/cacheon Linux and/Volumes/tangled-cacheon macOS.
On Linux, Namespace keeps what a run wrote when the run succeeds. When
it fails or times out, it’s kept only if every cache entry has when: always, or if the workflow caches only /nix and images. A canceled
empties a cache, so nothing gets saved there. On macOS, Namespace keeps
the volumes regardless of hwo the run terminates.
Limitations of the cache: Namespace keeps each volume on the same machine that wrote to that cache, and each run gets the newest copy of the cache, on the machine it lands on. This means that rarely used machines or the first multiple runs of a workflow may not hit the cache at all! As you run more workflows, your hit rate will improve.
Dummy engine
Section titled “Dummy engine”engine: dummy accepts steps and environment and doesn’t execute
anything. It exists for testing spindle itself.