Quick Start

Choose the current-main local Studio path for the shortest setup, or use the stable 0.7.1 server/API path below when you need a released artifact.

Note

Current main: orch8 init my-projectthen orch8 dev my-project. The CLI starts a persistent SQLite-backed Studio at http://localhost:8080, watches the project for changes, and avoids the manual API bootstrap below. This behavior is not yet in the 0.7.1 release.

Bash

1orch8 init my-project
2orch8 dev my-project
3
4# One-shot CI smoke test
5orch8 dev my-project --no-server --skip-timers --once

1. Install

Recommended for macOS and Linux: use the release installer. It verifies the archive checksum before installing. Current main also publishes a native Windows binary and a checksum-verifying PowerShell installer; stable 0.7.1 Windows users should use Docker Desktop or WSL 2.

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 and.tar.gz.sha256 checksum file from GitHub Releases. In the download directory, run sha256sum -c <archive>.sha256(or shasum -a 256 -c <archive>.sha256 on macOS), then extract the archive and 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_STORAGE_BACKEND=sqlite ORCH8_DATABASE_URL=./orch8-quickstart.db orch8-server --insecure &
3
4# Verify: a healthy engine returns HTTP 200
5curl --fail -i http://localhost:8080/health/ready
6
7# Alternative: Docker Desktop — stop the native process before using the same ports
8docker run -d -p 127.0.0.1:8080:8080 -p 127.0.0.1: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.

Choose either the native process or Docker. The native command stores workflow state in ./orch8-quickstart.db in your working directory.

Expected response: HTTP 200; the readiness response has no JSON body. If the command is not found, add~/.local/bin to PATH. If port 8080 is busy, stop the existing process or set ORCH8_HTTP_ADDR=127.0.0.1:18080 to a free address.

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. Send X-Tenant-Id: demo on product API requests, including local requests made with authentication disabled.

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.

Keep the SDK client and returned IDs for subsequent steps in the same program. Node.js examples use ES modules with top-level await. Run Python snippets inside an async function (started with asyncio.run) or a notebook that supports top-level await. Add later Go snippets inside the same main function.

Bash

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

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 -H "X-Tenant-Id: demo" "http://localhost:8080/api/v1/instances/$INSTANCE_ID"
3
4# See step outputs
5curl -H "X-Tenant-Id: demo" "http://localhost:8080/api/v1/instances/$INSTANCE_ID/outputs"

6. Control a running workflow

The two log steps usually finish before you reach this section. Use the commands below with an instance that is still running or waiting, replacing its ID. These controls do not restart a completed instance. See the signals reference for supported lifecycle operations.

Bash

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

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)NextAuthoring Tools →

Was this helpful?