Quick Start

Install the engine, define a sequence, and run it locally.

1. Install

Recommended for macOS and Linux: use the release installer. It verifies the archive checksum before installing. Windows users should use Docker Desktop or WSL 2; a native Windows binary is not currently published.

Bash

1# macOS / Linux — one-line install
2curl -fsSL https://raw.githubusercontent.com/orch8-io/engine/main/install.sh | sh
3
4# macOS — Homebrew alternative
5brew install orch8-io/orch8/orch8-server
6
7# Install just the CLI (Go)
8brew install orch8-io/orch8/orch8-cli
9
10# SDKs
11npm install @orch8.io/sdk      # Node.js / TypeScript
12pip install orch8-io-sdk       # Python
13go get github.com/orch8-io/sdk-go  # Go

Prefer a manual, auditable install? Download the release archive andSHA256SUMS from GitHub Releases, runsha256sum -c SHA256SUMS, then place the binary on PATH.

2. Start the engine and verify it

By default the engine requires an API key. For local development, use --insecure to skip authentication:

Bash

1# Run the binary directly (local development only)
2orch8-server --insecure &
3
4# Verify: a healthy engine returns HTTP 200
5curl --fail http://localhost:8080/health
6
7# Docker Desktop — Windows, macOS, or Linux
8docker run -d -p 8080:8080 -p 50051:50051 \
9  ghcr.io/orch8-io/engine:0.7.1 --insecure

Local development only: --insecure disables authentication. Never expose that process to a public or shared network.

Expected response: status: ok. If the command is not found, add~/.local/bin to PATH. If port 8080 is busy, stop the existing process or set ORCH8_HTTP_PORT to a free port.

For production, generate separate random encryption and API keys:

Bash

1export ORCH8_ENCRYPTION_KEY="$(openssl rand -hex 32)"
2export ORCH8_API_KEY="$(openssl rand -hex 32)"
3
4docker run -d \
5  -e ORCH8_API_KEY \
6  -e ORCH8_ENCRYPTION_KEY \
7  -e ORCH8_STORAGE_BACKEND=postgres \
8  -e ORCH8_DATABASE_URL=postgres://user:pass@host:5432/orch8 \
9  -e ORCH8_RUN_MIGRATIONS=true \
10  -p 8080:8080 -p 50051:50051 \
11  ghcr.io/orch8-io/engine:0.7.1

SQLite initializes its embedded schema automatically. PostgreSQL migrations are opt-in; set ORCH8_RUN_MIGRATIONS=truefor a controlled migration job or first start. HTTP listens on port 8080 and gRPC on 50051 by default.

Product endpoints are canonical under /api/v1, as used below. Bare product routes remain compatibility aliases.

3. Define a sequence

A sequence is a reusable recipe. This zero-dependency example logs two messages, so it works without an external service or credentials.

Bash

1curl -X POST http://localhost:8080/api/v1/sequences \
2  -H "Content-Type: application/json" \
3  -d '{
4    "tenant_id": "demo",
5    "namespace": "default",
6    "name": "hello-world",
7    "version": 1,
8    "id": "550e8400-e29b-41d4-a716-446655440000",
9    "created_at": "2026-07-28T00:00:00Z",
10    "blocks": [
11        {
12          "type": "step",
13          "id": "send_greeting",
14          "handler": "log",
15          "params": {
16            "message": "Hello, {{context.data.name}}!"
17          }
18        },
19        {
20          "type": "step",
21          "id": "log_done",
22          "handler": "log",
23          "params": {
24            "message": "Greeting sent to {{context.data.name}}"
25          }
26        }
27    ]
28  }'
29
30# Expected: the response includes the id supplied above.
31# {"id":"550e8400-e29b-41d4-a716-446655440000", ...}

The cURL example supplies a stable sequence ID. Keep it in a shell variable for the next step:

Bash

1export SEQUENCE_ID="550e8400-e29b-41d4-a716-446655440000"

4. Schedule a task instance

An instance is one execution of a sequence. Pass in the context data (in this case, a name) and the engine will run the sequence:

Bash

1curl -X POST http://localhost:8080/api/v1/instances \
2  -H "Content-Type: application/json" \
3  -d '{
4    "sequence_id": "'"$SEQUENCE_ID"'",
5    "tenant_id": "demo",
6    "namespace": "default",
7    "context": {
8      "data": { "name": "Alice" }
9    }
10  }'
11
12# Expected: {"id":"6ba7b810-9dad-41d1-80b4-00c04fd430c8","state":"scheduled",...}
13export INSTANCE_ID="6ba7b810-9dad-41d1-80b4-00c04fd430c8"

The engine runs the first step immediately, then the second. Even if you restart the engine mid-run, it will resume from the last completed step.

5. Check the status

Bash

1# Get instance state
2curl "http://localhost:8080/api/v1/instances/$INSTANCE_ID"
3
4# See step outputs
5curl "http://localhost:8080/api/v1/instances/$INSTANCE_ID/outputs"

6. Control it

Bash

1# Pause the instance
2curl -X POST "http://localhost:8080/api/v1/instances/$INSTANCE_ID/signals" \
3  -H "Content-Type: application/json" \
4  -d '{ "signal_type": "pause" }'
5
6# Resume it
7curl -X POST "http://localhost:8080/api/v1/instances/$INSTANCE_ID/signals" \
8  -H "Content-Type: application/json" \
9  -d '{ "signal_type": "resume" }'
10
11# Update context mid-run
12curl -X POST "http://localhost:8080/api/v1/instances/$INSTANCE_ID/signals" \
13  -H "Content-Type: application/json" \
14  -d '{
15    "signal_type": "update_context",
16    "payload": { "replied": true }
17  }'

That's it. The engine handles crash recovery, retries, rate limits, and timezone-aware scheduling automatically.

Delay values such as delay.duration are milliseconds;10000 means 10 seconds. Continue with the CLI reference for interactive status, logs, and validation commands.

What's next

Defining Sequences

Block types, delays, and context access

Built-in Handlers

http_request, log, sleep, llm_call

REST API

Guide + generated OpenAPI

Core Concepts

How the engine works under the hood

CLI Reference

Validate, inspect, and control workflows

Ready to try Orch8?

One command to install. Then run your first local sequence.

Bash

1curl -fsSL https://orch8.io/start.sh | sh

Quick Start Guide Or skip the setup with Cloud →

Previous← Current Main (Unreleased)NextTask Guides →

Was this helpful?