Quickstart
Start an Orcher engine on your machine, run a workflow, then crash its worker halfway through and watch the workflow finish anyway. Everything here comes from the public quickstart repository, and the same guide is on the website at orcher.io/quickstart.
What you'll build
An order workflow with two tasks and a durable timer between them:
1charge ──▶ sleep 10s ──▶ shipThe engine records every step as it finishes, and keeps the timer itself, so no process has to stay up while it runs. A worker that dies mid-order is replaced by a new one, which picks the order up where it stopped: it ships the order without charging it again.
Prerequisites
- Docker with Compose v2
- For the language you pick: Python 3.11 or later, Node.js 22 or later, or stable Rust
1. Start the engine
1git clone https://github.com/orcher-io/quickstart.git2cd quickstart3docker compose up -d --waitThis starts Postgres and the engine, which applies its database schema as it starts, with gRPC on localhost:50051 and health checks on localhost:8080/health/ready. Authentication is off: this engine is for your machine only.
Port taken? Pick others, and point the examples at the new gRPC port:
1ORCHER_GRPC_PORT=50061 ORCHER_HTTP_PORT=8081 docker compose up -d --wait2export ORCHER_URL=http://localhost:500612. Run a worker
A worker connects to the engine, registers the workflow and its tasks, and runs them. Pick a language and leave the worker running in its own terminal.
1cd python2python3 -m venv .venv && source .venv/bin/activate3pip install -r requirements.txt4python worker.pyThe workflow and its tasks, from python/worker.py:
1@task(name="charge")2async def charge(ctx: TaskContext, order_id: str) -> str:3 # Tasks are where side effects go: call the payment API here.4 print(f"charged {order_id}", flush=True)5 return f"charged {order_id}"678@task(name="ship")9async def ship(ctx: TaskContext, order_id: str) -> str:10 print(f"shipped {order_id}", flush=True)11 return f"shipped {order_id}"121314@workflow(name="order")15async def order(ctx: WorkflowContext, order_id: str) -> str:16 charged = await ctx.execute_task(charge, order_id=order_id)17 # A durable timer: the engine keeps it, so a worker restart doesn't reset it.18 await ctx.sleep(timedelta(seconds=10))19 shipped = await ctx.execute_task(ship, order_id=order_id)20 return f"{charged}, then {shipped}"3. Start a workflow
In a second terminal, in the same directory, start an order and wait for it:
1python start.py # Python2npm run start-workflow # TypeScript3cargo run --bin start # RustThe worker prints charged order-…, then shipped order-… ten seconds later, and the starter prints the workflow's result:
1started workflow order-3f9c1a7e2result: charged order-3f9c1a7e, then shipped order-3f9c1a7e4. Kill the worker mid-run and watch it resume
- Start another order, as in step 3.
- When the worker prints
charged order-…, the workflow is sleeping. Stop the worker with Ctrl+C, or kill it outright. - The starter keeps waiting: the order is safe in the engine, not in the worker. Start the worker again, as in step 2.
- The new worker prints
shipped order-…once the ten seconds are up, and the starter prints the result. It never printschargedagain: the charge already happened, so the workflow resumes after it.
scripts/kill-and-resume.sh does the same with kill -9, and fails unless the order was charged exactly once and shipped by the second worker:
1scripts/kill-and-resume.sh python # or typescript, or rustIt runs the examples from their directories, so install them first, as in step 2 (for Rust, cargo build --bins; for Python, set PYTHON to your virtualenv's interpreter if it isn't active).
When you're done, docker compose down -v stops the engine and deletes its data.
The engine image
ghcr.io/orcher-io/orcher:0.7.0 is the engine, open source under the Apache License 2.0 (orcher-io/orcher), like the quickstart and the SDKs. Its license ships in the image as /LICENSE, beside /THIRD_PARTY_NOTICES, which lists the open-source components built into the engine with their own licenses:
1docker compose exec orcher cat /LICENSE2docker compose exec orcher cat /THIRD_PARTY_NOTICESNext steps
Each SDK's README covers retries, events, child workflows, actors and testing:
| Language | SDK | Package |
|---|---|---|
| Python | orcher-io/sdk-py | orcher-sdk on PyPI |
| TypeScript | orcher-io/sdk-ts | @orcher/sdk on npm |
| Rust | orcher-io/sdk-rust | orcher-sdk on crates.io |
Beneath them, orcher-io/sdk-core is the core the SDKs share, and orcher-io/protos holds the Protocol Buffer definitions of the API they speak.
Then read on in these docs:
- Understanding Orcher: the concepts behind workflows, tasks and durable execution
- Workflows and tasks: writing your own