---
title: What are spindles?
description: Spindles are Tangled's CI runners, built atop Nix and the AT Protocol.
sidebar:
  order: 0
---

Spindle is Tangled's continuous integration runner, built atop Nix
and the AT Protocol. Like knots, spindles are self-hostable by
design: you can use a managed spindle, or run your own and point
your repositories at it.

A spindle subscribes to repository events. When you push code or
open a pull request, the knot hosting the repository emits an
event; the spindle picks it up, reads the [workflow
manifests](/spindles/workflows/) in `.tangled/workflows/`, spins
up an execution environment, and runs your steps. Status and logs
stream back over websockets, so you can watch runs live from the
appview (or [tail them over SSH](https://blog.tangled.org/ssh)).

Workflow manifests are intentionally simple. There is no
"marketplace" of workflows or complex job orchestration —
dependencies are just [nixpkgs](https://search.nixos.org)
packages, listed by name, with no toolchain setup.

## Engines

Spindles can execute workflows on two engines:

- **nixery** runs each step in an OCI container (Docker, or
  Podman with Docker compatibility). Images are built on the fly
  by [Nixery](https://nixery.dev), which turns a list of Nix
  packages into a layered container image.
- **microVM** runs the whole workflow inside a QEMU microVM — a
  VM with the boring parts removed: no BIOS, no PCI bus to probe,
  no emulated graphics. Boot times are fast, isolation is strong
  (isolated network namespaces, DNS filtering, blackholed
  special-use IP ranges), and workflows can declare NixOS
  configuration directly — `services.postgresql.enable: true` gets
  you a running database. Existing nixery workflows port over by
  changing `engine: nixery` to `engine: microvm`.

Secrets use AT Protocol [service
auth](https://atproto.com/specs/xrpc#inter-service-authentication-jwt):
the appview makes a signed request using the logged-in user's DID
key, and the spindle verifies the signature against the public key
in their DID document. No shared secrets between services.

## Where to go next

- [Workflows](/spindles/workflows/) — the manifest format:
  triggers, dependencies, engines, and example recipes
- [Self-hosting a spindle](/spindles/self-hosting/) — run your own
  CI on your own machines
- [Secrets with OpenBao](/spindles/secrets/) — back spindle
  secrets with OpenBao instead of SQLite
- [Architecture](/spindles/architecture/) — how spindle consumes
  records and executes pipelines

## Further reading

- [Introducing spindle](https://blog.tangled.org/ci) — the
  announcement post
- [Tangled CI runs on microVMs](https://blog.tangled.org/spindle-microvm)
  — a deep dive into the QEMU-based microVM engine
