Tutorial - User Guide¶

This tutorial shows you how to use Satay, one feature at a time. It is written to be read in order: each page assumes the page before it and adds a single idea.

You will start by killing a running workflow and watching it resume without redoing the work that already finished. Then timers, external events, fan-out, and the rule that keeps all of it correct. By the end you will have a test that crashes a workflow on purpose and skips a fourteen-day sleep in under a tenth of a second.

Every code block on these pages was executed to produce the output shown underneath it.

Install¶

pip install satay

Or with uv, which is what the project itself uses:

uv venv
source .venv/bin/activate      # .venv\Scripts\activate on Windows
uv pip install satay

Either way you get exactly one package:

$ pip list
Package Version
------- -------
pip     26.2
satay   0.1.0

The core install is dependency-free. That is the packaging promise, and it is why you can embed Satay in an application without dragging FastAPI, uvicorn, and a JavaScript bundle into production. The debugger and the HTTP API are a separate opt-in:

pip install 'satay[studio]'     # adds fastapi, uvicorn, pydantic, typer

Check the CLI landed:

$ satay --help
usage: satay [-h] {runs,dev} ...

Satay Runtime — local-first durable execution (core CLI).

positional arguments:
  {runs,dev}
    runs      Inspect durable runs.
    dev       (studio extra) Boot the local dev stack; --app MODULE imports
              your workflows.

options:
  -h, --help  show this help message and exit

Pin the version

Every page in this tutorial was written and executed against 0.1.0, the current release. Satay is at 0.x: there is no deprecation policy yet and the public API can still move, so pin the exact version in anything you build.

pip install 'satay[studio]==0.1.0'

Limits lists what is deliberately missing.

Requirements¶

Python 3.12 or 3.13. Linux and macOS are first class. Windows is best effort: the cross-process data-directory lock uses POSIX flock and degrades to a no-op elsewhere. SQLite on a network filesystem is not supported.

The Pages, in Order¶

Page	What it adds
First Steps	Two tasks, one workflow, a real crash, and a resume.
Concepts	The journal, replay from the top, and how a call keeps its identity.
The Determinism Rule	The one rule that makes replay work, and what breaking it looks like.
The Five Primitives	`sleep`, `wait_for_event`/`send_event`, `map`, `gather`, `start_child`.
Testing Workflows	The manual clock, the seeded RNG, and crashing a workflow in a test.

Then the Cookbook¶

The tutorial builds small pieces to explain one idea at a time. The Cookbook does the opposite: each recipe is a complete program you can run, with the journal or Studio output that proves it worked. Go there once you know what you want to build.

Lookup material sits in Guarantees and Studio and satay dev. Read those when a question comes up, not front to back.

Start Here¶

First Steps takes about ten minutes and gets you the crash-and-resume story first hand.