obelisk: Open Source Orchestration & Scheduling

What is obelisk?

Obelisk is a durable and deterministic workflow engine written in Rust and built on the WASM Component Model, aimed at developers who need replayable, crash-resilient background jobs, periodic tasks, batch work, and webhook-driven pipelines.

What it is

Obelisk is a workflow engine distributed as a single binary that executes deterministic workflows, activities, and webhook endpoints, persisting every step in an execution log stored in SQLite or PostgreSQL. It is built on the WASM Component Model and uses the WIT IDL for schema-first, end-to-end type-safe definitions, so functions are compiled to WASM components and their interfaces generate API bindings rather than being wired together by hand. The project lives in the Rust, WASI, and WASM ecosystem, is licensed AGPL-3.0, and is developed under the obeli-sk organisation with documentation at obeli.sk.

The concrete problem it solves is orchestration that survives failure without bespoke glue code. Application code that needs retries, scheduled checks, compensating actions, or auditable multi-step jobs normally grows its own retry loops, cron wiring, and partial-failure handling. Obelisk instead guarantees runtime determinism, so workflows are fully replayable from the persistent execution log, and activities are retried automatically on errors, timeouts, and panics recorded as WASM traps, with inputs and results persisted. That combination yields reliable recovery, debugging, and auditing, which is what the replayable-workflow and time-travelling-debugger features exist to provide.

Key capabilities

A single runtime binary that executes deterministic workflows, activities, and webhook endpoints, persisting steps in an execution log backed by SQLite or PostgreSQL.
WASI activities with support for HTTP requests through the WASI 0.2 HTTP client, automatic retries on errors, timeouts, and WASM traps, and persistent execution results; activities must be idempotent, a contract the activity itself fulfils.
Deterministic workflows that are runtime-guaranteed deterministic, fully replayable from the persistent execution log, crash resilient, and retried automatically on timeouts.
Structured concurrency, letting workflows spawn child executions.
WASI webhook endpoints mounted as a URL path, serving HTTP traffic and spawning child executions in response.
A work stealing executor with concurrency limits and customizable retry handling.
Three control interfaces: the obelisk CLI, a gRPC API for programmatic interaction, and a Web UI for viewing and submitting function executions, execution logs, and WIT definitions, including a time-travelling debugger that shows backtraces and sources of recorded events.

Who uses it and how

Teams running event-driven integrations: the Stargazers demo app listens to GitHub star events through a webhook, runs activities against Turso DB, OpenAI, and GitHub, and orchestrates them with a workflow.
Deployment automation: the Obelisk fly.io deployment tool is a complete workflow for deploying Obelisk apps on fly.io, with cleanup and compensating actions on failure.
Operators scheduling periodic tasks and background jobs that need complex logic written as regular code with built-in error handling and retries.
Batch job owners managing large-scale work such as faas deployments.
Test and platform engineers automating end-to-end tests with detailed logs of each step, and teams sandboxing and auditing AI-assisted code.
Self-hosters on Linux x64 and arm64 (musl, glibc v2.35+, NixOS) or macOS x64 and arm64.

Getting started

