Quick Start — Orch8 Docs

Quick Start#

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

0. Install

Bash

# macOS / Linux — one-line install
curl -fsSL https://raw.githubusercontent.com/orch8-io/engine/main/install.sh | sh

# Or with Homebrew
brew install orch8-io/orch8/orch8-server

# Or install just the CLI (Go)
brew install orch8-io/orch8/orch8-cli

# SDKs
npm install @orch8.io/sdk      # Node.js / TypeScript
pip install orch8-io-sdk       # Python
go get github.com/orch8-io/sdk-go  # Go

1. Start the engine

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

Bash

# Run the binary directly (local dev)
orch8-server --insecure

# Docker — zero config with SQLite (pin releases in production)
docker run -d -p 8080:8080 -p 50051:50051 \
  ghcr.io/orch8-io/engine:0.7.0 --insecure

# Docker with Postgres + auth (production)
docker run -d \
  -e ORCH8_API_KEY="your-secret-key" \
  -e ORCH8_ENCRYPTION_KEY="<64-hex-chars>" \
  -e ORCH8_STORAGE_BACKEND=postgres \
  -e ORCH8_DATABASE_URL=postgres://user:pass@host:5432/orch8 \
  -e ORCH8_RUN_MIGRATIONS=true \
  -p 8080:8080 -p 50051:50051 \
  ghcr.io/orch8-io/engine:0.7.0

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.

2. Define a sequence

A sequence is a reusable recipe. This example sends an HTTP request and logs a follow-up message. You can run it immediately — no setup needed.

Bash

curl -X POST http://localhost:8080/api/v1/sequences \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo",
    "namespace": "default",
    "name": "hello-world",
    "version": 1,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2026-07-28T00:00:00Z",
    "blocks": [
        {
          "type": "step",
          "id": "send_greeting",
          "handler": "http_request",
          "params": {
            "url": "https://httpbin.org/post",
            "method": "POST",
            "body": {
              "message": "Hello, {{context.data.name}}!"
            }
          }
        },
        {
          "type": "step",
          "id": "log_done",
          "handler": "log",
          "params": {
            "message": "Greeting sent to {{context.data.name}}"
          }
        }
    ]
  }'

Copy the id from the response — you will need it in the next step.

3. 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

curl -X POST http://localhost:8080/api/v1/instances \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_id": "<id-from-step-2>",
    "tenant_id": "demo",
    "namespace": "default",
    "context": {
      "data": { "name": "Alice" }
    }
  }'

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.

4. Check the status

Bash

# Get instance state
curl http://localhost:8080/api/v1/instances/<uuid>

# See step outputs
curl http://localhost:8080/api/v1/instances/<uuid>/outputs

5. Control it

Bash

# Pause the instance
curl -X POST http://localhost:8080/api/v1/instances/<uuid>/signals \
  -H "Content-Type: application/json" \
  -d '{ "signal_type": "pause" }'

# Resume it
curl -X POST http://localhost:8080/api/v1/instances/<uuid>/signals \
  -H "Content-Type: application/json" \
  -d '{ "signal_type": "resume" }'

# Update context mid-run
curl -X POST http://localhost:8080/api/v1/instances/<uuid>/signals \
  -H "Content-Type: application/json" \
  -d '{
    "signal_type": "update_context",
    "payload": { "replied": true }
  }'

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

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

Ready to try Orch8?

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

Bash

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

Quick Start Guide Or skip the setup with Cloud →

Previous← What's New in 0.7.0 NextUse Cases →