Quick Start
Go from zero to a running sequence in under 2 minutes.
0. Install
# 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 # Go1. Start the engine
By default the engine requires an API key. For local development, use --insecure to skip authentication:
# Run the binary directly (local dev)
orch8-server --insecure
# Docker — zero config with SQLite (great for local dev)
docker run -d -p 8080:8080 -p 50051:50051 \
ghcr.io/orch8-io/engine:latest --insecure
# Docker with Postgres + auth (production)
docker run -d \
-e ORCH8_API_KEY="your-secret-key" \
-e ORCH8_STORAGE_BACKEND=postgres \
-e ORCH8_DATABASE_URL=postgres://user:pass@host:5432/orch8 \
-p 8080:8080 -p 50051:50051 \
ghcr.io/orch8-io/engine:latestThe engine runs migrations automatically on first start and begins listening on port 8080 (HTTP) and 50051 (gRPC) by default.
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.
curl -X POST http://localhost:8080/sequences \
-H "Content-Type: application/json" \
-d '{
"tenant_id": "demo",
"namespace": "default",
"name": "hello-world",
"definition": {
"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:
curl -X POST http://localhost:8080/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
# Get instance state
curl http://localhost:8080/instances/<uuid>
# See step outputs
curl http://localhost:8080/instances/<uuid>/outputs5. Control it
# Pause the instance
curl -X POST http://localhost:8080/instances/<uuid>/signals \
-H "Content-Type: application/json" \
-d '{ "signal_type": "pause" }'
# Resume it
curl -X POST http://localhost:8080/instances/<uuid>/signals \
-H "Content-Type: application/json" \
-d '{ "signal_type": "resume" }'
# Update context mid-run
curl -X POST http://localhost:8080/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.