Install a pre-built binary with the published download script (curl -L --tlsv1.2 -sSf https://raw.githubusercontent.com/obeli-sk/obelisk/main/download.sh | bash) or with cargo binstall obelisk. Alternatively run the getobelisk/obelisk Docker image, generating a config with obelisk generate config > config/obelisk.toml and starting it with server run --config /config/obelisk.toml, which binds ports 8080 for the web UI and 5005 for gRPC.

How it compares

The facts provided name no paid products that Obelisk replaces, and they name no comparable orchestration tools either, so there is no licence, self-hosting, data-ownership, or cost-model contrast to draw. Within this registry it stands alone as a deterministic WASM Component Model workflow engine.

When to use it — and when not to

A self-hoster must operate the runtime plus its dependencies: an execution log on SQLite or PostgreSQL, a WASM cache directory if caching is shared from the host, and the web and gRPC ports. The README carries an explicit pre-release warning that the CLI, gRPC interface, WIT definitions, and database schema should all be expected to change, so teams that require a frozen API or schema, or that do not want a WASM Component Model and WIT toolchain in their build, should not pick it up yet.

project readme (upstream, from github) — read inline

Obelisk

A deterministic workflow engine built on the WASM Component Model.

[!WARNING] Pre-release: Expect changes in CLI, gRPC, WIT, and database schema.

Obelisk in Action

The Stargazers app features:

A webhook listening to GitHub star events.
Activities for interacting with Turso DB, OpenAI, and GitHub.
A workflow orchestrating the activities.

Obelisk fly.io deployment tool features:

A complete workflow for deploying Obelisk apps on fly.io
Cleanup / compensating actions on failure

What's Included

Obelisk Runtime: A single binary executing deterministic workflows, activities, and webhook endpoints, persisting steps in execution log using SQLite or PostgreSQL.
Control Interfaces:
- CLI: Manage executions via the obelisk command.
- gRPC API: Programmatic interaction.
- Web UI: View and submit function executions, execution logs, WIT definitions, and a time-traveling debugger showing backtraces and sources of recorded events.

Core Principles

Replayable Workflows: Deterministic execution ensures reliable recovery, debugging, and auditing.
Resilient Activities: Automatic retries on errors and timeouts, with persistent input and results.
Schema-first design with end-to-end type safety: Uses WASM Component Model and WIT IDL for generating API bindings.

Use Cases

Sandboxing and auditing of AI-Assisted Code
Periodic Tasks: Automate periodic checks with complex logic using regular code.
Background Jobs: Offload tasks with built-in error handling and retries.
Batch jobs: Manage large-scale tasks like faas deployments.
End-to-End Testing: Automate tests with detailed logs of each step.

Key Features

WASI Activities

Activities must be idempotent (retriable). This contract must be fulfilled by the activity itself.
Support for HTTP requests via WASI 0.2 HTTP client.
Automatic retries on errors, timeouts, and panics (WASM traps).
Persistent execution results.

Deterministic Workflows

Runtime guaranteed determinism, fully replayable with persistent execution log and thus crash resilient.
Automatic retries on timeouts.
Support for spawning child executions with structured concurrency.

WASI Webhook Endpoints

Mounted as a URL path, serving HTTP traffic.
Support for spawning child executions.

Work Stealing Executor

Concurrency limits and customizable retry handling.

Installation

Supported Platforms

Linux x64, arm64 (musl, glibc v2.35+, NixOS)
MacOS x64, arm64

Pre-built Binary

curl -L --tlsv1.2 -sSf https://raw.githubusercontent.com/obeli-sk/obelisk/main/download.sh | bash

Or use cargo-binstall:

cargo binstall obelisk

Docker

# Use host's network. Ports 8080 (web) and 5005 (grpc) will be bound to 127.0.0.1
mkdir config
docker run getobelisk/obelisk generate config > config/obelisk.toml
docker run \
  --net=host
  -v $(pwd)/config:/config \
  getobelisk/obelisk \
  server run --config /config/obelisk.toml

# Forward ports explicitly
docker run \
  -p 8080:8080 -e 'OBELISK__webui__listening_addr=0.0.0.0:8080' \
  -p 5005:5005 -e 'OBELISK__api__listening_addr=0.0.0.0:5005' \
  -v $(pwd)/config:/config \
  getobelisk/obelisk \
  server run --config /config/obelisk.toml

# Share the cache directory from host
docker run --net=host \
  -u $(id -u):$(id -g) \
  -v $(pwd)/config:/config \
  -e 'OBELISK__WASM__CACHE_DIRECTORY=/cache/obelisk/wasm' \
  -v ~/.cache/obelisk/wasm:/cache/obelisk/wasm \
  getobelisk/obelisk \
  server run --config /config/obelisk.toml

From Source

Requires protoc.

cargo install --locked obelisk

Using Nix:

nix run github:obeli-sk/obelisk/latest

For more options see Installation.

Persisted value limit

The server defaults to a 1 MiB compact JSON-encoded limit for each newly persisted execution parameter array, result, stub result, persisted history value, or failure diagnostic. Self-hosted operators can set a positive value in server.toml:

[limits]
max_persisted_value_size_bytes = 1048576

Each top-level execution snapshots the effective limit. Child and scheduled executions inherit it, so a configuration change applies only to new execution trees and cannot change replay behavior. Existing databases require no schema migration: executions created by older releases retain their legacy unlimited contract. max_transport_message_size_bytes (also under [limits], defaulting to 512 MiB) is a separate, larger transport safeguard bounding a single gRPC message or REST request body, and does not relax the persisted-value limit.

Getting Started

Check out the Getting Started Guide for details.

Start the Server

obelisk server run --deployment deployment-testing-wasm-oci.toml

Linux VM activity MVP

See deployment-testing-vm.toml for the runnable example, setup commands, and architecture notes.

Running with Postgres

docker run -it --rm \
  --name obelisk-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:18

# export env vars if .envrc is not used
export POSTGRES_HOST="localhost"
export POSTGRES_USER="postgres"
export POSTGRES_PASSWORD="postgres"
export POSTGRES_DATABASE="obelisk"

obelisk server run --server-config server-postgres.toml --deployment deployment-testing-wasm-oci.toml

CLI Usage

obelisk component list
# Call fibonacci(10) activity from the workflow 500 times in series.
obelisk execution submit testing:fibo-workflow/workflow.fiboa '[10, 500]' --follow

Web UI

Visit localhost:8080 to manage components, functions and execution history.

Contributing

This project has a roadmap and features are added in a certain order. Discuss features via GitHub Discussions before contributing. A Contributor License Agreement is required.

Development

Set up dependencies via Nix:

cp .envrc-example .envrc
$EDITOR .envrc
direnv allow
# If direnv is not available use `nix develop`

Or manually install dependencies (see dev-deps.txt).

Run the program:

cargo run --release

See DEVELOPMENT.md for repository structure, build instructions, testing, code patterns, and contribution conventions.

Running Tests

Postgres must be running. See .envrc-example for how to set up the environment variables. Quick start:

cp .envrc-example .envrc && $EDITOR .envrc && direnv allow
cargo run --release
./scripts/test.sh

Project Licensing Information

This project (all files and folders except as noted below) is licensed under the GNU Affero General Public License version 3.

Subfolder Exceptions

The following subfolders are licensed under the MIT License:

wit/ – see LICENSE-MIT
proto/ – see LICENSE-MIT

Generated WIT Files

The runtime includes functionality that may generate new "extension" WIT files. These generated files are typically based on a combination of user-provided WIT files and the base WIT definitions found in the MIT-licensed wit/ directory.

Users are free to use, modify, and distribute these generated WIT files under the terms of the MIT License, for example, to allow other WASM components to interact via these extended interfaces.

Frequently asked questions

Is obelisk free to use?

obelisk is open source under the AGPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does obelisk do?

Durable & Deterministic Workflow Engine

What is obelisk written in?

obelisk is primarily written in Rust. Its source is publicly available at https://github.com/obeli-sk/obelisk, and it has 766 GitHub stars.