# Orch8 0.7.1 — AI-readable guide Orch8 is a self-hosted durable workflow and portable-continuity engine built in Rust. It persists execution state in PostgreSQL or SQLite, exposes a REST API and CLI, supports external workers and plugins, and embeds on iOS and Android. Release date: 2026-07-28 Git release: https://github.com/orch8-io/engine/releases/tag/v0.7.1 Website guide: https://orch8.io/docs/releases/0-7-0 ## Version convention - Git tag and GitHub release: `v0.7.1` - Binary, crate, SDK package, and OCI tag: `0.7.1` - Production image: `ghcr.io/orch8-io/engine:0.7.1` - Multi-architecture index digest: `sha256:80d23764e0dbbd3330ce853e068bf8b6215b6845e167dafcb140c636551aac39` ## Install and verify ```bash curl -fsSL https://raw.githubusercontent.com/orch8-io/engine/main/install.sh | sh orch8-server --version docker pull ghcr.io/orch8-io/engine:0.7.1 docker run --rm ghcr.io/orch8-io/engine:0.7.1 --version ``` For local evaluation with SQLite: ```bash docker run --rm -p 8080:8080 -p 50051:50051 \ ghcr.io/orch8-io/engine:0.7.1 --insecure ``` For PostgreSQL, explicitly set `ORCH8_RUN_MIGRATIONS=true` in the one process that owns schema changes. Storage encryption and API authentication are secure by default; use `--insecure-storage` and `--insecure-auth` only for local development. ## HTTP contract Canonical product base URL: ```text http://localhost:8080/api/v1 ``` New integrations should use `/api/v1`. Bare product routes remain compatibility aliases. Health probes, OpenAPI, and Swagger stay at root paths: - `GET /health/live` - `GET /health/ready` - `GET /info` - `GET /api-docs/openapi.json` - `/swagger-ui` Authenticated requests use: ```text x-api-key: x-tenant-id: ``` The running server's OpenAPI document is authoritative for exact request and response shapes. ## Sequence shape ```json { "tenant_id": "demo", "namespace": "default", "name": "welcome-flow", "id": "550e8400-e29b-41d4-a716-446655440000", "version": 1, "created_at": "2026-07-28T00:00:00Z", "blocks": [ { "type": "step", "id": "send_welcome", "handler": "http_request", "params": { "url": "https://api.example.com/welcome", "method": "POST", "body": { "email": "{{context.data.email}}" } }, "retry": { "max_attempts": 3, "initial_backoff": 1000, "max_backoff": 60000, "backoff_multiplier": 2.0 } } ] } ``` Core composite blocks include Step, Parallel, Race, Loop, ForEach, Router, TryCatch, SubSequence, ABSplit, CancellationScope, and Saga. Steps can declare `when`, retry policy, output schema, rate limits, concurrency keys, queues, compensation, and deadlines. ## Effect semantics Orch8 does not promise universal provider-level exactly-once behavior. - Committed step outputs are memoized and skipped on resume. - A crash after a provider observed an effect but before the receipt committed creates an unknown outcome. - In that crash window the fast path is at least once. - Use provider idempotency keys for email, payments, LLM calls, transactions, and other external effects. - Query `GET /api/v1/instances/{id}/effects?tenant_id=...` for effect history. - A declared `effect_at_most_once` invariant with `commit_guard` can select one dispatch winner for an effect identity. - Reconcile unknown outcomes before retrying; do not infer success or failure from timeout alone. Compensation is a new effect, not time travel: ```json { "type": "step", "id": "charge", "handler": "payments.charge", "params": { "amount": 4200 }, "compensation": { "handler": "payments.refund", "params": { "amount": 4200 }, "depends_on": ["reserve_inventory"], "verification": "provider_receipt" } } ``` The planner reverses only committed or verified effects. Runs may finish as `completed_with_residuals`; unresolved effects remain operator work. ## External worker protocol Poll: ```http POST /api/v1/workers/tasks/poll content-type: application/json { "handler_name": "send_email", "worker_id": "mail-worker-42", "limit": 10, "version": "1.4.2" } ``` A reclaimed task may contain `resume_checkpoint` and `checkpoint_seq`. Heartbeat and atomically replace the checkpoint: ```http POST /api/v1/workers/tasks/{id}/heartbeat { "worker_id": "mail-worker-42", "checkpoint_seq": 0, "checkpoint": { "completed_batches": 12, "cursor": "next-page-token" } } ``` The response returns the next sequence. A stale sequence or former owner receives 409. Checkpoints are limited to 256 KiB, encrypted at rest when encryption is enabled, and retained through lease recovery. Complete: ```json { "worker_id": "mail-worker-42", "output": { "message_id": "msg-123" } } ``` Fail: ```json { "worker_id": "mail-worker-42", "message": "SMTP connection refused", "retryable": true } ``` The worker protocol is at least once. Workers must make external effects idempotent. ### Current main after v0.7.1 (unreleased) Current main returns a monotonic `claim_epoch` with each claimed task. Heartbeat, complete, and fail bodies must echo it; a stale epoch receives 409. Attempt history is available at `GET /api/v1/workers/tasks/{id}/attempts`. These fields are not part of the stable 0.7.1 contract. Current main also adds `POST /api/v1/events/batch` for up to 100 PostgreSQL outbox events. `producer_event_id` is deduplicated by `(tenant_id, event_name, producer_event_id)`. See https://orch8.io/docs/releases/unreleased. Current main also completes the 1.0 authoring and distribution surface: recursive sequence JSON Schema and OpenAPI snapshots, `schema_version` and format upgrades, persistent local Studio by default, code-first TypeScript, Python, and Go builders, `orch8 generate`, MCP authoring tools, a reusable GitHub workflow gate, connector catalog commands, signed package registry commands, Windows binaries, and checksum-verifying npm/pipx launchers. See https://orch8.io/docs/authoring. ## Typed dataflow Declare sequence input schemas and step `output_schema` values. The compiler checks direct `data.*`, `outputs.*`, `state.*`, and `config.*` references. Contradictions are errors; dynamic or unprovable shapes remain explicit warnings. ```bash orch8 sequence dataflow --file checkout.json --out-dir generated orch8 sequence dataflow --id --out-dir generated ``` Output includes deterministic `types.ts`, `types.py`, `Types.swift`, `Types.kt`, `schema.json`, and `report.json`. The command exits non-zero on errors. ## Guarded releases Release path: ```text draft → validating → ready → canary → promoted └──────────→ failed ├──────→ paused → canary └──────→ rolled_back ``` ```bash export ORCH8_URL=http://127.0.0.1:8080/api/v1 export ORCH8_API_KEY='replace-me' export ORCH8_TENANT_ID=demo RELEASE_ID=$(orch8 --output json release create \ --tenant-id demo \ --baseline "$BASELINE_ID" \ --candidate "$CANDIDATE_ID" \ --max-error-regression 0.05 \ --min-sample 20 | jq -r '.id') orch8 release diff "$RELEASE_ID" orch8 release validate "$RELEASE_ID" --sample 20 orch8 release canary "$RELEASE_ID" --percent 10 orch8 release evaluate "$RELEASE_ID" orch8 release promote "$RELEASE_ID" ``` Historical validation never invokes real handlers. Missing evidence is divergence or inconclusive, never success. Promotion routes new executions; default `pin` leaves in-flight executions on their starting version. ## Portable Continuity 0.7.0 includes: - signed, encrypted execution capsules; - ownership epochs and immutable global location history; - runtime capability advertisements and locality/residency/trust placement; - placement-bound handoff and crash-safe redelivery; - object-store-independent cloud/device transfer; - dispatch-time effect receipt enforcement; - live migration with bounded copy/move/drop transforms and narrow rollback; - cryptographic provenance with optional historical signing-key registry; - checkpoint time travel and redacted diffs; - effect-free what-if comparisons; - deterministic fault-lab state-space exploration; - production evidence extraction into runnable contract fixtures; - bounded tumbling, sliding, and session windows; - destination-bound federation envelopes and replay receipts. Handoff creation requires both `placement_decision_id` and `preview_sha256` from a fresh preview. The engine re-evaluates live facts at creation and export. Hard policy denials cannot be overridden. Live migration CLI: ```text orch8 execution migration-plan plan.json orch8 execution migration-get --tenant-id tenant-a orch8 execution migration-apply approval.json orch8 execution migration-rollback rollback.json ``` Rollback fails after the target epoch dispatched, committed, verified, or lost certainty about an external effect. ## Agents and operations 0.7.0 also adds: - bounded tenant-scoped shared memory with instance scope as the default; - cumulative six-dimensional budget reservations and settlement; - leased human-attention assignment with payload-free decision digests; - effect-safe provider routing and failover; - stored-evidence evaluation gates with pending/inconclusive outcomes; - an optimization advisor that creates an auditable draft sequence and release; - DLQ root-cause fingerprints and automatic incident reproduction; - stuck-instance diagnosis and state-bound remediation previews; - template, webhook, and release evidence inspectors; - contract suites, scenario tests, preflight, and readiness checks; - bounded concurrent Parallel branches and cooperative priority preemption. ## Database upgrade Stable 0.7.1 PostgreSQL migrations extend through 074. Migration 074 converts `block_outputs` to 16 hash partitions by `instance_id` and `audit_log` to 16 hash partitions by `tenant_id`. Existing-table conversion requires a rewrite. Reserve a migration window, test against a production-sized copy, validate free space and locks, and designate one schema owner. Current main is unreleased and extends PostgreSQL through 081 and the bundled SQLite schema through version 40. Source builds require Rust 1.97 or later. ## Signed public webhooks Every public webhook trigger must have a secret. Send it to `POST /webhooks/{slug}`. The caller signs `timestamp + "." + nonce + "." + raw_body` and sends: ```text x-trigger-timestamp: x-trigger-nonce: x-orch8-signature: v1= ``` Unsigned public webhook requests are rejected. The timestamp may be at most 300 seconds old or 60 seconds in the future; the body limit is 1 MiB. Sign the exact bytes sent. The authenticated `/triggers/{slug}/fire` route is separate, and outbound webhooks use a separate timestamp-and-body signature contract. ## Official documentation - https://orch8.io/docs/releases/0-7-1 - https://orch8.io/docs/releases/0-7-0 - https://orch8.io/docs/releases/unreleased - https://orch8.io/docs/continuity - https://orch8.io/docs/quickstart - https://orch8.io/docs/api - https://orch8.io/docs/workers - https://orch8.io/docs/versioning - https://orch8.io/docs/configuration - https://orch8.io/docs/database - https://orch8.io/docs/mobile - https://orch8.io/changelog - https://github.com/orch8-io/engine ## Problem-led field guides - https://orch8.io/blog/state-snapshots-vs-event-replay - https://orch8.io/blog/exactly-once-workflow-execution - https://orch8.io/blog/workflow-side-effect-idempotency - https://orch8.io/blog/workflow-stuck-running-worker-checklist - https://orch8.io/blog/cron-vs-job-queue-vs-workflow-engine - https://orch8.io/blog/deploy-long-running-workflows-safely - https://orch8.io/blog/background-job-observability-metrics - https://orch8.io/blog/running-ai-agents-in-production - https://orch8.io/blog/stream-llm-output-durable-workflow-state - https://orch8.io/blog/human-in-the-loop-workflow-architecture - https://orch8.io/blog/self-hosted-workflow-engine-operations-checklist - https://orch8.io/blog/versioning-long-running-workflows - https://orch8.io/blog/offline-durable-workflows-mobile - https://orch8.io/blog/build-vs-buy-workflow-orchestrator These guides explain general engineering problems and cite official external sources. Product documentation, the running OpenAPI document, and tagged release notes remain authoritative for Orch8 behavior. ## Editorial authority - About: https://orch8.io/company/about - Editorial policy: https://orch8.io/company/editorial-policy - Corrections and contact: https://orch8.io/company/contact