title: Engines description: The engines a spindle runs workflows on, how they differ, and the fields each one adds to a workflow. #
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 #
Each step runs in a fresh container built by Nixery from your dependencies. The workspace is shared between steps; nothing else is.
engine: nixery
dependencies:
nixpkgs: [go]
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_pkg
These dependencies are now available to every step.
Complete nixery workflow #
# .tangled/workflows/build.yml
when:
- event: ["push", "manual"]
branch: ["main", "develop"]
- event: ["pull_request"]
branch: ["main"]
engine: "nixery"
# using the default values
clone:
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 #
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: microvm
image: nixos
dependencies: [go, "unstable#zig", "github:nixos/nixpkgs#hello"]
registry:
nixpkgs: github:nixos/nixpkgs/nixos-unstable
substituters:
https://nix-community.cachix.org: "nix-community.cachix.org-1:..."
services:
postgresql: true
virtualisation:
docker: true
Image #
A workflow picks the image to boot with the top-level image field:
engine: microvm
image: nixos
There 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 #
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#hello
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/x
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 #
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: true
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 #
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 namespace
engine: namespace
# namespace specific configuration fields
namespace:
# 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 linux
image: docker.io/nixos/nix:latest
# dependencies to install, these are specified as nix package identifiers
dependencies: [go, "unstable#zig"]
# directories to cache across runs
cache:
- key: go
paths: [/tangled/home/.cache/go-build]
Each field is explained in more detail below.
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 #
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.
:::note
For self-hosted spindles, --issuer needs to be configured to point to
your spindle; perhaps something like https://tokens.spindle.example.com.
Setting up OIDC covers turning it on.
::::
Workspace and machine #
engine: namespace
namespace:
workspace: tenant_2dlq9rc32sn20
machine: linux/arm64:4x8
image: docker.io/nixos/nix:latest
dependencies: [go]
steps:
- name: test
command: go test ./...
engine: namespace
namespace:
workspace: tenant_2dlq9rc32sn20
machine: macos/arm64:6x14
selectors: [macos.version=26.x, image.with=xcode-26]
steps:
- name: test
command: xcodebuild test -scheme App
workspace(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 #
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: namespace
namespace:
workspace: tenant_2dlq9rc32sn20
machine: linux/amd64:4x8
nix: true
cache:
size: 20
nix: true
images: true
image: docker.io/library/golang:1.27
dependencies: [nodejs]
cache:
- key: go
hash: [go.sum]
fallback: true
paths:
- /tangled/home/.cache/go-build
- /tangled/home/go/pkg/mod
namespace.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 #
engine: dummy accepts steps and environment and doesn't execute
anything. It exists for testing spindle itself.