Platform discipline as code.
Every platform has standards: how a service is shaped, how Terraform is applied, what may
ship to production and in what order. Most of them live in wikis, review comments, and
the heads of a few people. orun gives them a declarative language. Write your
platform's structure and standards as intent, package them as baselines you version and
evolve like any other code, give your agents the same intent so they don't deviate, and
let a runner verify it, compile a plan, and execute it.
apiVersion: sourceplane.io/v1
kind: Component
metadata:
name: identity-worker
spec:
type: cloudflare-worker # its golden path
domain: platform-identity
subscribe:
environments:
- name: dev
profile: pull-request # how it runs per lane
- name: staging
profile: verify
- name: production
profile: deploy
parameters: # checked against its schema
installCommand: pnpm install --no-frozen-lockfile
buildCommand: pnpm exec turbo run build --filter=./
deployCommand: pnpm run deploy
nodeVersion: "20"
productionBranch: mainStructure and standards as intent
intent.yaml holds the platform's rules: environments, groups, trigger
bindings, promotion order. component.yaml sits next to each unit of code
and says what it is. Compositions turn a golden path into a typed contract: the schema
a component must satisfy, the jobs it runs, the profiles allowed per lane.
Standards that travel like code
Golden paths ship as versioned OCI Stacks. Platform rules ship as intent presets
that repositories inherit with extends:. A repository pins each standard
by version or digest, and every plan records the exact digest it used.
A baseline packages a whole product's
structure and standards, so it can be rebuilt for a new owner and upgraded instead of
forked.
Agents that read your standards
A coding agent working in an orun repository reads the same intent, catalog, and
contracts your platform does, through orun mcp and a versioned base
literacy. Agent types carry a deny-by-default tool policy, and task contracts declare
the blast radius a change may touch, so agents work inside the standards instead of
guessing at them.
A runner that checks before it acts
orun validate checks the intent and its rules. orun plan checks
every component against its composition's schema, then compiles
plan.json, a deterministic DAG you can diff in review.
orun run executes the plan on your shell, in Docker, or on GitHub Actions,
and records every step as content-addressed history.
Why discipline needs to be code
A platform's standards are only as strong as the place they live. When they live in a
wiki, they drift the moment someone is in a hurry. When they live in CI if: expressions
and review vigilance, nobody can say what a change will do without running it. And a
coding agent joining the team inherits all of that fog at machine speed: it copies the
nearest example, not the standard.
orun moves the standards into the repository, in a language that both people and tools can read:
One source for structure and rules
Which components exist, which environments they ship to, which golden path each one follows, and in what order things promote: all declared, all reviewable as a diff.
Standards with releases
A change to the golden path is a new Stack version. A repository adopts it with a version bump and sees the consequence as a plan diff before anything runs.
The same truth for people and agents
Agents read the declared intent and the derived catalog instead of inferring conventions from code. What they may touch is a contract, not a suggestion.
Verified before it runs
Every event compiles to a complete plan first. Identical inputs produce byte-identical plans, so the plan in a pull request is a faithful preview of what will happen.
The loop
DECLARE PACKAGE & EVOLVE GROUND AGENTS
intent.yaml Stacks (golden paths, OCI) orun mcp · orun skills
component.yaml ◀── intent presets (extends:) ──▶ base literacy · agent types
compositions baselines (whole products) task contracts (affects)
│ │
│ agents propose changes to intent ◀──────────┘
▼
VERIFY ─────────▶ PLAN ─────────────▶ EXECUTE ───────────▶ RECORD
orun validate orun plan orun run .orun/ object graph
intent, rules schemas, plan.json shell · docker · gha catalog · status · logs · tui
Standards are declared once, packaged so they can travel, and read by every agent that works in the repository. The runner is the checkpoint: nothing executes that was not first verified and compiled into a plan you can review.
Orunbase, when a team shares it
orun is local-first: it is a single binary, and its state lives in your repository's
.orun/. Orunbase is the hosted control plane you add when
a team shares that state: workspaces, managed remote state, live runs, a console, the task
plane, sandboxed agents, and the registry of baselines you can build whole products from.
Sign in with orun auth login and pick a workspace with
orun workspace use. Orunbase is itself written as
orun intent.
How to read these docs
Install and run the example
Install the CLI and follow the quick start: declare, verify, plan, and run the example platform in this repository.
The idea and its principles
Read what orun is, the design principles, and how orun works, then the concept pages pillar by pillar in sidebar order.
Encode your own standards
Write a composition for your golden path, publish it as a Stack, and share platform rules through intent presets.
Every command and schema
The CLI reference is grouped by pillar. The reference pages cover configuration, the plan schema, and environment variables.