A self-hosted, durable workflow orchestration engine built in Rust. Define workflows as composable JSON sequences. Orch8 guarantees every step either completes, retries, or surfaces in a dead-letter queue.
Single binary. One dependency: PostgreSQL (or SQLite for dev/embedded).
Docs · Discord · Cloud · Playbook
Existing durable workflow engines either ship a multi-service cluster (Temporal: Cassandra + Elasticsearch + JVM workers) or assume Python everywhere (Airflow: Celery + Redis + scheduler). Both are full-time operational jobs on a small team.
Orch8 keeps the execution model — state-snapshot durability, retries, replay-on-restart — but trades the ecosystem for one Rust binary and Postgres. Workers in any language via REST long-poll. Higher-level building blocks (Parallel, Race, TryCatch, CancellationScope, plus LLM/HumanReview/ToolCall) shipped as first-class instead of patterns you build on activities.
Workflow Primitives — Step, Parallel, Race, TryCatch, Loop, ForEach, Router, SubSequence, CancellationScope, AB Split
Scheduling — Relative delays, business-days-only with holiday awareness, timezone-per-instance, jitter, send windows, cron triggers with configurable tick interval
Rate Limiting — Per-resource sliding window with deferred scheduling (not rejection), resource pools with weighted rotation, daily caps, and warmup ramps
Reliability — Crash recovery via state snapshots, configurable retry with exponential backoff, dead letter queue, idempotency keys, circuit breakers with fallback handler routing and persistent state
Concurrency — Per-entity key control, priority queues (Low/Normal/High/Critical), bulk create/pause/resume/cancel, batch instance creation (up to 10k)
Multi-tenancy — Tenant-scoped queries, per-tenant rate limits, per-tenant circuit breakers, tenant isolation middleware, per-tenant noisy-neighbor protection
Extensibility — External workers (any language via REST polling), gRPC sidecar plugins, WASM plugins, webhook events, workflow interceptors, emit-event with deduplication
Observability — Prometheus metrics, structured JSON logging, audit log, execution tree visualization, Grafana dashboard template
AI Agent Support — Unified llm_call handler covering all major providers (OpenAI, Anthropic, Gemini + 7 more), dynamic step injection (self_modify), human-in-the-loop with timeout/escalation, SSE streaming, query-instance handler for cross-workflow coordination
Security — AES-256-GCM encryption at rest for context and credentials, OAuth2 credential refresh, API key authentication, CORS configuration
# Docker (fastest)
docker run -d -p 8080:8080 ghcr.io/orch8-io/engine:latest
# Binary release (downloads from GitHub releases)
curl -fsSL https://raw.githubusercontent.com/orch8-io/engine/main/install.sh | sh
# Homebrew
brew tap orch8-io/orch8 && brew install orch8-server# Initialize a project
orch8 init my-project
cd my-project
# Start the engine (--insecure skips API key requirement)
orch8-server --insecuredocker compose up -d # starts Postgres + enginecurl -X POST http://localhost:8080/sequences \
-H 'Content-Type: application/json' \
-d '{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tenant_id": "demo",
"namespace": "default",
"name": "hello-world",
"version": 1,
"blocks": [
{ "type": "step", "id": "greet", "handler": "noop", "params": {} }
]
}'curl -X POST http://localhost:8080/instances \
-H 'Content-Type: application/json' \
-d '{
"sequence_id": "550e8400-e29b-41d4-a716-446655440000",
"tenant_id": "demo",
"namespace": "default",
"context": { "data": { "user": "alice" } }
}'All SDKs live in their own repositories under the orch8-io GitHub organization.
| Language | Package | Install | Repo |
|---|---|---|---|
| TypeScript | @orch8.io/sdk |
npm install @orch8.io/sdk |
sdk-node |
| Python | orch8-io-sdk |
pip install orch8-io-sdk |
sdk-python |
| Go | github.com/orch8-io/sdk-go |
go get github.com/orch8-io/sdk-go |
sdk-go |
The TypeScript SDK includes both workflow authoring (sequence builder, deploy via REST) and worker support (task polling, handler registration, concurrent execution).
orch8-server Binary entry point, config loading, signal handling
|
orch8-api REST (axum) + SSE streaming, OpenAPI via utoipa
|
orch8-grpc gRPC service (tonic) for high-throughput clients
|
orch8-engine Scheduler, evaluator, handlers, signals, cron,
| circuit breakers, recovery, sequence cache
|
orch8-storage StorageBackend trait + Postgres + SQLite + encrypting wrapper
|
orch8-types Domain types, config, IDs, errors
|
orch8-cli CLI tool (init, sequence, instance, signal, health)
Key design decisions:
- Postgres is the timer wheel (zero engine memory for scheduled instances)
FOR UPDATE SKIP LOCKEDprevents double-claiming across nodes- State machine enforced at type level
- Snapshot-based resume — no history replay, no determinism constraints
- Semaphore-bounded concurrency for step execution
- Circuit breaker state persisted to storage (survives restarts)
- Sequence cache with TTL eviction for hot-path lookups
Configuration via orch8.toml, environment variables (ORCH8_*), or both (env vars override file).
| Variable | Default | Description |
|---|---|---|
ORCH8_STORAGE_BACKEND |
postgres |
sqlite or postgres |
ORCH8_DATABASE_URL |
— | Connection string (required) |
ORCH8_HTTP_ADDR |
127.0.0.1:8080 |
HTTP API listen address |
ORCH8_GRPC_ADDR |
127.0.0.1:50051 |
gRPC API listen address |
ORCH8_TICK_INTERVAL_MS |
100 |
Scheduler tick interval (ms) |
ORCH8_CRON_TICK_SECS |
10 |
Cron loop check interval (seconds) |
ORCH8_BATCH_SIZE |
256 |
Max instances claimed per tick |
ORCH8_MAX_CONCURRENT_STEPS |
128 |
Semaphore limit for step execution |
ORCH8_MAX_INSTANCES_PER_TENANT |
0 |
Per-tenant claim limit (0 = unlimited) |
ORCH8_ENCRYPTION_KEY |
— | 64 hex chars for AES-256-GCM encryption at rest |
ORCH8_LOG_LEVEL |
info |
trace, debug, info, warn, error |
ORCH8_LOG_JSON |
false |
JSON-formatted log output |
ORCH8_CORS_ORIGINS |
— | CORS allowed origins (empty = no CORS headers) |
ORCH8_API_KEY |
— | Set to require API key auth |
See Configuration Reference for the full list.
59 documented REST endpoints covering:
- Sequences — CRUD, versioning, deprecation, migration, by-name lookup
- Instances — create, batch create, list/filter, state transitions, context update, retry, DLQ
- Signals — send pause/resume/cancel/context signals to running instances
- Workers — task polling, completion, failure, heartbeat, stats, queue-based routing
- Cron — CRUD with expression validation, enable/disable, trigger history
- Triggers — webhook and event-driven instance creation
- Sessions — stateful multi-instance coordination
- Pools — resource pool management with weighted allocation
- Credentials — encrypted credential vault with OAuth2 refresh
- Circuit Breakers — per-tenant/handler state, manual reset
- Plugins — WASM and gRPC plugin registration
- Approvals — human-in-the-loop approval inbox
- Cluster — node listing, heartbeat, drain
- Health — liveness, readiness, Prometheus metrics
# Start Postgres
docker compose up -d
# Build
cargo build --workspace
# Unit tests
cargo test --workspace
# Lint
cargo clippy --workspace -- -D warnings
# Format
cargo fmt --check
# E2E tests (TypeScript)
cd tests/e2e && npm ci && npm test
# E2E tests (Rust)
cargo test --test '*' --workspace2,028 tests across two layers:
| Layer | Tests | Scope |
|---|---|---|
| Rust unit + integration | 1,255 | Storage backends, evaluator, scheduler, handlers, config parsing, state machine transitions, gRPC auth, full engine integration |
| TypeScript E2E | 773 | 202 test files hitting the live HTTP API — sequences, instances, workers, cron, triggers, webhooks, approvals, sessions, plugins, credentials, pools, cluster, SSE streaming |
Coverage by feature area:
| Area | Test suites |
|---|---|
| Blocks | Step, Parallel, Race, TryCatch, Loop, ForEach, Router, SubSequence, CancellationScope, AB Split |
| Handlers | Built-in handlers, external worker dispatch, LLM call, query-instance |
| Features | Rate limiting, resource pools, circuit breakers, encryption, credentials, multi-tenancy |
| Signals | Pause/resume/cancel, context update, terminal guards |
| Scheduling | Cron CRUD, business days, timezone/DST, jitter, send windows, SLA timers |
| Mixing | Complex sequences combining multiple block types and features |
| Resilience | Crash recovery, retry, DLQ, idempotency, checkpoint/restore |
| Security | API key auth, CORS, encryption at rest, tenant isolation |
| Templating | Context expressions, dynamic params, conditional logic |
| Observability | Prometheus metrics, audit log, health endpoints, SSE streaming |
engine/
orch8-api/ REST API layer (axum + utoipa)
orch8-cli/ CLI binary
orch8-engine/ Core scheduler, evaluator, handlers
orch8-grpc/ gRPC service (tonic + protobuf)
orch8-server/ Server binary, config, startup
orch8-storage/ Storage trait + Postgres + SQLite impls
orch8-types/ Shared domain types and config
proto/ Protobuf service definitions
migrations/ 29 SQL migrations (Postgres schema)
tests/e2e/ 202 TypeScript E2E test files (773 test cases)
loadgen/ Load generator with per-template metrics
activepieces/ Activepieces sidecar integration
dashboard/ React admin dashboard
examples/ Example workflows (email classifier, etc.)
scripts/ Dev scripts (dev-up, dev-down)
docs/ Documentation
- Quick Start — zero to first completed instance in 5 minutes
- Sequences — build, publish, trigger, and extend sequences (the workflow format)
- API Reference — REST endpoints, block types, error codes
- Architecture — execution model, schema, performance
- Configuration — all config options and env vars
- Deployment — production deploys (Docker, Kubernetes, managed cloud)
- External Workers — writing handlers in any language
- Applications — embedding patterns and use cases
- Webhooks — event schema and delivery semantics
- Externalized State — how oversized payloads are offloaded
- Agent Patterns — example sequences for AI agents
- Changelog
docker run -d \
-p 8080:8080 \
-e ORCH8_DATABASE_URL=postgres://user:pass@host:5432/orch8 \
ghcr.io/orch8-io/engine:latesthelm repo add orch8 https://orch8-io.github.io/helm-charts
helm install orch8 orch8/orch8-engineChart repo: orch8-io/helm-charts
- Discord — questions, patterns, show & tell
- GitHub Issues — bug reports and feature requests
- Playbook — 22 workflow patterns with full JSON definitions
Pre-1.0. This is the public release of an engine that has been running my own production for several months, with 2,028 tests covering core paths. Honest about what it isn't yet:
- Not battle-tested at Temporal-scale. Largest internal load test: ~10K concurrent instances. If you're past that or have multiple engineers depending on uptime, run Temporal until 1.0.
- No replay debugger or time-skipping test tooling. Temporal's SDKs ship deterministic replay + timer-skip helpers; we don't.
- Workflow versioning is younger. Sequence definitions are versioned, but the migration ergonomics for in-flight instances aren't as polished as Temporal's
GetVersion/ patch system. - SDK depth varies. TypeScript SDK has both authoring + worker support; Go and Python SDKs are worker-focused for now.
- API is stable but evolving. Pre-1.0 means breaking changes are possible; we'll mark them in releases and keep them minimal.
If any of these are dealbreakers, file an issue — the gap-to-feature roadmap is driven by what users hit first.
This project is licensed under the Business Source License 1.1 (BUSL-1.1).
You can:
- Use Orch8 in production for your own applications
- Modify and extend the source code
- Self-host for your team or company
You cannot:
- Offer Orch8 as a hosted or embedded service to third parties competing with us
The license converts to Apache 2.0 four years from publication.
Don't want to self-host? orch8.io/pricing — we run it for you.
Want to embed Orch8 in your SaaS product or offer it as a managed service? Contact hello@orch8.io for commercial licensing.