# Engine
URL: https://lsd.tools/docs/api-engine
Updated: 2026-07-17

`Engine` is the runtime that executes pipelines outside the desktop — in a script, a test, or CI —
on the exact engine the desktop uses. It owns the workspace, the event bus, and the entity
collection, and orchestrates runs in dependency order. Construct it three ways — ephemeral
(in-memory), from a `.lsd` file, or from a project directory — then wire steps and call
[`run`](/docs/api-engine-run); runs are cached, so `resume=True` reuses unchanged steps.

## Usage

```python
from lsdtools import Engine

result = Engine().run(top(numbers(count=6), limit=3))
result.output.print()
# → the final Table, with each step cached
```

Three ways to anchor an engine to a project:

```python
Engine()               # ephemeral: in-memory, nothing persisted
Engine("survey.lsd")   # a single-file project
Engine("project_dir")  # a directory-backed project
```

## Entities run, views show

An `Engine` holds two kinds of thing, and `add` takes either: **entities you run** and **views you
show**. The two verbs mirror each other exactly — `run_all()` executes every entity, `show()` presents
every attached view:

```python
from lsdtools import Engine, views

engine = Engine()
engine.add(drillholes(collar="collars.csv", survey="survey.csv"))   # an entity → run
grid = views.table(title="Assays").watch("drillholes")              # a view that follows it
engine.add(grid)                                                    # a view → show

engine.run_all()      # entities run in dependency order; the view holds the output
engine.show()         # present every attached view (a window, or console text when headless)
```

- `engine.add(entity)` attaches a pipeline; `engine.add(view)` attaches a
  [`View`](/docs/api-view). Attaching a view also subscribes its
  [`watch`](/docs/api-view-watch) links to the bus, so a watch declared before either was added
  resolves right then.
- `engine.views` lists the attached views; `engine.view(name)` fetches one; `engine.remove_view(v)`
  detaches it.
- `show(mode="auto", title=None, block=True)` opens one window hosting all views when a front-end is
  loaded, else prints each view's titled text rendering. `run_all()` / `save()` / `load()` are
  documented on their own pages below.

A [deliver step that returns a `ViewerPayload`](/docs/tools-rendering) is routed to whatever view
watches its entity — so a run can populate a viewer with no extra wiring.

## Where to start

**Learn** — [Node variants](/docs/tools-variants) · [Tables & data flow](/docs/tools-tables)

**Examples** — [Your first tool](/docs/ex-hello-tool) · [Multi-output mesh](/docs/ex-multi-output)

**API** — [RunResult](/docs/api-runresult) · [Table](/docs/api-table) · [Tool](/docs/api-tool) · [Runtime](/docs/api-runtime)