# Obelisk Obelisk is a deterministic durable execution engine. Write new apps in JavaScript by default; they run on the JS runtime selected by the server (see "JavaScript / JS Runtime" under Docs). 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 by owner: `server.toml` (platform admin: limits and listeners, optional), `app.toml` (app admin: app name, secrets, public environment, outbound HTTP, and exec approvals), and `deployment.toml` (components). Agents edit component code and `deployment.toml` freely; a deployment can only use what `app.toml` and `server.toml` grant. Any change to `app.toml` or `server.toml` widens what the app can do, so point it out to a human for review instead of treating it as routine. - 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 `demo-agent`; 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 - [Example Applications](https://obeli.sk/docs/v0.42.0/apps/) - [Security Model](https://obeli.sk/docs/v0.42.0/security/) - [Migrating from 0.41 to 0.42](https://obeli.sk/docs/v0.42.0/migrating-to-0.42/) - [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/) - [JavaScript / JS Runtime](https://obeli.sk/docs/v0.42.0/js/js-runtime/) - [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 / Webhook Endpoints](https://obeli.sk/docs/v0.42.0/concepts/webhook-endpoints/) - [Concepts / WIT Basics](https://obeli.sk/docs/v0.42.0/concepts/wit-reference/) - [Concepts / Logging](https://obeli.sk/docs/v0.42.0/concepts/logging/) - [Concepts / Cron (Periodic Tasks)](https://obeli.sk/docs/v0.42.0/concepts/cron/) - [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) / Rust Activities](https://obeli.sk/docs/v0.42.0/wasm/activities/) - [WASM (Rust) / HTTP Client (Rust)](https://obeli.sk/docs/v0.42.0/wasm/http-client/) - [WASM (Rust) / Rust Workflows](https://obeli.sk/docs/v0.42.0/wasm/workflows/) - [WASM (Rust) / Extension Interfaces](https://obeli.sk/docs/v0.42.0/wasm/extensions/) - [WASM (Rust) / Runtime Support Interfaces](https://obeli.sk/docs/v0.42.0/wasm/runtime-support/) - [WASM (Rust) / Publishing Components](https://obeli.sk/docs/v0.42.0/wasm/publishing/) - [Configuration](https://obeli.sk/docs/v0.42.0/configuration/) - [Configuration / Server Configuration](https://obeli.sk/docs/v0.42.0/configuration/server/) - [Configuration / App Configuration](https://obeli.sk/docs/v0.42.0/configuration/app/) - [Configuration / Deployment Configuration](https://obeli.sk/docs/v0.42.0/configuration/deployment/) - [Access](https://obeli.sk/docs/v0.42.0/access/) - [Access / Command Line Interface](https://obeli.sk/docs/v0.42.0/access/cli/) - [Access / API Access](https://obeli.sk/docs/v0.42.0/access/api/) - [Access / Authentication](https://obeli.sk/docs/v0.42.0/access/authentication/)