Configuration

Runlane configuration is code. There is no project-wide YAML file and no hidden task discovery step. Your application creates a runtime with createRunlane(), wires a lane, registers queues and tasks, and exports that same runtime to processes that need to trigger, execute, maintain, or inspect runs.

Use this page to choose the right surface before changing config.

Runtime Construction

createRunlane() is the main application configuration boundary. It requires a lane and an explicit queue registry:

import { createRunlane, queue } from '@runlane/core'
import { createLocalLane } from '@runlane/lane-local'

import { sendEmail } from './tasks/send-email.js'

const emailQueue = queue({ name: 'emails', default: true })

export function createAppRunlane() {
  return createRunlane({
    environment: { name: 'development' },
    lane: createLocalLane(),
    queues: [emailQueue],
    tasks: { sendEmail },
  })
}

Runtime options are validated when the runtime is created. Unsupported options fail with ErrorCode.ConfigurationInvalid.

Queue declarations belong in shared application code, not in the CLI config file. The same queue objects should be passed to createRunlane({ queues }), task definitions, and provider bindings such as sqsQueue(queue, options).

See Quick Start for the runtime lifecycle and Queues for queue policies.

Lane And Adapter Options

A lane is the storage plus delivery mode the runtime uses. Local development normally uses createLocalLane() from @runlane/lane-local; it accepts only an optional diagnostic name and keeps state in the current process.

Production code usually has more adapter configuration. Use Postgres polling when workers should poll Postgres directly:

import { postgresPollingLane } from '@runlane/lane-postgres-polling'

const lane = postgresPollingLane({
  connectionString: process.env.DATABASE_URL,
  schema: 'runlane',
})

Use Postgres/SQS when a provider should deliver wakeups:

import { SQSClient } from '@aws-sdk/client-sqs'
import { postgresSqsLane } from '@runlane/lane-postgres-sqs'
import { sqsQueue } from '@runlane/transport-sqs'

const lane = postgresSqsLane({
  postgres: {
    connectionString: process.env.DATABASE_URL,
    schema: 'runlane',
  },
  sqs: {
    client: new SQSClient({ region: process.env.AWS_REGION }),
    queues: [
      sqsQueue(emailQueue, {
        queueUrl: process.env.RUNLANE_EMAILS_QUEUE_URL,
      }),
    ],
  },
})

postgresSqsLane() validates its top-level shape, then delegates nested validation to the adapter packages:

Run Postgres migrations before starting a Postgres-backed lane. lane.start() probes the migrated tables and fails when the database, schema, or migration is not ready.

See Postgres Polling Lane, Postgres SQS Lane, Postgres Storage, and SQS Transport for adapter contracts and deployment notes.

CLI Config

The packaged runlane binary loads a config module from the current working directory. The default search order is:

1. runlane.config.ts
2. runlane.config.mts
3. runlane.config.mjs
4. runlane.config.js
5. runlane.config.cjs

Pass --config <path> before the command when the module lives somewhere else.

The config module exports a RunlaneCliConfig object with a runtime value or factory:

import { type RunlaneCliConfig } from '@runlane/cli'

import { createAppRunlane } from './runtime/runlane.ts'

export default {
  runtime: createAppRunlane,
} satisfies RunlaneCliConfig

Keep this file thin. It should import the application-owned runtime factory rather than rebuilding tasks, queues, lanes, or environment defaults in a second place.

runlane init config --runtime ./runtime/runlane.ts writes this adapter for you. It does not start a runtime or generate lane configuration.

See Runlane CLI for command behavior, --json, runlane dev, worker options, and operator commands.

Environment Values

Runlane does not prescribe an environment variable format. Keep secrets and deployment-specific values in your app's normal configuration system, then pass typed values into the runtime and lane factory.

Common values include:

Do not split one logical runtime across mismatched environment names, queue definitions, or SQS bindings. createRunlane() and the transport adapters validate many of these mismatches at startup, but shared constants make them easier to avoid.