Orion is a declarative services runtime. An Orion service consists of a
workflow and a channel, with optional connectors to external systems.
Deploy those definitions and the service is live, without writing
an application server, building a container for each service, or restarting the
runtime.
Orion consistently handles the surrounding infrastructure: routing, ingress
guards, rate limits, timeouts, retries, circuit breakers, connection pooling,
immutable deployments, rollback, metrics, and tracing. Definitions can be
written by a developer or proposed by an AI assistant; they follow the same
lint, test, deploy, and audit path.
NOTE
Orion is designed for request- and event-shaped work expressible as ordered
task functions and JSONLogic. It is not a general-purpose application runtime
or a durable workflow engine. See When Orion fits before
choosing it for a project.
Quickstart
This tested path uses Docker, curl, jq, and a POSIX-compatible shell. It starts a
local Orion instance, deploys an order-processing workflow and channel, and
calls the resulting API.
1. Start Orion
docker run --name orion-quickstart -d -p 8080:8080 \
ghcr.io/goplasmatic/orion:latest
curl --retry 10 --retry-delay 1 --retry-connrefused \
http://localhost:8080/healthz
2. Deploy a workflow and a channel
Upload each definition, then deploy both as revision 1:
A=http://localhost:8080/api/v2/admin
WF=$(curl -fsS -X POST $A/definitions -H 'Content-Type: application/json' -d '{
"kind": "workflow",
"definition": {
"name": "High-Value Order",
"tasks": [
{ "id": "parse", "function": { "name": "parse_json",
"input": { "source": "payload", "target": "order" } } },
{ "id": "flag", "condition": { ">": [{ "var": "data.order.total" }, 10000] },
"function": { "name": "map", "input": { "mappings": [
{ "path": "data.order.flagged", "logic": true } ] } } }
]
}
}' | jq -r .digest)
CH=$(curl -fsS -X POST $A/definitions -H 'Content-Type: application/json' -d '{
"kind": "channel",
"definition": { "name": "orders", "channel_type": "sync", "protocol": "rest",
"route_pattern": "/orders", "methods": ["POST"] }
}' | jq -r .digest)
MANIFEST=$(jq -n --arg wf "$WF" --arg ch "$CH" '{
schema_version: 2, providers: [], members: [
{ entity: { kind: "channel", id: "orders", revision: 1 }, definition_digest: $ch,
requires: [{ kind: "workflow", id: "quickstart-orders", revision: 1 }] },
{ entity: { kind: "workflow", id: "quickstart-orders", revision: 1 }, definition_digest: $wf }
]
}')
REVIEWED=$(jq -n --argjson manifest "$MANIFEST" \
'{ base_revision: 0, manifest: $manifest }' \
| curl -fsS -X POST $A/deployment-plans -H 'Content-Type: application/json' --data @- \
| jq -r .reviewed_manifest_digest)
jq -n --argjson manifest "$MANIFEST" --arg reviewed "$REVIEWED" '{
idempotency_key: "quickstart-1", base_revision: 0, reason: "quickstart",
reviewed_manifest_digest: $reviewed, manifest: $manifest
}' | curl -fsS -X POST $A/deployments -H 'Content-Type: application/json' --data @-
Each upload answers the definition's digest. The plan answers the reviewed
manifest digest, and the deployment names it with both definition digests and
commits them as the node's first revision. With a definition set on disk,
orion-cli compile and orion-cli deployments apply -d do these steps for
you.
3. Call your service
curl -fsS -X POST http://localhost:8080/api/v2/data/orders \
-H 'Content-Type: application/json' \
-d '{ "data": { "order_id": "ORD-0001", "total": 12500 } }'
The response contains the parsed order with "flagged": true. The workflow
holds the business logic; the channel exposes it at POST /orders. Routing,
validation, tracing, and deployment are supplied by Orion.
For expected output, troubleshooting, Windows-friendly installation paths, and
cleanup instructions, follow the
complete quickstart.
The core model
flowchart LR
Request["HTTP request or schedule"] --> Channel
Channel["Channel<br/>route + ingress policy"] --> Workflow
Workflow["Workflow<br/>ordered business logic"] --> Connector
Connector["Connector<br/>external system"]
Workflow --> Response["Response or stored trace"]
| Primitive | Purpose | Example |
|---|
| Channel | Receives traffic and applies ingress policy | POST /orders, GET /users/{id}, 0 15 2 * * * |
| Workflow | Runs the business logic as an ordered task pipeline | Parse → validate → enrich → respond |
| Connector | Provides a reusable connection to an external system | PostgreSQL, a REST API, a cache |
A node serves one deployment: a manifest naming every channel, workflow,
connection and plugin it runs. Each change commits a new immutable revision, so
rolling back is committing an earlier one again.
How Orion works
explains request execution, composition, deployment topology, and extension
boundaries in one page.
What you can build
- Microservice and decision APIs: expose transformations, validation,
pricing, eligibility, and routing decisions over HTTP.
- Webhook and data-ingestion services: normalize incoming payloads and
read or write external systems through governed connectors.
- AI-agent tools: expose governed HTTP operations that an assistant can
author, dry-run, deploy, and roll back using the Orion CLI and agent skill.
- Scheduled jobs: run a workflow on a cron expression instead of on a
request, with every scheduled instant recorded as a durable occurrence.
- Composable services: call another channel in-process with
channel_call,
while preserving the callee's guards and preventing cycles.
Choose a focused path in
What are you building?,
or deploy a tested package from examples/packages/.
Runtime capabilities
| Area | Included capability |
|---|
| Traffic | REST, plain HTTP, synchronous and asynchronous channels, cron schedules |
| Safety | Payload validation, API-key/HMAC/JWT channel auth, rate limiting, backpressure, CORS controls |
| Resilience | Timeouts, retries, circuit breakers, idempotency, response caching, dead-letter handling |
| Delivery | Offline lint and dry-runs, immutable deployment revisions, plan and apply, rollback, WebAssembly plugins |
| Observability | Health and readiness endpoints, Prometheus metrics, structured logs, OpenTelemetry traces |
| Data | PostgreSQL, MySQL, SQLite, HTTP, an in-process cache |
| Operations | Embedded SQLite for one node; one shared PostgreSQL/MySQL for clustered replicas |
Configuration is explicit, and several production controls are permissive or
disabled for local development. In particular, data channels are open unless
they declare authentication or sit behind an authenticating proxy. Before
exposing an instance, work through the
production checklist.
Safe changes, including AI-generated ones
flowchart LR
Author --> Lint --> DryRun["Dry-run"] --> Plan --> Apply --> Observe
Observe -->|problem| Rollback
Workflow, channel, and connector definitions take the same governed path
regardless of who authored them. You lint and dry-run them offline, plan the
deployment to see exactly what changes, and apply it without restarting the
server. Each apply is an immutable revision, and a rollback commits an earlier
one again. Administrative changes are recorded in the audit log.
For AI-assisted authoring, install the Orion agent
skill or use the self-contained
prompt pack. The
Claude Code tutorial walks
through a complete assisted workflow.
When Orion fits
Orion fits services whose work starts with an HTTP request or a schedule,
completes as a bounded pipeline, and can be expressed with Orion's task
functions and JSONLogic. It is especially useful when many small services need
the same operational and governance foundation.
Choose another runtime, or pair one with Orion, when:
- work must survive restarts at an intermediate step or wait hours or days;
- ingress requires gRPC, WebSockets, or streaming responses;
- business logic requires arbitrary code with I/O, or a scripting runtime — a
pure transformation ships as a sandboxed WebAssembly plugin, anything that
has to reach another system does not;
- image processing, model inference, or large in-memory joins sit on the
hot path; or
- full OIDC flows or mutual TLS must terminate inside the data plane. JWT
verification is built in; those flows require a gateway or service mesh.
Read Is Orion right for
you? for detailed comparisons
with durable execution engines, API gateways, automation platforms, rule
engines, and embedded dataflow-rs.
Install
The current workspace release is 2.0.0-rc.1 and requires Rust 1.98 when built
from source. The CLI is built from its own
repository against each server
release and versioned with it; use matching versions.
brew install GoPlasmatic/tap/orion-server
brew install GoPlasmatic/tap/orion-cli
cargo install --git https://github.com/GoPlasmatic/Orion --locked orion-server
cargo install --git https://github.com/codetiger/Orion-cli --locked orion-cli
Release installers are also available for Linux, macOS Apple Silicon, and
Windows. See Install &
Run for every method,
platform support, startup, and verification.
Useful local commands:
orion-server validate-config -c config.toml
orion-cli fmt ./definitions
orion-cli lint workflow.json
orion-cli clippy ./definitions
orion-cli dry-run -w workflow.json -i input.json
orion-cli test examples/workflow-tests
orion-cli compile ./definitions -o dist/deployment
orion-cli deployments apply -d dist/deployment
The server command
reference
and Orion CLI reference list
all commands and flags.
Upgrading from v1 to v2 (Breaking Changes)
Orion 2 moves every route from /api/v1/* to /api/v2/*, replaces per-entity writes with immutable deployments of content-addressed definitions, pages every list by cursor, and starts from a fresh state database: a 1.x database is refused at startup and nothing converts one. Recompile your definition set with orion-cli compile, deploy it with orion-cli deployments apply -d, and move the clients.
The Upgrade to 2.0.0 guide lists every change; Move from Orion 1.x is the procedure.
In the historical Orion 1.0.0 baseline benchmark, a single Apple M2 Pro instance
measured 5.1K–5.7K workflow requests per second with single-digit-millisecond
average latency across the recorded workflow scenarios. These are historical
release- and workload-specific results, not capacity guarantees for 2.x. Review
the benchmark record
for hardware, scenarios, tail latency, cluster results, and reproduction steps.
Documentation
The full manual is at docs.goplasmatic.io.
The documentation source lives in its own repository,
GoPlasmatic/Orion-docs, shared by
the Community and Enterprise editions. Its STYLE_GUIDE.md covers structure and
editorial conventions.
Project and community
Orion is built by Plasmatic and released under the
Apache License 2.0.