Skip to main content
Orcra Run (orun) is a lightweight, declarative container orchestrator that uses Git as its sole source of truth. Instead of pushing commands to nodes, you commit manifests to a repository and each node pulls and applies them on its own schedule. This page covers what Orcra Run is, how it differs from traditional orchestrators, the three resource types it manages, and the built-in features that come bundled in the single orun binary.

​
How it works

Every node runs orun start as a systemd service. On each poll cycle — every 5 seconds by default — the node fetches the latest commit from your manifest repository and reconciles the running containers to match. No central scheduler decides what runs where; each node reads its own section of the repository and acts independently. This pull-based model means:
  • No control plane to operate. The cluster keeps running whether or not your workstation is online.
  • Airgap-friendly. Once a node has cloned the manifest repository, it can continue reconciling from a local mirror or an internal Git server.
  • SSH is only needed once. orun bootstrap connects over SSH to provision the node. After that, orun manages itself via systemd.

​
Committing manifests

The workflow is intentional: you write YAML manifests, commit them, and push. The node does the rest. Every change is a commit, so you get an audit trail and rollback for free — just revert the commit. 
deployments/
  hello-world.yaml
nodes/
  web-01.yaml
services/
  hello-world.yaml
Branches or worktrees can represent environments. Set gitBranch in the node manifest to track staging or production independently from the same repository.

​
Resource types

Orcra Run defines three Kubernetes-style resource kinds under the run.orcra.dev/v0alpha API version. Node — Describes a server: its SSH connection details, which manifest repository and branch to track, how often to poll, and where to store state on disk. Node manifests live in nodes/ and are written automatically by orun bootstrap. Deployment — Describes a container: the image to run, host/container port bindings, volume mounts, environment variables, and HTTP health checks for readiness and liveness probing. Service — Exposes a Deployment through the built-in Caddy ingress proxy. Set a domain, enable ssl: true, and Caddy provisions a certificate automatically via ACME.

​
Built-in features

orun ships as a single static binary that includes everything a node needs:
  • Caddy ingress — An embedded Caddy server handles HTTP/HTTPS routing and automatic SSL for any Service with ingress.ssl: true.
  • SOPS secrets — Environment variables in Deployment manifests can be SOPS-encrypted with an age key. The node decrypts them at apply time; plaintext never touches Git.
  • Structured logs — All agent activity is emitted as structured JSON, captured by systemd/journald. Pair with Beszel, Dozzle, or a log shipper like Vector for visibility.
Orcra Run is pre-release, experimental software. The v0alpha API version may change between releases.

​
Next steps

Quick start

Bootstrap your first node and deploy a running container in under 10 minutes.

How it works

A deeper look at the reconciliation loop and the pull-based model.

Node configuration

All fields for the Node manifest: SSH, Git, poll interval, and data directory.

CLI reference

Full reference for orun bootstrap and orun start.