# Using morca

> 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.

[morca](https://morca.dev/)

[](https://morca.dev/search "Search")

morca turns a Mojo file of steps into a pipeline binary with a command line, and a scheduler runs those binaries on this machine, on Kubernetes or on EC2, recording every run in Postgres. This page installs it; the pages below cover the rest. The plan is in the repository's [DESIGN.md](https://github.com/morca-dev/morca/blob/main/DESIGN.md).

**A note on the name.** The project is called morca, but the code is still named `orca` and will be renamed to `morca` ([morca #384](https://github.com/morca-dev/morca/issues/384)). Until then the package, the command line, `orca.toml` and the `ORCA_*` environment variables keep their names, and so do these docs' examples.

## The docs

- [**Features**](https://morca.dev/docs/features): Everything morca does on one page, major features first, each linking to where it is explained.
- [**Writing a pipeline**](https://morca.dev/docs/build): Steps and pipelines, partitions by date or by name, schedules, Iceberg tables and datasets, sensors, Dista inside steps, and building the binaries.
- [**The command line**](https://morca.dev/docs/cli): The commands you type, on a pipeline binary and on orca, from a laptop with orca login and --remote, the ones orca runs for you, and how the same binary acts locally or on AWS.
- [**Scheduling and running**](https://morca.dev/docs/run): The scheduler, runs on Kubernetes and EC2, placement and remote workers, fills, sizing runs by memory and CPU, the watchdog and alerts, runs in Postgres, logs and machine metrics, lineage and rebuilds, the environment, and what happens when things fail.
- [**The UI**](https://morca.dev/docs/ui): The pages and their JSON, coverage, filtering runs and acting on many, the actions and what they ask first, logins, a run's page, and code on hover.
- [**Debugging failures**](https://morca.dev/docs/debug): Where a failed run's errors and logs are, adding context to errors, symbolized crash dumps, reproducing a partition locally, and resuming it.
- [**Remote workers**](https://morca.dev/docs/workers): Running some pipelines on a second machine: a worker token, a placement, a worker container that needs only outbound HTTPS, and the census as the example.
- [**Mojo API**](https://morca.dev/docs/api): The Mojo API of the orca package, module by module, from the published release.
- [**orca.toml**](https://morca.dev/docs/config): Every key of orca.toml: pipelines, pools, fills, requests, how many runs at once, and what register refuses.
- [**Files and HTTP API**](https://morca.dev/docs/formats): The HTTP and JSON API, the worker API, logs and metrics files, the Postgres tables and the environment variables.
- [**Deploying**](https://morca.dev/docs/deploy): Deploying on one Hetzner server: the scripts from a release, deploys that replace only what changed and don't pause runs, rollbacks, settings and SOPS secrets, and rescaling.
- [**Pools and autoscaling**](https://morca.dev/docs/pools): Worker pools whose machines morca makes and removes on Hetzner Cloud or EC2, and one run spread over several machines.
- [**Sizing and scaling**](https://morca.dev/docs/scaling): The right size for each run and the right number of runs: requests, learned requests, auto counts and memory pressure.
- [**Alerts and the watchdog**](https://morca.dev/docs/monitoring): Alerts, the watchdog, the metrics morca samples, and where to look when a run is stuck.
- [**Upgrades and rollbacks**](https://morca.dev/docs/upgrades): New releases, additive migrations, rolling back without restoring the database, and backups.
- [**Tokens and secrets**](https://morca.dev/docs/security): Logins, worker and machine tokens, each run's cluster token, pipeline secrets and cloud API tokens.
- [**Roadmap**](https://morca.dev/docs/roadmap): Vertical scaling, the right size for each run, and horizontal scaling, the right number of runs and machines: what morca does today, what's next, and the work it draws on.

## Install it

morca is the [mojoshelf](https://mojoshelf.org/getting-started) tin `orca-mojo`. With pixi and mojoshelf's `pixi shelf` installed, a new project adds it, and the tins it needs come with it. Plain pixi can add it from its repository instead:

mojoshelf:

```
pixi init -c https://conda.modular.com/max-nightly -c conda-forge lake && cd lake
sed -i.bak 's/^\[workspace\]/[workspace]\npreview = ["pixi-build"]/' pixi.toml   # tins build with pixi-build
pixi add "mojo-compiler==1.2.0"
pixi shelf add orca-mojo
```

`pixi shelf` comes with mojoshelf: [install it first](https://mojoshelf.org/getting-started).

plain pixi:

```
pixi init -c https://conda.modular.com/max-nightly -c conda-forge lake && cd lake
sed -i.bak 's/^\[workspace\]/[workspace]\npreview = ["pixi-build"]/' pixi.toml   # tins build with pixi-build
pixi add "mojo-compiler==1.2.0"
# Without mojoshelf: the tin as a git dependency at its published commit.
# Transitive dependencies may be wrong: pixi takes the tin's own git deps as
# pinned in its pixi.toml, which may not match what other tins pin, and then
# fails with "duplicate records". mojoshelf picks revisions that agree.
pixi add orca-mojo --git https://github.com/morca-dev/morca --rev 32ee1ee691cc9fd09a8e2a2d0798a6381d432458
```

No mojoshelf needed. If pixi reports duplicate records, the mojoshelf tab picks revisions that agree.

A pipeline is one Mojo file whose `main` hands it to `orca_main`, compiled into a binary of its own. Build one and run it in memory to try it:

```
pixi run mojo build -I src pipelines/lake.mojo -o build/lake
./build/lake run --partitions 2024-01..2024-03
```

[Writing a pipeline](https://morca.dev/docs/build) says what goes in the file, and how to build the `orca` command that schedules it.

## The playground

To see the UI before running anything real, the repository's playground starts it on this machine with a throwaway Postgres, the example pipelines and their runs, two of them on a stand-in EC2:

```
git clone https://github.com/morca-dev/morca orca.mojo && cd orca.mojo
git clone https://github.com/morca-dev/dista ../dista.mojo
git clone https://github.com/magmalake/k8s.mojo ../k8s.mojo
pixi run playground          # then http://127.0.0.1:8270, log in as demo / demo-password
```

## From source

Building from source works the same way: the repository compiles Dista and k8s.mojo from those checkouts beside it, `pixi run test` runs the tests, and `pixi run orca` builds the scheduler to `build/orca`. It targets Mojo 1.2.0, with a nightly environment alongside. Its state goes through postgres-mojo, which loads libpq; the tests start a throwaway Postgres server of their own. `orca.tables`, the Iceberg part, has its tests in the `data` environment (`pixi run -e data test-tables`).

[morca](https://morca.dev/)

Data pipelines in Mojo. Early, and built in the open.

### Project

[GitHub organisation](https://github.com/morca-dev) [Issues](https://github.com/morca-dev/morca/issues) [morca](https://github.com/morca-dev/morca) [dista](https://github.com/morca-dev/dista) [census](https://github.com/morca-dev/census)

### Built on

[magmalake.dev](https://magmalake.dev) [The Iceberg, Parquet and codec libraries](https://magmalake.dev/tins) [mojoshelf.org](https://mojoshelf.org) [The Mojo language](https://www.modular.com/mojo)

### Standards

[Apache Iceberg](https://iceberg.apache.org) [Apache Parquet](https://parquet.apache.org) [PostgreSQL](https://www.postgresql.org)

Copyright 2026 Marius Seritan. Every repository is licensed [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

Apache Iceberg and Parquet are trademarks of the Apache Software Foundation. Mojo is a trademark of Modular Inc. This project is not affiliated with or endorsed by the ASF or Modular.