> ## Documentation Index
> Fetch the complete documentation index at: https://openworkflow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> openworkflow.config.ts reference

OpenWorkflow uses a configuration file to connect to your database, locate your
workflow files, and set worker options. The CLI reads this file automatically
for all commands.

If you ran `npx @openworkflow/cli init`, this file was created for you. This
page covers all available options.

If you're using the PostgreSQL backend, install the Postgres driver:

<CodeGroup>
  ```bash npm theme={null}
  npm i openworkflow postgres
  ```

  ```bash pnpm theme={null}
  pnpm add openworkflow postgres
  ```

  ```bash bun theme={null}
  bun add openworkflow postgres
  ```
</CodeGroup>

## Config File

Create `openworkflow.config.ts` (or `.js`) in your project root:

```ts theme={null}
import { defineConfig } from "@openworkflow/cli";
import { BackendPostgres } from "openworkflow/postgres";

export default defineConfig({
  backend: await BackendPostgres.connect(
    process.env.OPENWORKFLOW_POSTGRES_URL!,
  ),
  dirs: ["./openworkflow"],
});
```

The CLI automatically finds this file by searching up from the current
directory. If your config lives somewhere else, pass an explicit path:

```bash theme={null}
npx @openworkflow/cli worker start --config src/openworkflow.config.ts
```

## Verify Configuration

After creating or updating the config, run:

<CodeGroup>
  ```bash npm theme={null}
  npx @openworkflow/cli doctor
  ```

  ```bash pnpm theme={null}
  pnpx @openworkflow/cli doctor
  ```

  ```bash bun theme={null}
  bunx @openworkflow/cli doctor
  ```
</CodeGroup>

This confirms that your config can be loaded, the backend can be reached, and
your workflows can be found.

## Configuration Options

### `backend` (required)

The storage backend for workflow state. See [PostgreSQL](/docs/postgres) or
[SQLite](/docs/sqlite).

```ts theme={null}
import { BackendPostgres } from "openworkflow/postgres";
import { BackendSqlite } from "openworkflow/sqlite";

// PostgreSQL (production)
backend: await BackendPostgres.connect(process.env.OPENWORKFLOW_POSTGRES_URL!),

// SQLite (development)
backend: BackendSqlite.connect("./openworkflow/backend.db"),
```

### `dirs`

Directory or directories to scan for workflow files. Defaults to
`["./openworkflow"]`.

```ts theme={null}
// Single directory
dirs: "./openworkflow",

// Multiple directories
dirs: ["./openworkflow", "./src/workflows"],
```

The CLI recursively scans these directories for files with extensions: `.ts`,
`.mts`, `.cts`, `.js`, `.mjs`, `.cjs`.

### `ignorePatterns`

Glob patterns to exclude when discovering workflow files:

```ts theme={null}
ignorePatterns: [
  "**/*.test.*",      // Ignore test files
  "**/*.run.*",       // Ignore runner scripts
  "**/__fixtures__/**", // Ignore fixtures
],
```

The pattern `**/*.run.*` is ignored by default to exclude runner scripts.

### `worker`

Worker configuration options:

```ts theme={null}
worker: {
  // Number of concurrent workflow executions (default: 1)
  concurrency: 4,
},
```

## Full Example

```ts theme={null}
import { defineConfig } from "@openworkflow/cli";
import { BackendPostgres } from "openworkflow/postgres";

export default defineConfig({
  // PostgreSQL for production, with namespace
  backend: await BackendPostgres.connect(
    process.env.OPENWORKFLOW_POSTGRES_URL!,
    {
      namespaceId: process.env.OPENWORKFLOW_NAMESPACE_ID || "default",
    },
  ),

  // Scan multiple directories
  dirs: ["./openworkflow", "./src/workflows"],

  // Ignore test files
  ignorePatterns: ["**/*.test.*", "**/*.spec.*"],

  // Worker configuration
  worker: {
    concurrency: 8,
  },
});
```

## Environment-Based Configuration

Use environment variables for different environments:

```ts theme={null}
import { defineConfig } from "@openworkflow/cli";
import { BackendPostgres } from "openworkflow/postgres";
import { BackendSqlite } from "openworkflow/sqlite";

const isDev = process.env.NODE_ENV !== "production";

export default defineConfig({
  backend: isDev
    ? BackendSqlite.connect("./openworkflow/backend.db")
    : await BackendPostgres.connect(process.env.OPENWORKFLOW_POSTGRES_URL!),

  dirs: ["./openworkflow"],

  worker: {
    concurrency: isDev ? 1 : 8,
  },
});
```

## Loading Environment Variables

The CLI loads `.env` files automatically. Add your database URL and other
secrets there:

```bash theme={null}
# .env
OPENWORKFLOW_POSTGRES_URL=postgresql://user:pass@localhost:5432/openworkflow
OPENWORKFLOW_NAMESPACE_ID=development
```

## Supported Extensions

Config files can use these extensions:

* `openworkflow.config.ts`
* `openworkflow.config.mts`
* `openworkflow.config.cts`
* `openworkflow.config.js`
* `openworkflow.config.mjs`
* `openworkflow.config.cjs`