orun
Plan once. Run anywhere. Operate from one cockpit.
orun compiles policy-aware platform intent into a deterministic execution DAG,
then runs it through the backend you choose — local shell, Docker, or GitHub Actions.
The CLI and the TUI render the same plan, the same state, the same glyphs. Drift between
surfaces is a compile error, not a visual regression.
▲ orun multi-environment-platform Plan: sha256-ad6ce · Run: gh-26563885741-... · State: completed · Duration: 1m42s Scope: 6 components · 14 jobs · 3 environments Status: ✓ 12 succeeded · ◐ 1 running · ○ 1 queued · ✗ 0 failed Progress: ▓▓▓▓▓▓▓▓▓▓▓▓▓░░ 86% ● api-edge-worker │ ├─ ✓ build 4.1s │ ├─ ✓ test 12.3s │ └─ ✓ verify-deploy 19.0s ● database │ └─ ◐ apply running 38.2s ○ web-app └─ ○ deploy queued
A deterministic compiler
Six-stage pipeline — load, normalize, expand, bind, resolve, materialize — turns
intent.yaml plus discovered components and composition packages into
plan.json: an immutable DAG you can diff, archive, and review.
One UX for status, logs, runs
orun status, orun logs, orun tui and live
--watch mode all flow through the same view-model and the same design
tokens. The CLI is the TUI compressed to a frame; the TUI is the CLI with navigation.
Backend-swappable runtime
The plan is the boundary. Execute it on the local shell, inside Docker, or on GitHub Actions without recompiling. Trigger bindings and dependency rules adapt the DAG to the event that fired it — PR validation, merge-to-main, tagged release.
What orun is
orun is a planner and a cockpit for the platform-engineering layer that sits
between application repos and deployment automation. It is shaped by four ideas:
Intent, not scripts
Platform teams declare environments, group policies, discovery roots, and trigger
bindings in intent.yaml. App teams declare component types and inputs in
component.yaml. Neither side owns the runtime details.
Compositions as packages
A composition is a typed, versioned execution contract — input schema, job templates,
profiles. Distribute them as a directory, an archive, or an OCI artifact. The plan
pins the resolved digest in compositions.lock.yaml.
The plan is the audit trail
Every implicit default, policy merge, and dependency edge becomes explicit in
plan.json. You diff plans in pull requests, archive them as deployment
records, and replay them against different runners.
Cockpit-grade observability
The same view-model that paints orun status drives the TUI cockpit and
future surfaces. State is on disk under .orun/; orun status
--watch and the TUI subscribe to the same polling stream.
The compile → cockpit → execute loop
intent.yaml ── component.yaml ── compositions ──┐
├──▶ orun plan ──▶ plan.json
trigger context ──────────────┘ │
│
┌───────────────────────────┘
▼
orun run ──▶ .orun/ state
│
┌───────────────┼───────────────┐
▼ ▼ ▼
orun status orun logs orun tui
└─────── cockpit (one design system) ───────┘
The boundary on the left is planning. The boundary on the right is operations.
plan.json and .orun/ are the only contracts between them — both versioned, both
deterministic, both reviewable.
How to read these docs
Install, build, ship the example
Install the CLI, run the quick start, and watch the cockpit light up against a real example intent.
Principles & concepts
Start with the design principles, then read intent, compositions, and plans in that order.
Cockpit, CLI, runners
The cockpit guide covers status, logs, and the TUI. The CLI reference and runners cover day-to-day operation and CI integration.
Architecture & contributing
Architecture explains every stage of the planner and cockpit bridge. Build covers packaging your own compositions, runners, or surfaces.
Why this design
Determinism is non-negotiable
Identical inputs produce identical plans — byte-for-byte. The planner is a pure function of intent + components + locked composition digests.
Policy at compile time
Group policies and domain constraints are enforced when the plan is built, not when it runs. A non-compliant intent fails fast with a structured error.
One design language, many surfaces
Glyphs, palette, status pills, progress bars and tree connectors live in
internal/cockpit/style. Reskinning the cockpit is one file.
OCI-native distribution
orun ships as a kiox provider at
ghcr.io/sourceplane/orun. Compositions distribute the same way.
Ready to compile your first plan? Jump to the quick start, or read the design principles for the why behind the architecture.