Skip to content

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.

EngineRuns onUse it for
nixeryA fresh Docker or Podman container for each step, with the image built from your Nix packages by NixeryShort, stateless builds and tests.
microvmThe whole workflow inside its own microVM, with a choice of imagesStronger isolation, NixOS services such as PostgreSQL, Docker inside CI.
namespaceA machine in your own Namespace workspace, Linux or macOSIf 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.

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]

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.

# .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.

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

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. The dependencies, services, virtualisation, registry and substituters fields 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.

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

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

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="

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

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.

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. On amd64 machines the container gets the machine’s /dev/kvm too, 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.

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.

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"]}'
  • --issuer is your spindle’s OIDC issuer.
  • --subject-match is your repo’s DID, then :* for any branch or :refs/heads/main for one, then :engine:namespace.
  • --grant lets the run’s token manage instances and nothing else in the workspace.
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 running nsc workspace describe, “Tenant ID” is your workspace’s ID.
  • machine is os/arch:CPUxGB, as in nsc create --machine_type. Workflows run on linux and macos. The exact architectures and machine configurations depend on your workspace. If unspecified, linux/amd64:2x4 is typically selected.
  • selectors is a list of name=value pairs that pick the machine’s base image, such as macos.version=27.x or image.with=xcode-26. See Namespace’s base image selection.
  • nix: true installs Nix
  • kvm gives the container access to the machine’s /dev/kvm. It’s on by default for linux/amd64 and can be turned off with kvm: false. On all other OS/arch configurations, this is not present.

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.nix puts /nix on 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.images keeps the images Namespace pulls for this repository’s Linux runs.
  • namespace.cache.size: size of each volume in GB.
  • cache keeps directories, with the same fields as on the other engines. The entries share one volume, mounted at /tangled/cache on Linux and /Volumes/tangled-cache on 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.

engine: dummy accepts steps and environment and doesn’t execute anything. It exists for testing spindle itself.