Runex

Agent-Native Ontology Runtime.

English · 简体中文

Runex is an agent-native ontology runtime — it brings Palantir-Ontology-style modeling and data-operation experience to a single person's machine. It turns every element of your operation (tasks, customers, rules, agents, notes) into a strongly typed, transactionally consistent graph shared by humans and agents. Write once, and it becomes the durable world your agents act on — no more reconstructing context from a prompt every session.

How it works

flowchart LR
    S["Human · Agent · External source"]
    W["① Write<br/>typed node<br/>identity · fields · relations"]
    M["② Model<br/>state machine + Guard<br/>illegal → block + rollback"]
    R["③ Reactive<br/>event cascade<br/>WorkItem · Proposal · downstream"]

    S -->|"write once"| W
    W -->|"state change"| M
    M -->|"valid transition"| R
    R -.->|"work done → graph updated"| W

    classDef phase fill:#0B0C0E,stroke:#3FCF8E,color:#ECEDEE,stroke-width:2px;
    classDef src fill:#16191D,stroke:#5BE6A3,color:#ECEDEE;
    class W,M,R phase;
    class S src;

Loading

1. Write — everything lands in the graph.

A task, customer, or rule mentioned once becomes a typed object: identity · fields · relations · lifecycle. Written once, it persists. The next agent that meets it gets the complete, stable entity — no guessing.

2. Model — objects are alive.

Every object has an explicit state model: state machines + Guards define how it may transition. "A deal can't close before the contract is signed" is a law of the runtime, not a suggestion in a prompt. Illegal transitions are blocked and rolled back — agents can't cheat, and can't forget.

3. Reactive — transitions trigger chain reactions.

Every state change produces a deterministic event cascade: a persistent WorkItem for a background worker, a Proposal awaiting approval, updates to every downstream consumer. Watch each step — traceable, auditable, replayable.

Quick Start

Runex ships as a Nuitka-compiled onefile binary. macOS (Apple Silicon):

unzip runex-macos-arm64.zip
cd runex-macos-arm64/
./install.sh
runex init && runex doctor

Windows · Linux · source install

Windows (amd64)

Expand-Archive runex-windows-amd64.zip
cd runex-windows-amd64
pwsh install.ps1
runex init && runex doctor

Linux (x64 / arm64)

unzip runex-linux-x86_64.zip      # arm64: runex-linux-aarch64.zip
cd runex-linux-x86_64/
./install.sh
runex init && runex doctor

From source (developers, or platforms without a prebuilt binary)

git clone https://github.com/heyewong/runex.git
cd runex && git checkout dev
uv tool install .
runex init && runex doctor

No PyPI release: runex is distributed as prebuilt binaries only. The runex package on PyPI is an unrelated third-party project — do not run uv tool install runex.

Requirements: macOS 13+ (Apple Silicon), Windows 10+ (x64), or any modern Linux (x64 / arm64).

Common commands

runex init                    # bootstrap: create DB + load engine types (one-time)
runex doctor                  # health check: ontology & DB
runex node create "Q4 review" --tag Task -f "owner=me"   # write a typed object
runex query --tag Task --field "status=open"             # query the graph
runex connection configure vault --connector obsidian-markdown --recipe obsidian-mirror --source ~/Documents/MyVault --param path=~/Documents/MyVault
runex connection pull vault   # sync a connected source
runex ontology check          # validate loaded ontology
runex agent list              # registered agents + health
runex work list               # pending / running WorkItems
runex proposal list           # changes awaiting approval

Every subcommand has --help. Agents can drive the same operations through the runex skill. See the guide for installation and reference.

Tutorials — one story, four chapters

Follow a mine owner building a digital twin of their asteroid mine:

1. Daily business, in plain language — One sentence: build a CRM: customers, products, deals. No tech words needed.
2. The big one, hand-written — Asteroid mine digital twin: from one index card to an AI CEO's shutdown ruling — 9 lessons.
3. Grow a team — upgrade the single CEO into a board: fan-out, debate-and-judge, pipeline patterns (the finale of chapter 2).
4. Go unattended — Run it 24/7: listen daemon, scheduled scans, weekend cleanup.

Docs & development

• docs/guide — installation, tutorials, CLI reference
• docs/whitepaper.md — why agents need a durable ontology world
• docs/architecture.md — architecture, layers, invariants
• docs/adr/ — architecture decision records
• AGENT.md — contribution guide (branch model, versioning, verification habits)

License

The Runex core engine is open source under the MIT License — see LICENSE.