# Engines

> 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`](/docs/spindles/workflows/#engine) field, and each workflow in a pipeline can pick a different one.

The [common fields](/docs/spindles/workflows/) 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](https://namespace.so) 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.

```yaml
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](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-registry-add).

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`:

```yaml
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

```yaml
# .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](https://tangled.org/@tangled.org/core/blob/master/.tangled/workflows/build.yml).

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

```yaml
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:

```yaml
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`.

### 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`](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-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.

```yaml
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`:

```yaml
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.

```yaml
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`).

```yaml
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](https://namespace.so) instance in your own workspace. This is done using [Workload Federation](https://namespace.so/docs/federation) with the spindle’s [OIDC tokens](/docs/spindles/oidc/). 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:

```yaml
# 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`](#workspace-and-machine) instead.

`dependencies` is a list of Nix packages installed before your steps, as on the [microVM engine](#dependencies-1). 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:

```sh
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](/docs/spindles/oidc/#choose-the-issuer-url).
* `--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.

> **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](/docs/spindles/oidc/#for-operators) covers turning it on.

### Workspace and machine

```yaml
engine: namespace
namespace:
  workspace: tenant_2dlq9rc32sn20
  machine: linux/arm64:4x8
image: docker.io/nixos/nix:latest
dependencies: [go]
steps:
  - name: test
    command: go test ./...
```

```yaml
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](https://namespace.so/docs/architecture/compute/macos#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.

### Caching

On the namespace engine, caches are [Namespace cache volumes](https://namespace.so/docs/architecture/storage/cache-volumes) in your own workspace, not archives the spindle stores. There are three kinds, and a workflow can use any of them:

```yaml
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](/docs/spindles/workflows/#cache). 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.

## Dummy engine

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