Configuration - obelisk.toml

Server Configuration

API Server

api.listening_addr = "127.0.0.1:5005"   # Address and port for API server

Web UI

webui.listening_addr = "127.0.0.1:8080" # Address and port for web UI

Warning: Listening on all interfaces ([::]:<port>) is not recommended as authentication is not yet implemented.

Sqlite

sqlite.directory = "${DATA_DIR}/obelisk-sqlite"  # SQLite database location
sqlite.pragma = { "cache_size" = "3000" }        # Customize PRAGMA statements

Component Configuration

WASM Cache dir

Path to directory where downloaded or transformed WASM files are stored. Supports path prefixes. By default "${CACHE_DIR}/wasm" or "./cache/wasm" if no valid home directory path could be retrieved from the operating system.

wasm.cache_directory = "${CACHE_DIR}/wasm"       # WASM file cache location

Code Generation Cache

[codegen_cache]
enabled = true
directory = "${CACHE_DIR}/codegen"   # Generated code cache location

Global WASM Component configuration

wasm.backtrace.persist = true        # Persist backtraces on effect calls for all workflows and webhook endpoints.

Allocation strategy for instance creation. Can be either pooling or on demand. Default value auto will attempt to use the pooling strategy with a fallback on error to on_demand.

wasm.allocator_config = "auto"       # One of ("auto"|"on_demand"|"pooling")

Global Preopened Directories Config

Preopended directory support for activities is disabled by default. It must be enabled both globally and for specifically for activity that uses disk IO.

[activities.directories]
# enabled = false                           # Disabled by default.
# parent_directory = "${TEMP_DIR}/obelisk"  # Make sure the folder is not on a RAM-backed filesystem if you plan to write large files.
# cleanup.enabled = true                    # Periodic cleanup job can be disabled, it is enabled by default.
# cleanup.run_every.minutes = 1             # Run the cleanup every minute by default.
# cleanup.older_than.minutes = 5            # Delete folders belonging to executions that finished 5 minutes earlier by default.

Common Component Settings

All WASM components (Activities, Workflows, Webhooks) share these configuration options:

name = "component_name"              # Required: Component identifier
location.path = "path/to/wasm"       # File path location (mutually exclusive with oci)
location.oci = "docker.io/repo/image:tag"  # OCI registry location
content_digest = "sha256:..."        # Optional: WASM file hash verification

Common Executor Settings

exec.batch_size = 5                  # Executions per event loop tick
exec.lock_expiry.seconds = 1         # Execution lock duration
exec.tick_sleep.milliseconds = 200   # Executor sleeps the specified duration when polling for pending executions
exec.max_inflight_instances = "unlimited"  # Concurrent instance limit

Activities

Configure each WASM activity component using the activity_wasm section:

[[activity_wasm]]
name = "..."
location.oci = "..."
# Common component and executor settings apply
max_retries = 5                      # Maximum retry attempts
retry_exp_backoff.milliseconds = 100 # Initial retry delay (doubles each attempt)
retry_on_err = true                  # Retry on Result::Err returns
forward_stdout = "stderr"            # stdout forwarding ("stdout"|"stderr"|"none")
forward_stderr = "stderr"            # stderr forwarding ("stdout"|"stderr"|"none")
env_vars = ["ENV1", "ENV2=value"]    # Environment variable configuration. Inherit from system if value is not provided.

Preopended directory suppport

Disk IO must be explicitly enabled. When enabled, a directory will be created on host and mapped to . on the guest activity with all permissions. On host the directory is created as activities.directories.parent_directory/ExecutionID and is truncated after the activity finishes.

directories  = { enabled = true, reuse_on_retry = false}

reuse_on_retry disabled by default: every execution attempt will start with an empty preopened directory.

If reuse_on_retry is enabled, a retried activity can reuse the same directory that was used by previous attempt. This can be helpful if an activity e.g. downloads a file and then processes it. Activity must in this case do all of its operations idempotently (e.g. mkdir -p) and verify the integrity of all files left by previous attempts.

Read more about Preopened directories.

Process Spawn API

In order to enable the obelisk:activity/process@1.0.0 API, preopened directory must be enabled and process_provider must be set to "native".

