# morca

> A pipeline orchestrator written in Mojo: pipelines are Mojo code checked by the compiler, Dista runs their steps across a cluster, and the data lives in Iceberg tables with every run recorded in Postgres. No Python or JVM in the path.

Every page below is the Markdown twin of a page on https://morca.dev: the same URL with .md appended (the home page is /index.md). /llms-full.txt has them all in one file. The Mojo libraries morca is built on (Iceberg, Parquet, codecs, Postgres, Kubernetes) are documented on https://magmalake.dev.

## Start here

- [Pipeline orchestration in Mojo](https://morca.dev/index.md): morca is a pipeline orchestrator written in Mojo: pipelines checked by the compiler, steps run across a cluster by Dista, over Iceberg tables, with every run recorded in Postgres so it resumes and retries.

## Getting started

- [Getting started](https://morca.dev/getting-started.md): Build a lake of GitHub activity with morca: see it running, then build it by handing a coding agent the skills and a prompt, or step by step from pixi and mojoshelf to morca pipelines, a flare console, a local run and a deploy to AWS.
- [Let an agent build it — Getting started](https://morca.dev/getting-started/agent.md): Let a coding agent build a lake of GitHub activity with morca: install the skills for Mojo, morca, mojoshelf and AWS, and give it the prompt that built the census.
- [Develop locally — Getting started](https://morca.dev/getting-started/develop.md): Change morca, Dista or the census and run it on a laptop before any release or deploy: the checkouts to lay out side by side, morca's examples and test suites, the census on a local warehouse, testing a library change inside the census, and the caveats that bite locally.
- [Maintain and release — Getting started](https://morca.dev/getting-started/maintain.md): Run morca without an assistant: the pull-request routine and the known flaky tests, changelog fragments and database migrations, releasing morca and dista, operating morca and the census in production, and where everything lives.
- [Step by step — Getting started](https://morca.dev/getting-started/step-by-step.md): Build a lake of GitHub activity on morca by hand: pixi and mojoshelf, a project with morca in it, the pipelines and the flare console of the census, a local run, and a deploy to AWS with orca aws.

## Docs

- [Docs · morca](https://morca.dev/docs.md): How to use morca: installing it, then writing a pipeline, its command line, scheduling and running it here or on Kubernetes or EC2, the web UI, debugging failed runs, remote workers, deploying, and the resource roadmap, each on a page of its own.
- [Writing a pipeline · morca docs](https://morca.dev/docs/build.md): Writing a morca pipeline: steps and pipelines checked by the compiler, partitions by date or by name, cron schedules in time zones, keyed pipelines, Iceberg tables and datasets, sensors, Dista inside steps, and building the pipeline binaries and the orca command.
- [The command line · morca docs](https://morca.dev/docs/cli.md): morca's command line: the two binaries you run, a pipeline's own and the orca command; the commands you type on each; running them from a laptop against the deployed UI with orca login and --remote; the commands orca runs for you and you'll see in its logs; exit codes; and how the same binary acts on this machine or on AWS through its environment.
- [orca.toml · morca docs](https://morca.dev/docs/config.md): The orca.toml reference: its tables, every key of [defaults] and [pipelines.<name>] with its type and default, worker pools in [pools.<name>], fills, how many runs at once, requests and grants, what orca register refuses, which file it reads, and orca config show, check and export.
- [Debugging failures · morca docs](https://morca.dev/docs/debug.md): Debugging a failed morca run: where its errors and logs are, in the UI and in S3, what a raised error carries and how to add context to it, crash stack dumps and how the image symbolizes them, reproducing a partition locally, and resuming or rerunning it.
- [Deploying · morca docs](https://morca.dev/docs/deploy.md): Deploying morca on one Hetzner server: the scripts from a release, deploys that replace only what changed, the UI and apps without downtime, overlapping schedulers so a deploy doesn't pause runs, rollbacks, settings from hetzner.env, secrets encrypted with SOPS, rescaling the server, and what comes next.
- [Features · morca docs](https://morca.dev/docs/features.md): Everything morca does, on one page: the major features first, each with a paragraph and a link to where it is explained, then the smaller ones by area. As of morca 0.24.0.
- [Files and HTTP API · morca docs](https://morca.dev/docs/formats.md): The files and interfaces morca reads and writes besides orca.toml: the UI's pages and their JSON, the actions, the worker API, the layout of logs, timelines and machine metrics under ORCA_LOGS, the metrics' JSON lines, the orca schema in Postgres and its additive migrations, and the environment variables of the scheduler, the UI, workers and runs.
- [Alerts and the watchdog · morca docs](https://morca.dev/docs/monitoring.md): Watching a morca stack: the alerts it pushes to your phone through ntfy and how to set them up, the watchdog that pauses pipelines when something leaves a sane range, the machine metrics it samples, Ops › Alerts, Control and Pools, the Prometheus gauges, and where to look first when a run seems stuck.
- [Pools and autoscaling · morca docs](https://morca.dev/docs/pools.md): Worker pools in morca: workers that claim a pool's runs over HTTPS, pools that morca grows and shrinks itself on Hetzner or EC2, what counts as demand, how a machine boots and is removed, out-of-stock and quota fallback, the private network, and one run spread over several machines with a dista cluster of its own.
- [Roadmap · morca docs](https://morca.dev/docs/roadmap.md): morca's resource roadmap in two halves, after Google's Autopilot: vertical scaling, the right size for each run (measuring its memory and CPU, admitting it by what it needs, containing an overrun to its own run, back pressure inside it), and horizontal scaling, the right number of runs and machines, with milestones, the issues for each step and the papers behind them.
- [Scheduling and running · morca docs](https://morca.dev/docs/run.md): Scheduling and running morca pipelines: the scheduler and its fires, retries and limits, runs on this machine, on Kubernetes or on EC2, remote workers and fills, runs sized by memory and CPU, held off by memory pressure and contained in cgroups, runs recorded and resumed in Postgres, deploys and rollbacks, logs and machine metrics, lineage and rebuilds, every environment variable, and what happens when things fail.
- [Sizing and scaling · morca docs](https://morca.dev/docs/scaling.md): Sizing and scaling morca's runs: requests of CPUs and memory, learned requests, grants and admission, a cgroup per run, memory pressure, max_runs and fill_max_runs set to auto, worker pools that grow themselves, one run over several machines, and which setting to change when.
- [Tokens and secrets · morca docs](https://morca.dev/docs/security.md): Who and what can act on a morca stack: UI logins and API tokens, worker tokens scoped to a pool, the per-machine boot token of an autoscaled pool, the per-run dista cluster token, pipeline secrets that specs name but never carry, SOPS on deploy, and where the Hetzner, AWS and registry credentials live.
- [The UI · morca docs](https://morca.dev/docs/ui.md): morca's web UI: its pages and their JSON, coverage in one number, filtering runs and acting on many at once, the actions and the dialog they ask in, logins and sessions, a run's page with its cards, steps and machines, and code on hover.
- [Upgrades and rollbacks · morca docs](https://morca.dev/docs/upgrades.md): Upgrading morca: releases and the images built from them, deploying a new image with its upgrade steps and the check after it, additive migrations so an older image runs on a newer schema, rollbacks without restoring the database, floor-raising migrations, backups and restores, two schedulers overlapping during a deploy, and keeping workers on the server's tag.
- [Remote workers · morca docs](https://morca.dev/docs/workers.md): Running some of morca's pipelines on a second machine: what a remote worker is, a worker token, a placement, the worker container that needs only outbound HTTPS, fills on a pool, what happens when a worker dies, deploys, the census as the example, and the limits.

## Dista

- [Dista: distributed tasks for Mojo](https://morca.dev/dista.md): Dista runs Mojo functions across a cluster: declare a task, call it, and the work spreads over the machines, with results staying where they were computed. Early, open source, and measured against Ray and Rust.
- [Docs · Dista](https://morca.dev/dista/docs.md): How to use Dista: installing it and a first program, then tasks and results, shuffles, actors, running a cluster, the dista command, failure and recovery, and tuning, each on a page of its own.
- [Actors and checkpoints · Dista docs](https://morca.dev/dista/docs/actors.md): Dista's actors: state on a worker of its own with methods called in order, handles passed to tasks and other actors, restarts when a worker dies, checkpoints to a directory or S3, and actors moving off a draining worker.
- [The dista command · Dista docs](https://morca.dev/dista/docs/cli.md): The dista command: a generic head, status and status --json, drain, scale --once, timeline and stop; Prometheus metrics on the head and workers; and the task timeline in Chrome's trace format.
- [Running a cluster · Dista docs](https://morca.dev/dista/docs/cluster.md): Running Dista: local mode, roles from the environment, the generic dista head, Kubernetes manifests and EC2, draining a worker on SIGTERM or by name, autoscaling with dista scale, and every environment variable.
- [Failure and recovery · Dista docs](https://morca.dev/dista/docs/failures.md): What Dista does when things fail: a task that raises, a worker that dies or goes silent, a peer that can't be reached, a task that runs too long, a driver that leaves, and a head that restarts; and how it's tested.
- [Shuffles · Dista docs](https://morca.dev/dista/docs/shuffles.md): Shuffles in Dista: TaskMany for a task with several results, TaskWith for a value beside other tasks' results, partitioning again what earlier tasks made, placement by data location, and spilling past the node store.
- [Tasks and results · Dista docs](https://morca.dev/dista/docs/tasks.md): Dista's tasks: declaring them with up to three arguments, where their results live, freeing results with take and release, tasks on other tasks' results, cancelling and waiting with a timeout, and what can cross the wire.
- [Tuning · Dista docs](https://morca.dev/dista/docs/tuning.md): Tuning Dista: tasks in flight per worker, backpressure limits on the head's queue and a slow driver, the node store and spilling, the memory a driver's results hold, large results in parts, and logging a task's inputs.
- [Performance · Dista](https://morca.dev/dista/performance.md): Dista measured against Ray and Rust on 1.4 billion taxi trips in S3: distributed runs on 3 to 12 nodes, a shuffle against Ray, a task timeline, single-process references, image sizes, and how to reproduce every number.

## Blog

- [Writing](https://morca.dev/blog.md): Notes from building morca: pipelines in Mojo, the census they run, and what the measurements say.
- [Mojourney, a census of Mojo on GitHub](https://morca.dev/blog/introducing-mojourney.md): Every public GitHub repo with Mojo in it, found from GH Archive, with its full git history read. Repos, commits, lines of Mojo and the Mojo versions they pin, over time.
- [morca, a pipeline orchestrator in Mojo](https://morca.dev/blog/introducing-orca.md): Pipelines written as Mojo code and checked by the compiler, over Iceberg tables, scheduled, sensed and backfilled by one scheduler, with remote workers that need only HTTPS. It runs the Mojourney census on one small server.

## Optional

API references:

- [Dista API](https://morca.dev/dista/api.md): The API of Dista: the dista package's modules, structs, traits and functions, with their signatures and docstrings.
- [Dista API: dista.checkpoint](https://morca.dev/dista/api/checkpoint.md): dista.checkpoint, in Dista's API: Where actor checkpoints live: objects under `DISTA_CHECKPOINT_URI`.
- [Dista API: dista.client](https://morca.dev/dista/api/client.md): dista.client, in Dista's API: The driver's side of the protocol: submitting tasks, calling actors and getting results back from the head.
- [Dista API: dista.codec](https://morca.dev/dista/api/codec.md): dista.codec, in Dista's API: Turning task arguments and results into bytes and back.
- [Dista API: dista.conn](https://morca.dev/dista/api/conn.md): dista.conn, in Dista's API: A non-blocking framed connection, for the head's event loop.
- [Dista API: dista.executors](https://morca.dev/dista/api/executors.md): dista.executors, in Dista's API: A worker's task slots: threads that run tasks while its loop keeps serving.
- [Dista API: dista.frame](https://morca.dev/dista/api/frame.md): dista.frame, in Dista's API: Length-prefixed messages between drivers, the head and workers.
- [Dista API: dista.head](https://morca.dev/dista/api/head.md): dista.head, in Dista's API: The head: one event loop that schedules every driver's tasks onto workers.
- [Dista API: dista.metrics](https://morca.dev/dista/api/metrics.md): dista.metrics, in Dista's API: Prometheus metrics: counters and a histogram, and the `/metrics` page.
- [Dista API: dista.runtime](https://morca.dev/dista/api/runtime.md): dista.runtime, in Dista's API: The runtime: one binary that runs as driver, head or worker.
- [Dista API: dista.scale](https://morca.dev/dista/api/scale.md): dista.scale, in Dista's API: How many workers a running job wants: a policy over the head's demand.
- [Dista API: dista.seq](https://morca.dev/dista/api/seq.md): dista.seq, in Dista's API: `Seq[T]`: a list that goes through the codec.
- [Dista API: dista.signals](https://morca.dev/dista/api/signals.md): dista.signals, in Dista's API: SIGTERM: the head exits, and a worker drains, even as a container's PID 1.
- [Dista API: dista.socket](https://morca.dev/dista/api/socket.md): dista.socket, in Dista's API: IPv4 TCP and process control over libc.
- [Dista API: dista.store](https://morca.dev/dista/api/store.md): dista.store, in Dista's API: The node-local object store: large results in shared mappings.
- [Dista API: dista.task](https://morca.dev/dista/api/task.md): dista.task, in Dista's API: Tasks: remote functions, their IDs, and how a worker runs one.
- [Dista API: dista.worker](https://morca.dev/dista/api/worker.md): dista.worker, in Dista's API: A worker: runs tasks for the head and serves its results to peers.
- [morca API](https://morca.dev/docs/api.md): The API of morca: the orca package's modules, structs, traits and functions, with their signatures and docstrings.
- [morca API: orca.actions](https://morca.dev/docs/api/actions.md): orca.actions, in morca's API: What `orca ui` does to runs: each action is rows in Postgres that the scheduler, or the run's own process, acts on.
- [morca API: orca.admission](https://morca.dev/docs/api/admission.md): orca.admission, in morca's API: Admission by memory pressure, where it shows (#202): each host's newest reading in `orca.pressure`, for Ops › Control, `/api/workers`, `/metrics`, `orca status` and the home and runs pages, and the alert when a hold has nothing of orca's to wait for.
- [morca API: orca.alerts](https://morca.dev/docs/api/alerts.md): orca.alerts, in morca's API: What the scheduler raises alerts about (`orca.notify`, #184), each decided where the data is and sent through `orca.notify.alert`:
- [morca API: orca.api](https://morca.dev/docs/api/api.md): orca.api, in morca's API: orca's JSON API: what `orca --remote`, `orca worker` and `orca.http_store.HttpStore` talk to. A page's JSON is built from the same read models as its HTML (`orca.views`); these are the writers, and the endpoints that are JSON only.
- [morca API: orca.api.actions](https://morca.dev/docs/api/api/actions.md): orca.api.actions, in morca's API: The actions: each a `POST` of a form (or of JSON, from `orca --remote`) that changes something, through `orca.actions`.
- [morca API: orca.api.datasets](https://morca.dev/docs/api/api/datasets.md): orca.api.datasets, in morca's API: Rebuilds and lineage as JSON.
- [morca API: orca.api.ops](https://morca.dev/docs/api/api/ops.md): orca.api.ops, in morca's API: The Ops pages' JSON endpoints: `/api/fleet`, `/api/workers`, `/api/system`, `/api/gantt` and `/api/watchdog` (`/api/pools` is the Pools page's, `orca.ui.pools`). `/api/fleet` and `/api/workers` are what the Fleet and Workers pages were, before Pools replaced them.
- [morca API: orca.api.pipelines](https://morca.dev/docs/api/api/pipelines.md): orca.api.pipelines, in morca's API: A pipeline as JSON: its registration (`json_pipeline`), a keyed one's counts and Start runs' preview.
- [morca API: orca.api.runs](https://morca.dev/docs/api/api/runs.md): orca.api.runs, in morca's API: Runs as JSON: a run (`json_run`), a list's page with its cursors, a code version, and a run's machines with their metrics.
- [morca API: orca.api.worker](https://morca.dev/docs/api/api/worker.md): orca.api.worker, in morca's API: The worker API: what `orca worker` (`orca.worker`) and the runs it starts (`orca.http_store.HttpStore`) call, each a `POST` of JSON with `Authorization: Bearer <worker token>`. What each call does is `orca.workers`; this is how a request reaches it.
- [morca API: orca.auth](https://morca.dev/docs/api/auth.md): orca.auth, in morca's API: Who may act in `orca ui`: users with passwords, their sessions, and a record of what each did.
- [morca API: orca.aws](https://morca.dev/docs/api/aws.md): orca.aws, in morca's API: `orca aws`: a project's orca on AWS, with the `aws` and `docker` commands its user already has (`aws login`, or `AWS_PROFILE` for a named profile).
- [morca API: orca.aws_assets](https://morca.dev/docs/api/aws_assets.md): orca.aws_assets, in morca's API: The stack template and the project Dockerfile `orca aws` writes out: deploy/aws/orca.yaml and deploy/project.Dockerfile, embedded by scripts/embed-aws.py. Edit those, then run it; `pixi run test-aws-assets` fails while this is out of date.
- [morca API: orca.aws_replace](https://morca.dev/docs/api/aws_replace.md): orca.aws_replace, in morca's API: `orca aws replace-control`: a blue/green replacement of the stack's control instance by a new one booted from the current template, with the old one's database (DESIGN.md, "Replacing the control instance").
- [morca API: orca.awsec2](https://morca.dev/docs/api/awsec2.md): orca.awsec2, in morca's API: The few EC2 calls the `ec2` runner makes (`orca.ec2`), over objectstore's SigV4 signing and HTTP.
- [morca API: orca.awsjson](https://morca.dev/docs/api/awsjson.md): orca.awsjson, in morca's API: One signed call to an AWS service's JSON API (Secrets Manager's `GetSecretValue`, SSM's `GetParameter`): SigV4 over objectstore's HTTP, with the credentials of the `AWS_*` environment or else the instance role. A low module: `orca.control` and `orca.machines_ec2` both use it.
- [morca API: orca.calendar](https://morca.dev/docs/api/calendar.md): orca.calendar, in morca's API: A dated pipeline's partitions on a calendar: what state each day (or, for a monthly pipeline, month) is in, read from the database alone.
- [morca API: orca.cgroup](https://morca.dev/docs/api/cgroup.md): orca.cgroup, in morca's API: Containment (#201): a cgroup v2 memory limit per run, and retrying bigger after an out-of-memory kill.
- [morca API: orca.chart](https://morca.dev/docs/api/chart.md): orca.chart, in morca's API: Runs per day, drawn as SVG on the server for the home page: one bar a day, stacked by how the runs ended.
- [morca API: orca.civil](https://morca.dev/docs/api/civil.md): orca.civil, in morca's API: Calendar arithmetic: dates to days since 1970-01-01 and back.
- [morca API: orca.cli](https://morca.dev/docs/api/cli.md): orca.cli, in morca's API: `orca_main`: the command line every pipeline binary gets.
- [morca API: orca.command](https://morca.dev/docs/api/command.md): orca.command, in morca's API: The `orca` command: the scheduler, the UI and registration, in a binary that links no pipeline. A project builds its own from two lines:
- [morca API: orca.config](https://morca.dev/docs/api/config.md): orca.config, in morca's API: `orca.toml`: one checked-in file for how each of a project's pipelines runs (#145), read by `orca register` and `orca aws register`.
- [morca API: orca.config_show](https://morca.dev/docs/api/config_show.md): orca.config_show, in morca's API: `orca config show` and `orca config export` (`orca.config`): each pipeline's settings with where each came from, as text, HTML and JSON, and the registered settings written back as an orca.toml.
- [morca API: orca.control](https://morca.dev/docs/api/control.md): orca.control, in morca's API: Placement: where a pipeline's runs run (`orca register --placement`), and the control runner, which runs them on the scheduler's own host.
- [morca API: orca.coverage](https://morca.dev/docs/api/coverage.md): orca.coverage, in morca's API: A pipeline's coverage: one number for how much of it is done, shown on the home page's table, its page's Progress card and in their JSON.
- [morca API: orca.crash](https://morca.dev/docs/api/crash.md): orca.crash, in morca's API: What a crash left in a run's output: the stack dump Mojo's runtime prints on a fatal signal (a segfault, `abort`, a failed bounds check), cut down to a line for the error of the attempt it ended.
- [morca API: orca.cron](https://morca.dev/docs/api/cron.md): orca.cron, in morca's API: Cron expressions, and when they next fire in a time zone.
- [morca API: orca.ctx](https://morca.dev/docs/api/ctx.md): orca.ctx, in morca's API: `Ctx`: what a step gets besides its input.
- [morca API: orca.dag](https://morca.dev/docs/api/dag.md): orca.dag, in morca's API: A pipeline's DAG drawn as SVG, on the server.
- [morca API: orca.day](https://morca.dev/docs/api/day.md): orca.day, in morca's API: `Day`: the partition key of a daily pipeline.
- [morca API: orca.ec2](https://morca.dev/docs/api/ec2.md): orca.ec2, in morca's API: Runs on EC2: a head instance and worker instances per run, started and ended by the scheduler (DESIGN.md, phase 5, PR 5).
- [morca API: orca.estimate](https://morca.dev/docs/api/estimate.md): orca.estimate, in morca's API: How long runs of a pipeline would take, from how long its recent runs took.
- [morca API: orca.expiry](https://morca.dev/docs/api/expiry.md): orca.expiry, in morca's API: Snapshot expiry, the scheduler's half: what orca still needs of a dataset's history, and the binary that does the expiring.
- [morca API: orca.fill](https://morca.dev/docs/api/fill.md): orca.fill, in morca's API: Fills (#155): a pipeline filling its whole partition range by itself, within limits, set in orca.toml (`orca.config`):
- [morca API: orca.fleet](https://morca.dev/docs/api/fleet.md): orca.fleet, in morca's API: The fleet: every machine orca is paying for, as Ops' Pools shows the EC2 ones (`/ops/pools?kind=ec2`, `orca.ui.pools`) and `/api/fleet` has them as JSON.
- [morca API: orca.follow](https://morca.dev/docs/api/follow.md): orca.follow, in morca's API: How far a dated sensor pipeline is behind the datasets it follows.
- [morca API: orca.graph](https://morca.dev/docs/api/graph.md): orca.graph, in morca's API: A directed graph drawn as SVG, on the server: the pipelines and datasets that feed each other, and a snapshot's lineage.
- [morca API: orca.hcloud](https://morca.dev/docs/api/hcloud.md): orca.hcloud, in morca's API: Hetzner Cloud's API, as the pool autoscaler needs it (#267, `orca.pool_scale`): make a server, list a pool's, delete one, and the architecture of a server type.
- [morca API: orca.heartbeat](https://morca.dev/docs/api/heartbeat.md): orca.heartbeat, in morca's API: A run's heartbeat, kept fresh from a thread while the run's steps work.
- [morca API: orca.highlight](https://morca.dev/docs/api/highlight.md): orca.highlight, in morca's API: Mojo source coloured for the UI's code-on-hover (`_PEEK` in `orca.ui.layout`), on the server, with no library: `tokens` splits source into runs of one kind, and `highlight` turns those into HTML lines with a `<span>` per coloured run.
- [morca API: orca.hour](https://morca.dev/docs/api/hour.md): orca.hour, in morca's API: `Hour`: the partition key of an hourly pipeline.
- [morca API: orca.html](https://morca.dev/docs/api/html.md): orca.html, in morca's API: Writing HTML: every value escaped, markup only where it's said to be.
- [morca API: orca.http_store](https://morca.dev/docs/api/http_store.md): orca.http_store, in morca's API: `HttpStore`: a run's state over `orca ui`'s API, for a run on a remote worker (`orca worker`, `orca.worker`), which holds no database credentials.
- [morca API: orca.instances](https://morca.dev/docs/api/instances.md): orca.instances, in morca's API: Scheduler instances: two `orca scheduler`s of different images overlapping on one Postgres during a deploy (docs/overlap.md).
- [morca API: orca.json](https://morca.dev/docs/api/json.md): orca.json, in morca's API: The little JSON orca writes: quoted strings.
- [morca API: orca.key](https://morca.dev/docs/api/key.md): orca.key, in morca's API: `Key`: what a partition key is, whatever it counts.
- [morca API: orca.keyed](https://morca.dev/docs/api/keyed.md): orca.keyed, in morca's API: Keyed partitions: keys that are names, read from a column of a dataset.
- [morca API: orca.kube](https://morca.dev/docs/api/kube.md): orca.kube, in morca's API: Runs on Kubernetes: a dista cluster per run, made and removed by the scheduler (K8S.md).
- [morca API: orca.lineage](https://morca.dev/docs/api/lineage.md): orca.lineage, in morca's API: Lineage: which snapshots a dataset's snapshot was made from, and what was made from it, from the reads and commits every attempt records.
- [morca API: orca.live](https://morca.dev/docs/api/live.md): orca.live, in morca's API: Which runs are live: queued, deferred, or running with their process alive.
- [morca API: orca.locate](https://morca.dev/docs/api/locate.md): orca.locate, in morca's API: Where a pipeline's step functions and dista tasks are defined in its source, so `orca ui` can link each one to its line at the commit a run ran.
- [morca API: orca.logs](https://morca.dev/docs/api/logs.md): orca.logs, in morca's API: Where attempts' logs, drivers' logs and runs' timelines go.
- [morca API: orca.machines](https://morca.dev/docs/api/machines.md): orca.machines, in morca's API: Machines for a worker pool, from whichever provider the pool names (#267): what the autoscaler (`orca.pool_scale`) calls, so it never knows which.
- [morca API: orca.machines_ec2](https://morca.dev/docs/api/machines_ec2.md): orca.machines_ec2, in morca's API: A worker pool's machines on EC2 (#267): `orca.machines.Provider` for a pool with `provider = "ec2"`.
- [morca API: orca.maintain](https://morca.dev/docs/api/maintain.md): orca.maintain, in morca's API: Table maintenance for a project's datasets: snapshot expiry.
- [morca API: orca.metrics](https://morca.dev/docs/api/metrics.md): orca.metrics, in morca's API: A run's machine metrics on its page: the samplers' files (`orca.sample`) read back, their peaks and warnings, and the charts, drawn as SVG on the server like the DAG.
- [morca API: orca.migrations](https://morca.dev/docs/api/migrations.md): orca.migrations, in morca's API: The schema's migrations (`State.migrate` applies them): each version's statements, which versions raise the floor an older binary needs, and the check that an older binary may run on a newer schema. AGENTS.md says how to keep a migration additive.
- [morca API: orca.month](https://morca.dev/docs/api/month.md): orca.month, in morca's API: `Month`: the partition key of a monthly pipeline.
- [morca API: orca.name](https://morca.dev/docs/api/name.md): orca.name, in morca's API: `Name`: the partition key of a keyed pipeline (`orca.keyed`).
- [morca API: orca.notify](https://morca.dev/docs/api/notify.md): orca.notify, in morca's API: Alerts to a person: a push to the owner's phone through ntfy (#184).
- [morca API: orca.partitions](https://morca.dev/docs/api/partitions.md): orca.partitions, in morca's API: Partition sets: which keys a pipeline is partitioned by, from when.
- [morca API: orca.pause](https://morca.dev/docs/api/pause.md): orca.pause, in morca's API: Pausing a pipeline: what `orca pause`, the UI's Pause button and the watchdog (`orca.watchdog`) all do.
- [morca API: orca.pipeline](https://morca.dev/docs/api/pipeline.md): orca.pipeline, in morca's API: Pipelines: a named list of steps, checked and run in order.
- [morca API: orca.pool](https://morca.dev/docs/api/pool.md): orca.pool, in morca's API: An EC2 instance's side of the warm pool (`orca.ec2`, `ORCA_EC2_POOL_SECONDS`): the two commands its script runs between runs, through the pipeline's binary, over `ORCA_DATABASE_URL`.
- [morca API: orca.pool_boot](https://morca.dev/docs/api/pool_boot.md): orca.pool_boot, in morca's API: How a machine the pool autoscaler made becomes a worker (#267): its startup script, and the UI's answer to its `/api/worker/boot`.
- [morca API: orca.pool_config](https://morca.dev/docs/api/pool_config.md): orca.pool_config, in morca's API: Worker pools orca grows and shrinks itself (#267): a `[pools.<name>]` table in orca.toml, read and checked here, recorded by `orca register` in `orca.pools`, and acted on by the scheduler (`orca.pool_scale`).
- [morca API: orca.pool_runs](https://morca.dev/docs/api/pool_runs.md): orca.pool_runs, in morca's API: The scheduler's part in a worker pool (`orca.workers`): due retries and dead runs queued again for a worker, lost workers' runs, orphans of gone instances, and fill runs queued for the pool.
- [morca API: orca.pool_scale](https://morca.dev/docs/api/pool_scale.md): orca.pool_scale, in morca's API: The pool autoscaler (#267): machines for the pools orca.toml declares (`orca.pool_config`), made and removed by the leading scheduler every `ORCA_POOL_SCALE_SECONDS` (15).
- [morca API: orca.pressure](https://morca.dev/docs/api/pressure.md): orca.pressure, in morca's API: Memory pressure (#202): Linux's pressure stall information (PSI) for memory, read each tick, and the admission rule built on it.
- [morca API: orca.proc](https://morca.dev/docs/api/proc.md): orca.proc, in morca's API: Starting processes: what the scheduler needs to run pipeline binaries.
- [morca API: orca.queueing](https://morca.dev/docs/api/queueing.md): orca.queueing, in morca's API: Queueing runs over keys: backfills, the keys a pipeline has done or holds, and what a rerun or an append refuses.
- [morca API: orca.recommend](https://morca.dev/docs/api/recommend.md): orca.recommend, in morca's API: Requests learned from what a pipeline's runs used (#269): shown on its Resources card and in `orca config show`, and applied where its `cpus` or `memory_gb` is `auto` (`resolve_request`).
- [morca API: orca.registered](https://morca.dev/docs/api/registered.md): orca.registered, in morca's API: A registered pipeline as the scheduler reads it (`Registered`, `registered`), and what its runs ask for (`run_request`).
- [morca API: orca.registering](https://morca.dev/docs/api/registering.md): orca.registering, in morca's API: `orca register`: recording a pipeline binary and how its runs run (`register_pipeline`).
- [morca API: orca.registry](https://morca.dev/docs/api/registry.md): orca.registry, in morca's API: Which architectures a container image has (#267): the pool autoscaler makes a machine only of a type the worker image runs on.
- [morca API: orca.remote](https://morca.dev/docs/api/remote.md): orca.remote, in morca's API: The `orca` command against a deployed `orca ui`, over HTTPS, as a user of it: log in once, then act from anywhere the UI can be reached.
- [morca API: orca.resources](https://morca.dev/docs/api/resources.md): orca.resources, in morca's API: Resource requests and grants (#171): runs sized to their share of the machine.
- [morca API: orca.sample](https://morca.dev/docs/api/sample.md): orca.sample, in morca's API: The sampler: a run's machine metrics, one JSON line every few seconds.
- [morca API: orca.schedule](https://morca.dev/docs/api/schedule.md): orca.schedule, in morca's API: Schedules: when a pipeline runs by itself, and which partition it fills.
- [morca API: orca.scheduler](https://morca.dev/docs/api/scheduler.md): orca.scheduler, in morca's API: The scheduler: fires schedules, senses datasets, queues backfills and rebuilds, and starts runs.
- [morca API: orca.secrets](https://morca.dev/docs/api/secrets.md): orca.secrets, in morca's API: Secrets a pipeline's runs get: `orca register --secret NAME=ID`.
- [morca API: orca.sensing](https://morca.dev/docs/api/sensing.md): orca.sensing, in morca's API: Fires and sensors (`orca.scheduler`): a schedule's fires, and a sensor's snapshots, keyed or by partition.
- [morca API: orca.sensors](https://morca.dev/docs/api/sensors.md): orca.sensors, in morca's API: Runs started by datasets: sensors, and rebuilds downstream of a dataset.
- [morca API: orca.source](https://morca.dev/docs/api/source.md): orca.source, in morca's API: Where a pipeline binary's code came from: its git repository and commit, given at build time.
- [morca API: orca.sqlite_store](https://morca.dev/docs/api/sqlite_store.md): orca.sqlite_store, in morca's API: orca's runs in a SQLite file: `SqliteStore`, for single-node orca.
- [morca API: orca.starting](https://morca.dev/docs/api/starting.md): orca.starting, in morca's API: Starting runs (`orca.scheduler`): due retries, dead runs and queued ones, within `max_runs`, memory pressure, grants and the vCPU budget; and a control-placed run's process.
- [morca API: orca.state](https://morca.dev/docs/api/state.md): orca.state, in morca's API: orca's state in Postgres: pipelines, runs, steps and attempts.
- [morca API: orca.step](https://morca.dev/docs/api/step.md): orca.step, in morca's API: Steps: the functions a pipeline runs, and the edges between them.
- [morca API: orca.store](https://morca.dev/docs/api/store.md): orca.store, in morca's API: Where the executor records what it does.
- [morca API: orca.system](https://morca.dev/docs/api/system.md): orca.system, in morca's API: The control instance's own health: `/ops/control`, the gauges on `/metrics`, and the warning on the home page.
- [morca API: orca.tables](https://morca.dev/docs/api/tables.md): orca.tables, in morca's API: Iceberg tables from steps: pinned reads, and commits a retry recognises.
- [morca API: orca.tasks](https://morca.dev/docs/api/tasks.md): orca.tasks, in morca's API: The dista tasks a pipeline's steps call, and the runtime a run gets.
- [morca API: orca.tick](https://morca.dev/docs/api/tick.md): orca.tick, in morca's API: One pass of the scheduler (`orca tick`; `orca scheduler` makes one a second): what each registered pipeline is due, started.
- [morca API: orca.timekeys](https://morca.dev/docs/api/timekeys.md): orca.timekeys, in morca's API: Time keys by their partitions' kind (`monthly`, `daily`, `hourly`), as text: for code that has a pipeline's kind as a string, not its type.
- [morca API: orca.timeline](https://morca.dev/docs/api/timeline.md): orca.timeline, in morca's API: A run's Dista timeline and its workers over time, drawn as SVG on the server for the run's page.
- [morca API: orca.tokens](https://morca.dev/docs/api/tokens.md): orca.tokens, in morca's API: API tokens: what `orca login` gets from `orca ui`, so the `orca` command on another machine can act as a user of it (`orca.remote`).
- [morca API: orca.toml](https://morca.dev/docs/api/toml.md): orca.toml, in morca's API: The TOML that `orca.toml` is written in (`orca.config`): a parser and a writer for the subset a configuration file needs.
- [morca API: orca.tz](https://morca.dev/docs/api/tz.md): orca.tz, in morca's API: Time zones, from the system's TZif files (RFC 8536).
- [morca API: orca.ui](https://morca.dev/docs/api/ui.md): orca.ui, in morca's API: orca's pages: HTML, each page in a module of its own, over the read models of `orca.views`; `orca.web.routes` says which path is which.
- [morca API: orca.ui.alerts](https://morca.dev/docs/api/ui/alerts.md): orca.ui.alerts, in morca's API: Ops › Alerts (`/ops/alerts`): every alert `orca.notify` sent or is sending, newest first, from `orca.alerts`: when, its kind, its title and message as sent, links to what it is about (the run, the pipelines, the watchdog's rules, a worker, Control), whether ntfy took it, and for those that resolve (a watchdog trip, a stalled fill, the disk, memory pressure, an `orca notify` that was later `--resolved`) whether it is still open.
- [morca API: orca.ui.attempt](https://morca.dev/docs/api/ui/attempt.md): orca.ui.attempt, in morca's API: `/runs/<id>/attempts/<attempt>`, an attempt's page: its log, with its error, and its facts, which refresh from `/facts` while it runs.
- [morca API: orca.ui.code](https://morca.dev/docs/api/ui/code.md): orca.ui.code, in morca's API: `/code?u=`: a file at a commit on GitHub, its lines coloured as HTML (`orca.highlight`), for the code shown on hover; the UI fetches it, so a browser needn't reach GitHub.
- [morca API: orca.ui.contained](https://morca.dev/docs/api/ui/contained.md): orca.ui.contained, in morca's API: Ops > Control's Runs card: each local and control-placed run going on this host, with its cgroup's memory against its limit (`orca.cgroup`), which the scheduler records every 5 seconds, and its grant (`orca.resources`).
- [morca API: orca.ui.coverage](https://morca.dev/docs/api/ui/coverage.md): orca.ui.coverage, in morca's API: The Coverage card on a dated pipeline's Operate tab: its partitions' states (`orca.calendar`) as plain HTML, read-only.
- [morca API: orca.ui.datasets](https://morca.dev/docs/api/ui/datasets.md): orca.ui.datasets, in morca's API: `/datasets`, the datasets and the graph of pipelines and datasets; `/datasets/<name>`, a dataset's writers, readers, snapshots and what a rebuild of it runs; `/datasets/<name>/snapshots/<id>`, a snapshot's lineage (`orca.lineage`); `/rebuilds/<id>`, a rebuild's runs by level.
- [morca API: orca.ui.home](https://morca.dev/docs/api/ui/home.md): orca.ui.home, in morca's API: `/`, the home page: the pipelines, with their coverage (`orca.coverage`), schedules, next and last runs, the recent runs, and the Timeline tab (`orca.ui.viz`); `/home/pipelines` is its table of pipelines, as the fragment it refreshes from.
- [morca API: orca.ui.layout](https://morca.dev/docs/api/ui/layout.md): orca.ui.layout, in morca's API: Every page's frame (`page_html`): its head, the nav, the slots the server fills in with who's logged in (`orca.web.server`), and the scripts every page has (`_POLL` for live fragments, `_TABS`, `_TIPS`, `_PEEK` for code on hover); and what every page draws with: cards, facts, help, action buttons, and the 404 and 400 pages.
- [morca API: orca.ui.login](https://morca.dev/docs/api/ui/login.md): orca.ui.login, in morca's API: The login page (`/login`, `orca.web.auth`).
- [morca API: orca.ui.machines](https://morca.dev/docs/api/ui/machines.md): orca.ui.machines, in morca's API: A run's machines on its page: each instance with its role, its metrics' peaks and warnings (`orca.metrics`), and the steps that ran on it.
- [morca API: orca.ui.ops](https://morca.dev/docs/api/ui/ops.md): orca.ui.ops, in morca's API: The Ops pages: Control (`/ops/control`, the machine running the scheduler, the UI and Postgres; `orca.system`), the watchdog (`/watchdog`; `orca.watchdog`) and Prometheus' `/metrics`, with the fragments each refreshes from; Alerts (`/ops/alerts`, where `/ops` goes) is `orca.ui.alerts` and Pools (`/ops/pools`) is `orca.ui.pools`. Fleet and Workers' old paths redirect to Pools (`moved`, `to_pools`).
- [morca API: orca.ui.parts](https://morca.dev/docs/api/ui/parts.md): orca.ui.parts, in morca's API: Pieces several pages draw: durations, times and partitions in a table's cells, a runs table with each row's actions, links to code, and a run's grant and usage as facts.
- [morca API: orca.ui.pipeline](https://morca.dev/docs/api/ui/pipeline.md): orca.ui.pipeline, in morca's API: `/pipelines/<name>`, a pipeline's page: Overview (its cards: Progress, Steps, Code, Resources, Configuration), Runs and Operate (Start runs, cancel, pause), each a tab of its own; `/progress`, the Progress card as the fragment it refreshes from; and `/keys/<key>`, one key of a keyed pipeline in every run it was in.
- [morca API: orca.ui.pools](https://morca.dev/docs/api/ui/pools.md): orca.ui.pools, in morca's API: Ops' Pools (`/ops/pools`): a row per machine of every pool runs are placed on (`orca.views.pools`), filtered by pool and kind with plain links, refreshed every 10 s from `/ops/pools/live`; a machine's own page (`/ops/pools/<kind>/<id>`); and `/api/pools`. With EC2 in view the page keeps Fleet's summary cards and charts (`orca.fleet`).
- [morca API: orca.ui.run](https://morca.dev/docs/api/ui/run.md): orca.ui.run, in morca's API: `/runs/<id>`, a run's page: its cards (Status, Partitions & trigger, Code, Resources, Settings), its steps as a table, a timeline or a graph, its machines, its snapshots and who acted on it; and its fragments and files: `/live`, `/steps`, `/metrics`, `timeline.json`, `driver.log` and each machine's log.
- [morca API: orca.ui.runs](https://morca.dev/docs/api/ui/runs.md): orca.ui.runs, in morca's API: `/runs`, the runs list: newest first, filtered by pipeline, status (any of several, each with its count), trigger, when it was created, a run and its partitions, a page at a time (`orca.views.runs.RunsPage`), and its runs picked to cancel, retry or backfill again in one go (`orca.api.actions.bulk`); `/runs/table` is a list's page as the fragment it refreshes from, for `/runs`, a pipeline's Runs tab and the home page.
- [morca API: orca.ui.start](https://morca.dev/docs/api/ui/start.md): orca.ui.start, in morca's API: Start runs, on a pipeline's Operate tab: the form, its date picker (`orca.ui.coverage`), and the preview of what it would queue (`orca.views.start`), updated as you type.
- [morca API: orca.ui.step_cards](https://morca.dev/docs/api/ui/step_cards.md): orca.ui.step_cards, in morca's API: A card per step, on hover, keyboard focus or a tap, in the UI's steps views: a pipeline's Steps card (Graph and Table) and a run's (Table, Timeline and Graph).
- [morca API: orca.ui.style](https://morca.dev/docs/api/ui/style.md): orca.ui.style, in morca's API: The stylesheet `orca ui` serves at `/static/orca.css`: magmalake.dev's colours and type, light and dark, and system fonts (nothing is fetched).
- [morca API: orca.ui.terms](https://morca.dev/docs/api/ui/terms.md): orca.ui.terms, in morca's API: What the UI's words mean, in one place: the help on every table's column headers, and on the values that come from a fixed set (statuses, step kinds, triggers, placements, where a setting came from), so the same word has the same explanation on every page.
- [morca API: orca.ui.viz](https://morca.dev/docs/api/ui/viz.md): orca.ui.viz, in morca's API: Two views `orca ui` draws in the browser: a run's Dista timeline, and the pipelines over time on the home page. Both are plain scripts in the page (nothing is fetched from elsewhere) over JSON the UI serves, and both load that JSON only when they're looked at, so the pages stay as fast as they were.
- [morca API: orca.upgrade](https://morca.dev/docs/api/upgrade.md): orca.upgrade, in morca's API: A release's upgrade steps (#323): what has to be done before or after a deploy, which a project's image ships in `upgrade.toml` and the Hetzner deploy shows or runs (`deploy/hetzner/deploy.sh`).
- [morca API: orca.usage](https://morca.dev/docs/api/usage.md): orca.usage, in morca's API: What a run's processes use: each attempt's peak memory and CPU.
- [morca API: orca.views](https://morca.dev/docs/api/views.md): orca.views, in morca's API: What the pages and their JSON show, read from the database once into typed rows: the query layer `orca.ui` and `orca.api` share.
- [morca API: orca.views.code](https://morca.dev/docs/api/views/code.md): orca.views.code, in morca's API: Where a pipeline's code is: each step's line at the commit a run, or the registration, was built from (`CodeLinks`), for the link beside every step a page shows.
- [morca API: orca.views.commands](https://morca.dev/docs/api/views/commands.md): orca.views.commands, in morca's API: The `orca` command lines the pages show beside their buttons, so what the UI does can be done from a shell, quoted for `sh`.
- [morca API: orca.views.datasets](https://morca.dev/docs/api/views/datasets.md): orca.views.datasets, in morca's API: Datasets as their pages read them: the steps that write and read one, and what a rebuild of it would queue (`RebuildPreview`).
- [morca API: orca.views.pipelines](https://morca.dev/docs/api/views/pipelines.md): orca.views.pipelines, in morca's API: Pipelines as the pages and their JSON read them: `PipelineRow` (a registration with its schedule and live runs), its steps (`StepDef`), its next fires, a keyed pipeline's counts (`KeyCounts`), its fill, and the Resources card's summary of what its runs used (`UsageSummary`).
- [morca API: orca.views.pools](https://morca.dev/docs/api/views/pools.md): orca.views.pools, in morca's API: Ops' Pools (`/ops/pools`): every machine runs are placed on, one row each, by the pool a placement names.
- [morca API: orca.views.runs](https://morca.dev/docs/api/views/runs.md): orca.views.runs, in morca's API: Runs as the pages and their JSON read them: `RunRow` with its grant and what it used, its steps (`StepRow`), the tables they read and wrote (`Touch`), its machines (`InstanceRow`) and code (`VersionRow`), a step's attempts (`AttemptRow`), and a runs list's page (`RunsQuery`, `RunsPage`: keyset by run id, so pages stay put as runs arrive).
- [morca API: orca.views.start](https://morca.dev/docs/api/views/start.md): orca.views.start, in morca's API: What Start runs would queue (`StartPreview`), as a sentence and as the command that queues it, for a pipeline's Operate tab and its JSON.
- [morca API: orca.views.steps](https://morca.dev/docs/api/views/steps.md): orca.views.steps, in morca's API: What the step cards show (`orca.ui.step_cards`): each step's card, with what its attempts in the pipeline's latest runs did, and on a run's page each attempt's.
- [morca API: orca.warehouse](https://morca.dev/docs/api/warehouse.md): orca.warehouse, in morca's API: A dataset's current snapshot, read from its table's metadata file without iceberg, for `<binary> sense`.
- [morca API: orca.watchdog](https://morca.dev/docs/api/watchdog.md): orca.watchdog, in morca's API: The watchdog: pauses pipelines when something leaves a sane range.
- [morca API: orca.web](https://morca.dev/docs/api/web.md): orca.web, in morca's API: orca's web server: one router over the pages (`orca.ui`) and the JSON API (`orca.api`), who each request is from, and the listeners.
- [morca API: orca.web.auth](https://morca.dev/docs/api/web/auth.md): orca.web.auth, in morca's API: Who a request is from, and whether it may act: the session cookie of a browser, the API token of a script (`orca --remote`), and the checks that keep another site's page from posting to the UI. Also the endpoints that log in and out. The users, sessions and audit rows themselves are `orca.auth`; API tokens are `orca.tokens`; a worker's token is checked by `orca.api.worker` instead, and gets nothing here.
- [morca API: orca.web.drain](https://morca.dev/docs/api/web/drain.md): orca.web.drain, in morca's API: Stopping `orca ui` without dropping a request. `docker stop` sends SIGTERM and waits 10 s before it kills; Ctrl-C sends SIGINT. Either one starts a drain:
- [morca API: orca.web.page](https://morca.dev/docs/api/web/page.md): orca.web.page, in morca's API: What a handler answers, `Page`: its status, its JSON and its HTML, where to send a browser, and `respond`, which sends it: the HTML, or the JSON to a script; a fragment or a file as itself, whatever was asked for.
- [morca API: orca.web.router](https://morca.dev/docs/api/web/router.md): orca.web.router, in morca's API: The router: a table of routes, each a method, a path pattern, what kind of request it is and the handler that answers it. `orca.web.routes` is the table; `orca.web.server` looks a request up here and wraps the handler in what its kind needs.
- [morca API: orca.web.routes](https://morca.dev/docs/api/web/routes.md): orca.web.routes, in morca's API: Every path `orca ui` answers, and what answers it: the route table `orca.web.server` serves (`orca.web.router` for how a path matches).
- [morca API: orca.web.server](https://morca.dev/docs/api/web/server.md): orca.web.server, in morca's API: `orca ui`'s server: one handler that looks each request up in the route table (`orca.web.routes`), checks who it's from (`orca.web.auth`) and answers it as its route's kind says.
- [morca API: orca.worker](https://morca.dev/docs/api/worker.md): orca.worker, in morca's API: `orca worker`: runs a pool's runs on this machine, talking only to `orca ui`'s API.
- [morca API: orca.workers](https://morca.dev/docs/api/workers.md): orca.workers, in morca's API: Remote workers, the server's side: worker tokens, claims, and the store calls a worker's runs make over `orca ui` (`orca.http_store`).