Skip to main content
The Compose App manifest is a YAML file that defines your app’s configuration. This is where you configure a list of tasks and other app-level concerns. Each task can be individually configured for things like retry behavior and HTTP trigger behavior, cron schedules and more.

​
App properties

PropertyTypeRequiredDescription
namestringYesUnique app identifier used for API calls
api_versionstringYesPins your app to a Compose runtime version. Use "stable" if unsure — see Release channels below.
secretsarray(string)NoNames of secrets you’ve set for this app
envENVNoEnvironment-specific variables
tasksTasks[]YesList of tasks in your app

​
Release channels

api_version pins your app to a Compose runtime version. You can use one of two release channels, or pin to a specific version:
  • "stable" — the current stable runtime. This is the recommended value for production apps.
  • "preview" — the latest pre-release runtime. Use this if you want early access to features that haven’t made it into stable yet. Expect more frequent changes.
  • A specific version (e.g. "0.3.0") — pin to an exact runtime version. Useful when you want full control over when your app picks up runtime changes. See the changelog for available versions.
If your manifest’s api_version is older than the CLI, compose deploy will warn you and prompt before continuing. Pass -f to skip the prompt.

​
Basic example

name: "my_app"
api_version: "stable"
secrets:
  - MY_SECRET 
env:
  local:
    MY_VAR: "foo"
  cloud:
    MY_VAR: "bar"
tasks:
  - name: "price_fetcher"
    path: "./tasks/fetch_price.ts"
    triggers:
      - type: "cron"
        expression: "* * * * *" # Run every minute
      - type: "http"
        authentication: "auth_token"
    retry_config:
      max_attempts: 3
      initial_interval_ms: 1000
      backoff_factor: 2
  - name: "data_processor"
    path: "./tasks/process_data.ts"

​
ENV variables

You can set env variables in your manifest which will be injected in your app under the env context property. Env configuration is namespaced by environment and the values of the current environment your running in will be injected. Currently the two environments “local” for when you’re running your compose app locally and “cloud” for when you’ve deployed your app with goldsky compose deploy, read more about deploying here.

​
Example

name: "my_app"
env:
  local:
    MY_VAR: "foo"
    ANOTHER_VAR: "bar"
  cloud:
    MY_VAR: "foo-prod"
    ANOTHER_VAR: "bar-prod"

​
Task configuration

Compose apps are made up of tasks, each task in the tasks array defines an executable unit of work and references a typescript file, see Task Authoring for more details. Tasks can be triggered by HTTP requests from your app, blockchain events, cron schedules, etc. See more about triggers below. Tasks can also trigger other tasks via the callTask context function within the task code. 
name: "my_app"
tasks:
  - name: "unique_task_name" # Required: Unique identifier
    path: "./tasks/my_task.ts" # Required: Path to task file
    triggers: 
      - type: "http"
        authentication: "auth_token"
      - type: "cron" 
        expression: "*/5 * * * *" # Every 5 minutes
    retry_config: # Optional: Task-level retry settings
      max_attempts: 5
      initial_interval_ms: 2000
      backoff_factor: 1.5

​
Name validation

App names must start with a lowercase letter, end with a letter or digit, and contain only lowercase letters, digits, and hyphens (e.g. my-app-1). Task names must start with a letter (or underscore followed by a letter/digit) and contain only letters, digits, and underscores (e.g. fetch_prices, _internal_task).

​
Task properties

PropertyTypeRequiredDescription
namestringYesUnique task identifier used for API calls
pathstringYesFile path to the task module
triggersarray(object)NoList of triggers that will run the task. Each trigger type can only appear once per task.
retry_configobjectNoTask-level retry behavior

​
Triggers

Triggers are what runs your Compose tasks, these can be HTTP calls, onchain events, or cron jobs. For more information, see Triggers.

​
Example

triggers:
  - type: "cron"
    expression: "* * * * *" # Run every minute (standard cron expression)
  - type: "http"
    authentication: "auth_token"
If you provide no triggers in your manifest then tasks can only be executed by other tasks.

​
Retry configuration

retry_config:
  max_attempts: 3 # Maximum number of retry attempts
  initial_interval_ms: 1000 # Initial delay before first retry
  backoff_factor: 2 # Exponential backoff multiplier
When specifying retry_config, all three fields (max_attempts, initial_interval_ms, backoff_factor) are required. You cannot provide only some of them.
How retries work:
  • If a task fails, Compose waits initial_interval_ms before retrying
  • Each subsequent retry interval is multiplied by backoff_factor
  • Example with above config: 1000ms → 2000ms → 4000ms
  • After max_attempts failures, the task is marked as permanently failed
  • The default retry behaviour is 0 retries (1 attempt, no retries)

​
Manifest examples

​
Multi-chain oracle

name: "Multi-Chain Oracle"
tasks:
  - name: "fetch_prices"
    path: "./tasks/fetch_crypto_prices.ts"
    retry_config:
      max_attempts: 5
      initial_interval_ms: 2000
      backoff_factor: 1.5

  - name: "update_ethereum_oracle"
    path: "./tasks/update_oracle.ts"
    triggers:
      - type: "cron"
        expression: "* * * * *" # Every minute
    retry_config:
      max_attempts: 3
      initial_interval_ms: 5000
      backoff_factor: 2

  - name: "update_polygon_oracle"
    path: "./tasks/update_oracle.ts"
    triggers:
      - type: "cron"
        expression: "* * * * *" # Every minute

​
Event processing pipeline

name: "Event Processor"
tasks:
  - name: "event_processing"
    path: "./tasks/process_events.ts"
    triggers:
      - type: "onchain_event"
        network: "base"
        contract: "0xb74de3F91e04d0920ff26Ac28956272E8d67404D"
        events:
          - "Transfer(address,address,uint256)"
    retry_config:
      max_attempts: 10
      initial_interval_ms: 1000
      backoff_factor: 1.2