# Obelisk Obelisk is a deterministic durable execution engine. Write new apps in JavaScript on the native V8 runtime by default. Use Rust components in Wasmtime when performance or an existing Rust library matters. ## Default authoring path - Start every new app with `obelisk generate new NAME` (or `obelisk generate new` inside an empty directory). It writes a runnable `app.toml`, `deployment.toml`, JavaScript webhook, workflow, and HTTP activity, and a `README.md`. Adapt the generated files instead of writing the configuration from scratch. - To add a single configuration file to an existing project, generate its commented reference instead: `obelisk generate app-config app.toml`, `obelisk generate deployment deployment.toml`, or `obelisk generate server-config server.toml` (optional; only needed to change platform defaults such as ports or limits). Every setting in these references is commented out; at minimum uncomment and set `app_name` in `app.toml`. - JavaScript components are plain `.js` files with WIT-defined signatures. - Activities are short-lived idempotent units of side-effecting work and can be retried automatically. Activities should spawn containers or VMs for CPU-intensive or long running workloads. - Workflows are deterministic and replayable. They orchestrate child executions - workflows and activities, and durable timers. - Webhook endpoints are HTTP handlers that can spawn executions. - Deployments are versioned. Workflows can be paused between runs, replayed, advanced step by step, or automatically replayed and upgraded when code changes between deployments. - Cancellation is part of structured concurrency. Activities and delays are cancellable; workflows are cancellable only when their exported function name ends in `-cancellable`. A cancelled workflow is not advanced again, so an ancestor must own cleanup. - All functions are identified by an FFQN (`namespace:package/interface.function`) and typed with WIT. - JS components declare their types inline in `deployment.toml` — no WIT files needed, or use `wit = "path/to/wit" to share types with other components. - Every function must return a fallible type: `result`, `result`, `result`, or `result` where `E` is a variant containing `execution-failed`. See the Activities and Workflows concept pages for details. - Configuration is split into `server.toml` (platform limits and listeners, optional), `app.toml` (app name, secrets, public environment, outbound HTTP, and exec approvals), and `deployment.toml` (components). - Name each app in `app.toml` with `app_name`; `obelisk generate new` creates it. When running without an app policy file, set `OBELISK_APP_NAME`. - Outbound HTTP needs a component `allowed_host` entry in `deployment.toml` and a matching `[[outbound_http.allowed_host]]` entry in `app.toml`. Deployment environment variables must be declared in the app's `[public_env]`; credentials go in the app's `[secrets]`. - Use `obelisk deployment verify --app-config app.toml --deployment deployment.toml --fix` to repair deployment digests and scaffold missing app configuration, then run `obelisk server run --app-config app.toml --deployment deployment.toml`. - Read the Example Applications page before building an app. Start an agent from `agent-template`; study `demo-playwright` for durable browser work and `demo-tutorial` for basic workflow patterns. Copy the relevant source and permissions into the new app. ## Common design patterns - [Cleanup supervisor / saga](https://obeli.sk/docs/v0.42.0/patterns/cleanup-supervisor/) - [Parallel fan-out and durable polling](https://obeli.sk/docs/v0.42.0/js/js-patterns/) - [Human-in-the-loop signals with stub activities](https://obeli.sk/docs/v0.42.0/concepts/activities/stub/) ## Docs - [Programmatic access](https://obeli.sk/docs/v0.42.0/programmatic-access/) - [Example Applications](https://obeli.sk/docs/v0.42.0/apps/) - [Security Model](https://obeli.sk/docs/v0.42.0/security/) - [Configuration](https://obeli.sk/docs/v0.42.0/configuration/) - [Authentication](https://obeli.sk/docs/v0.42.0/authentication/) - [Command Line Interface](https://obeli.sk/docs/v0.42.0/cli/) - [Migrating from 0.40 to 0.41](https://obeli.sk/docs/v0.42.0/migrating-to-0.41/) - [Migrating from 0.41 to 0.42](https://obeli.sk/docs/v0.42.0/migrating-to-0.42/) - [Concepts](https://obeli.sk/docs/v0.42.0/concepts/) - [Concepts / Deployments](https://obeli.sk/docs/v0.42.0/concepts/deployments/) - [Concepts / Execution States](https://obeli.sk/docs/v0.42.0/concepts/execution-states/) - [Concepts / Execution Log](https://obeli.sk/docs/v0.42.0/concepts/execution-log/) - [Concepts / Structured Concurrency](https://obeli.sk/docs/v0.42.0/concepts/structured-concurrency/) - [Concepts / Function Fully Qualified Name (FFQN)](https://obeli.sk/docs/v0.42.0/concepts/ffqn/) - [Concepts / Identifiers](https://obeli.sk/docs/v0.42.0/concepts/identifiers/) - [Concepts / Runtime Suppport](https://obeli.sk/docs/v0.42.0/concepts/runtime-support/) - [Concepts / Webhook Endpoints](https://obeli.sk/docs/v0.42.0/concepts/webhook-endpoints/) - [Concepts / WIT Reference](https://obeli.sk/docs/v0.42.0/concepts/wit-reference/) - [Concepts / Logging](https://obeli.sk/docs/v0.42.0/concepts/logging/) - [Concepts / Extensions](https://obeli.sk/docs/v0.42.0/concepts/extensions/) - [Concepts / Cron (Periodic Tasks)](https://obeli.sk/docs/v0.42.0/concepts/cron/) - [JavaScript](https://obeli.sk/docs/v0.42.0/js/) - [JavaScript / Getting Started with Obelisk](https://obeli.sk/docs/v0.42.0/js/getting-started/) - [JavaScript / Getting Started: Saga Pattern with Fly.io](https://obeli.sk/docs/v0.42.0/js/getting-started-fly-agent/) - [JavaScript / JS Components](https://obeli.sk/docs/v0.42.0/js/js-components/) - [JavaScript / JS Activities](https://obeli.sk/docs/v0.42.0/js/js-activities/) - [JavaScript / JS Workflows](https://obeli.sk/docs/v0.42.0/js/js-workflows/) - [JavaScript / JS Webhooks](https://obeli.sk/docs/v0.42.0/js/js-webhooks/) - [JavaScript / JS Patterns & Examples](https://obeli.sk/docs/v0.42.0/js/js-patterns/) - [Common Design Patterns](https://obeli.sk/docs/v0.42.0/patterns/) - [Common Design Patterns / Cleanup Supervisor (Saga)](https://obeli.sk/docs/v0.42.0/patterns/cleanup-supervisor/) - [Common Design Patterns / Generation Reconciler for Long-Running Workflows](https://obeli.sk/docs/v0.42.0/patterns/generation-reconciler/) - [Common Design Patterns / Stub RPC (Typed Oneshot Channels)](https://obeli.sk/docs/v0.42.0/patterns/stub-rpc/) - [Common Design Patterns / Publishing Workflow Events with Self-Fulfilled Stubs](https://obeli.sk/docs/v0.42.0/patterns/self-fulfilled-stub-events/) - [Common Design Patterns / Durable Mailbox and Notification Channel](https://obeli.sk/docs/v0.42.0/patterns/stub-mailbox/) - [WASM (Rust)](https://obeli.sk/docs/v0.42.0/wasm/) - [WASM (Rust) / Getting Started with Obelisk (Rust / WASM)](https://obeli.sk/docs/v0.42.0/wasm/getting-started/) - [WASM (Rust) / Rust Components](https://obeli.sk/docs/v0.42.0/wasm/rust-components/) - [WASM (Rust) / HTTP Client (Rust)](https://obeli.sk/docs/v0.42.0/wasm/http-client/)