App Configuration

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

Property	Type	Required	Description
`name`	string	Yes	Unique app identifier used for API calls. Must start and end with a letter or number, and contain only letters, numbers, underscores, and hyphens.
`api_version`	string	For deploy	Pins your app to a Compose runtime version. Required by `goldsky compose deploy`; optional for local dev. Use `"stable"` if unsure — see Release channels below.
`secrets`	array(string)	No	Names of secrets you’ve set for this app (see Secrets)
`env`	ENV	No	Environment-specific variables
`tasks`	Tasks[]	Yes	List of tasks in your app (must contain at least one task)

Release channels

api_version pins your app to a Compose runtime version. You can use one of the 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 semver 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. Do not include a v prefix. See the changelog for available versions.

If your manifest’s api_version is older than the CLI, goldsky 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 are injected into your task’s env context property. Env configuration is namespaced by environment, and only the values for the current environment are injected. Currently there are two environments: local, used when running your compose app locally, and cloud, used when your app is running after goldsky compose deploy — see the deploy guide for more. Values must be strings. For anything sensitive (API keys, private keys), use secrets instead.

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"
api_version: "stable"
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 and end with a letter or number, and contain only letters, numbers, underscores, and hyphens (e.g. my-app-1). The pattern is /^[a-zA-Z0-9]([a-zA-Z0-9_\-]*[a-zA-Z0-9])?$/. Task names must start with a letter or number, and contain only letters, numbers, underscores, hyphens, and dots (e.g. fetch_prices, oracle.update). The pattern is /^[a-zA-Z0-9][a-zA-Z0-9_.\-]*$/. A leading underscore is no longer allowed. Names that canonicalize the same (lowercased, with runs of -/_ collapsed to -) cannot coexist in a project. my-app, My_App, and my__app are treated as the same name, so the second deploy gets a conflict error.

Task properties

Property	Type	Required	Description
`name`	string	Yes	Unique task identifier used for API calls
`path`	string	Yes	File path to the task module
`triggers`	array(object)	No	List of triggers that will run the task. Each trigger type can only appear once per task.
`retry_config`	object	No	Task-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
When retry_config is omitted, tasks default to max_attempts: 3, initial_interval_ms: 1000, and backoff_factor: 2.

Manifest examples

Multi-chain oracle

name: "multi-chain-oracle"
api_version: "stable"
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"
api_version: "stable"
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

Compose

Guides

Reference

App properties

Release channels

Basic example

ENV variables

Example

Task configuration

Name validation

Task properties

Triggers

Example

Retry configuration

Manifest examples

Multi-chain oracle

Event processing pipeline

​App properties

​Release channels

​Basic example

​ENV variables

​Example

​Task configuration

​Name validation

​Task properties

​Triggers

​Example

​Retry configuration

​Manifest examples

​Multi-chain oracle

​Event processing pipeline

App properties

Release channels

Basic example

ENV variables

Example

Task configuration

Name validation

Task properties

Triggers

Example

Retry configuration

Manifest examples

Multi-chain oracle

Event processing pipeline