directories  = { enabled = true, reuse_on_retry = false, process_provider = "native"}

Read more about Process API.

Workflows

Configure each workflow component using the workflow section:

[[workflow]]
name = "..."
location.oci = "..."
# Common component and executor settings apply
retry_exp_backoff.milliseconds = 100  # Initial retry delay

# Blocking strategy:
blocking_strategy = "await"           # One of ("await"|"interrupt"|{"kind"=...})
# Default strategy is await.
# Customize the number of non-blocking events that can be cached and written in a batch.
# blocking_strategy = { kind = "await", non_blocking_event_batching = 100 }

retry_on_trap = false                 # Retry on traps (panics).
convert_core_module = true            # Auto-convert Core WASM modules to WASM Components
# Forward unhandled child errors to the parent workflow when closing completing join sets.
forward_unhandled_child_errors_in_completing_join_set_close = true
# Map from frame symbol file names to corresponding file paths on local filesystem.
# Both sides can use path prefixes.
backtrace.sources = {"backtracepath/src/lib.rs"="localpath/src/lib.rs"}

# Stub WASI CLI world imports. Only needed for workflows authored in TinyGo.
stub_wasi = false                     # Default is false.

The blocking strategy controlls whether an execution should await the child execution response or be interrupted and later replayed. Note that the await strategy will only wait until lock_expiry duration expires.

HTTP Servers and Webhooks

A Webhook Endpoint must be associated with a HTTP Server and must define one or more routes to listen on. Routes are divided into two categories: with HTTP methods (high priority) and without HTTP methods (low priority). When a request matches multiple routes of the same priority, the first webhook will receive it.

HTTP Servers

[[http_server]]
name = "server_name"                  # Server identifier
listening_addr = "0.0.0.0:9000"       # Listen address and port
max_inflight_requests = "unlimited"   # Concurrent request limit

Webhook Endpoints

[[webhook_endpoint]]
name = "..."
location.oci = "..."
# Common component settings apply
http_server = "server_name"          # Reference to HTTP server
routes = [                           # Route configurations
    { methods = ["GET"], route = "/path" },
    "/other/*",
    "/status/:param1/:param2"
]
forward_stdout = "stderr"            # stdout forwarding ("stdout"|"stderr"|"none")
forward_stderr = "stderr"            # stderr forwarding ("stdout"|"stderr"|"none")
env_vars = ["ENV1", "ENV2=value"]    # Environment variable configuration. Inherit from system if value is not provided.
# Map from frame symbol file names to corresponding file paths on local filesystem.
# Both sides can use path prefixes.
backtrace.sources = {"backtracepath/src/lib.rs"="localpath/src/lib.rs"}

Route Syntax

Routes: Define URL paths (only the path is matched):

Static paths

• "/" - Root path only
• "/path" - Exact path match

Wildcards

• "/path/*" - Path prefix match
• "{ methods = ["GET"], route = "/path" }" - Method-specific (priority) match

Parameterized

• "/status/:param1/:param2" - Path parameters (exposed as env vars)

All paths

• "" or "/*" - Match all paths

Observability

Levels and filtering is configured using EnvFilter syntax.

OTLP Tracing

[otlp]
enabled = true
level = "info,app=trace"   # See filtering syntax
service_name = "obelisk-server"
otlp_endpoint = "http://localhost:4317"

Logging

Stdout Logging

[log.stdout]
enabled = true
level = "info,app=trace"   # See filtering syntax
style = "plain_compact"    # One of "plain"|"plain_compact"|"json"
span = "none"              # One of "none"|"new"|"enter"|"exit"|"close"|"active"|"full"
target = false             # Whether to include the target module in message

File Logging

[log.file]
enabled = true
level = "info,obeli=debug,app=trace" # See filtering syntax
style = "json"             # One of "plain"|"plain_compact"|"json"
span = "close"             # One of "none"|"new"|"enter"|"exit"|"close"|"active"|"full"
target = true              # Whether to include the target module in message
rotation = "daily"         # One of "minutely"|"hourly"|"daily"|"never"
directory = "."
prefix = "obelisk_server_daily" # File name prefix

Appendix: Path Prefixes

The following path prefixes are supported throughout the configuration: