<!-- agents: TestFlows Machine docs, one section. Index: https://testflows.com/docs/machine.md -->

# What is it?

**Machine** is a place to run your programs where nothing is left to chance.
It controls time, interrupts, random numbers and input from devices, and it
records all of them while your program runs. Replay the recording and the
program does exactly what it did the first time, instruction for instruction.

That gives you three things to work with:

* **Record.** Every run keeps a log of everything that could have turned out differently.
* **Replay.** Play the log back and the run repeats itself. If it failed once, it fails every time.
* **Branch.** Stop at any point, branch from it, and try something else. The original run stays as it was.

If you have ever chased a test that fails one run in fifty, you know why this
is handy. Record the failing run once, then replay it as often as you need.

You work with Machine through a client called `machine`, or from Python using
the [SDK](python-sdk.md). Both do the same things. This page starts with the
client and ends with the SDK. To begin, [install the client](getting-started.md#the-client). It is
one command.

# Concepts

There are only a few of them, and the rest of this page builds on them.

**Disk.** What a machine boots. It is your program (or a whole application)
packaged with a small Linux system. You build one with `machine disks build`.

**Session.** A machine in the cloud that you create. It has its own CPUs, memory
and storage, and your runs live inside it. A session costs from the moment you
create it until you delete it, so delete it when you are done.

**Run.** A virtual machine booting a disk inside a session. Every run has a
name. Nearly everything in this page is something you do to a run.

**Entry.** A run writes its history as a numbered log. Each item in the log is
an entry, so entry 42 is always the same point in that run.

**Checkpoint.** A saved copy of the whole machine at one point in the log. Every
run has checkpoint 0, taken at boot, and you can add your own and name them.

**Branch.** A run that starts from another run at some point. It shares history
with its parent up to that point and has its own after that. You create one
with `machine fork` or `machine go`. Runs that grow out of one another form a
tree.

**Mark.** A second name for a branch, given after the fact. The generated name
says where a branch started. A mark says what it turned out to be,
like `crashed`.

## Points

A lot of commands take a point, which is a place in a run's history. You can
name one in several ways.

| Point | Means |
|---|---|
| `^booted` | the checkpoint named `booted` |
| `#42` | entry 42 |
| `1.5s` | a time on the guest's clock |
| `-10ms` | ten milliseconds of guest time back from where the run is now |
| `now` | where the run is now |
| `parent` | the point this run branched from |
| `root` | the start of the tree |
| `%crashed` | the branch marked `crashed` |

A branch can only start from a checkpoint. `machine go` takes any of these
points, and if the one you name isn't a checkpoint, it starts the branch at the
nearest checkpoint before it and replays the rest of the way for you.