Mode Configuration

Compozy supports two operational modes: standalone and distributed (aka remote). You select a global default and optionally override per component.

Overview

Global mode
Set mode: standalone|distributed at the root to establish a default for all components.
Per‑component override
Each component (e.g., temporal, redis) can specify its own mode to override the global setting.
Resolution order
Component mode (if set) → global mode (if set) → component default (usually distributed).

Configuration Structure

compozy.yaml

# Global default
mode: standalone | distributed

temporal:
  mode: standalone | remote   # "remote" is the distributed mode for Temporal
  # ...other temporal fields

redis:
  mode: standalone | distributed
  # ...per-mode fields

Temporal uses remote to denote the distributed mode, matching Temporal terminology. For Redis and other components, distributed is used. Both follow the same inheritance rules.

Examples

Pure Standalone

mode: standalone

temporal:
  mode: standalone
  standalone:
    database_file: :memory:

redis:
  mode: standalone
  standalone:
    persistence:
      enabled: false

Pure Distributed

mode: distributed

temporal:
  mode: remote
  host_port: temporal.prod.internal:7233
  namespace: compozy-prod

redis:
  mode: distributed
  distributed:
    addr: redis.prod.internal:6379
    password: ${REDIS_PASSWORD}
    tls:
      enabled: true

Mixed Mode (Local Dev)

mode: standalone

temporal:
  mode: standalone
  standalone:
    database_file: ./.tmp/temporal.db

redis:
  mode: distributed           # use real Redis while keeping Temporal embedded
  distributed:
    addr: localhost:6379
    password: ""

Environment & CLI Overrides

Use environment variables or flags to switch quickly:

Path	Env	Flag
`mode`	`COMPOZY_MODE`	`--mode`
`temporal.mode`	`TEMPORAL_MODE`	`--temporal-mode`
`redis.mode`	`REDIS_MODE`	`--redis-mode`

YAML values take precedence over flags. Use flags for local overrides only.

Validation

Unknown modes are rejected with a clear error (valid: standalone, distributed, remote where applicable)
Fields must be valid for the selected mode (e.g., redis.distributed.addr required when redis.mode=distributed)
Mode conflicts surface actionable diagnostics in compozy config commands