Reference

Files and HTTP API

Besides orca.toml, morca reads and writes an HTTP API (every UI page is also JSON), logs and machine metrics under ORCA_LOGS, an orca schema in Postgres, and its environment.

The HTTP API

orca ui serves every page as HTML, and as JSON to Accept: application/json or ?format=json; paths under /api/ are always JSON. Reading needs no login. An action needs a session cookie from a browser or an API token from a script (Authorization), and is audited as its user's. A worker's token works only on /api/worker/, and a user's token never does. The full route table is the docstring of routes.mojo, and ui.md describes each page and its JSON fields.

Pages and their JSON

Pages that refresh have a fragment twin (/runs/table, /home/pipelines, /ops/pools/live, /ops/control/live and others) that the page polls. The old /fleet, /ops/fleet, /ops/workers and /system redirect to Pools and Control.

A run's cluster (from 0.24.0)

/runs/<id>'s JSON gains cluster: the workers a run's Dista cluster spread over, when a pipeline placed on a worker pool has workers = N. The first row is the worker that started the run, holding its head; each later one a member that joined. It is an empty list for a run on one machine. The run page shows the same as its Cluster card.

"cluster": [
  {"role": "head", "start": 1, "worker": "orca-pool-lab-3", "address": "10.77.0.3:41237",
   "grant": {"cpus": 8, "memory_mb": 15360}, "joined": "2026-11-11T09:12:04Z",
   "ended": null, "why": null},
  {"role": "member", "start": 1, "worker": "orca-pool-lab-4", "address": null,
   "grant": {"cpus": 8, "memory_mb": 15360}, "joined": "2026-11-11T09:12:31Z",
   "ended": "2026-11-11T09:40:10Z", "why": "its run ended"}
]

Autoscaled pools (from 0.24.0)

/ops/pools' JSON and /api/pools gain autoscaled: each [pools.<name>] morca grows, with its types and waits (null for none), locations, limits, live machines, the type it is trying and what its last try came to. Pool machines are named orca-pool-<pool>-<n>.

"autoscaled": [
  {"name": "lab", "provider": "hetzner",
   "machines": [{"type": "cax31", "wait": 600}, {"type": "cpx32", "wait": null}],
   "locations": ["hel1", "nbg1"], "max_machines": 3, "idle_seconds": 900,
   "live": 2, "trying": null, "status": null}
]

Actions

Each is a POST of a form, or of JSON from orca --remote. It answers 303 See Other to the page of what it made (a script gets that page's JSON with 200), or 409 saying why it wasn't done.

Logging in

The worker API

What orca worker and the runs it starts call: each a POST of JSON with Authorization: Bearer <worker token>. The token must be a live worker token (else 401), the body a JSON object (400), and a pool it names the token's (403). With ORCA_WORKER_ADDR set, the UI also serves these, and only these, on that address from a thread of their own, so a slow page can't hold up claims and heartbeats. See Remote workers and api/worker.mojo.

Logs on disk and in object storage

With ORCA_LOGS set to a directory or s3://bucket/prefix, everything a run leaves is under <ORCA_LOGS>/<pipeline>/<run>/. Without it, logs go to standard output only. An object can't be appended to, so a log bound for object storage is written under ORCA_LOG_STAGE and uploaded when it's complete. Secrets named in ORCA_SECRETS are masked as *** in every log morca writes, and each attempt's row records where its log ended up.

A control-placed run's driver output is staged under ORCA_LOG_STAGE/control/ before it's appended to driver.log. On a remote worker, the logs of a cluster's head and members stay in the worker's --dir.

Metrics lines

<binary> sample runs beside every process doing a run's work and appends a JSON line every ORCA_SAMPLE_SECONDS (5). Readers ignore keys they don't know, since fields may be added. The run page's Machines section draws these files.

{"v": 1, "t": 1762250000.123, "dt": 5.0, "host": "ip-10-0-1-5", "cores": 4,
 "cpu": {"user": 61.2, "system": 4.1, "iowait": 0.3, "steal": 0.0, "busiest": 99.0},
 "mem": {"total": 8053063680, "used": 3221225472, "available": 4831838208,
         "cache": 2147483648, "swap_total": 0, "swap_used": 0, "rss": 2952790016},
 "disk": [{"path": "/tmp", "total": 53687091200, "used": 9663676416, "free": 44023414784}],
 "io": {"read": 1048576, "write": 52428800}, "net": {"in": 1310720, "out": 655360},
 "self_cpu": 0.42}

The sampler's options and platform differences are in the docstring of sample.mojo.

The Postgres schema

With ORCA_DATABASE_URL set, every orca binary creates and migrates the orca schema at start-up. Each change of a run's state is one transaction. morca 0.23 has 54 migrations, and 0.24.0 adds a 55th (orca.pipelines.fill_max_runs_auto). A sqlite: database holds the core run tables only.

Additive migrations

A binary older than the database runs on it if every migration it doesn't know is additive, which is what makes deploy.sh --rollback safe. So a migration may add tables, indexes and nullable foreign keys, and columns that are nullable or have a default. It may not rename, drop or retype a column or table, tighten a constraint, or write a value an older binary would act on. A migration that must is listed as raising the floor: orca.schema_version records it, and a binary that doesn't know it refuses to start. Today only migrations 1 and 24 raise it. Queries name the columns they read and write, so new columns never break old binaries. The rules are in migrations.mojo.

Environment variables

Settings for the whole stack are environment variables, in /etc/orca.env on a deployed stack; settings for one pipeline belong in orca.toml's env. Families with many members (ORCA_WATCHDOG_*, ORCA_NOTIFY_*, ORCA_EC2_*, ORCA_POOL_*) are listed in full in watchdog.md, alerts.md, Scheduling and running and orca.toml.

The scheduler

The UI

Workers and the remote CLI

A worker also reads ORCA_WAREHOUSE, ORCA_LOGS, ORCA_SECRET_FETCH, the reserve and pressure variables, and refuses to start with ORCA_DATABASE_URL set.

What morca sets for a run

A pipeline's env can't set these; orca does, for the run's process.

Dista variables morca sets

The runners start a run's Dista head and workers from the pipeline's own binary, telling each what it is with these.