Temporal Configuration

Temporal configuration is split into mode selection and standalone overrides. Remote mode connects to an external cluster; standalone mode boots temporal.NewServer() inside the process for local development and CI.

Configuration Structure

compozy.yaml

temporal:
  mode: remote | standalone
  host_port: localhost:7233
  namespace: default
  task_queue: compozy-tasks
  standalone:
    database_file: :memory:
    frontend_port: 7233
    bind_ip: 127.0.0.1
    namespace: default
    cluster_name: compozy-standalone
    enable_ui: true
    ui_port: 8233
    log_level: warn
    start_timeout: 30s

Mode Selection

Field	Description	Default
`mode`	`remote` (default) uses an external Temporal cluster. `standalone` starts the embedded Temporal server.	`remote`
`host_port`	Temporal endpoint in `host:port` format. Overridden automatically when `mode=standalone`.	`localhost:7233`
`namespace`	Default Temporal namespace for workflows. Create unique namespaces per environment.	`default`
`task_queue`	Primary task queue that Compozy workers poll.	`compozy-tasks`

When mode=standalone, host_port is rewritten to bind_ip:frontend_port. Update downstream services (like external workers) to use the new address if you expose it beyond localhost.

Standalone Options

Field	Description	Default
`database_file`	SQLite path. Use `:memory:` for ephemeral instances or a file path for persistence.	`:memory:`
`frontend_port`	Anchors the port block used by Temporal services (frontend + history + matching + worker).	`7233`
`bind_ip`	Interface to bind Temporal services. Keep `127.0.0.1` for safe development defaults.	`127.0.0.1`
`namespace`	Namespace created automatically when the embedded server starts.	`default`
`cluster_name`	Cluster identifier for the embedded server. Useful when inspecting metrics or logs.	`compozy-standalone`
`enable_ui`	Toggle the Temporal Web UI bundled with standalone mode.	`true`
`ui_port`	HTTP port for the Temporal Web UI.	`8233`
`log_level`	Temporal server log level (`debug`, `info`, `warn`, `error`).	`warn`
`start_timeout`	Maximum time to wait for Temporal startup before failing (`time.Duration` format).	`30s`

Environment Variables & CLI Flags

Config Path	Environment Variable	CLI Flag
`temporal.mode`	`TEMPORAL_MODE`	`--temporal-mode`
`temporal.host_port`	`TEMPORAL_HOST_PORT`	`--temporal-host`
`temporal.namespace`	`TEMPORAL_NAMESPACE`	`--temporal-namespace`
`temporal.task_queue`	`TEMPORAL_TASK_QUEUE`	`--temporal-task-queue`
`temporal.standalone.database_file`	`TEMPORAL_STANDALONE_DATABASE_FILE`	`--temporal-standalone-database`
`temporal.standalone.frontend_port`	`TEMPORAL_STANDALONE_FRONTEND_PORT`	`--temporal-standalone-frontend-port`
`temporal.standalone.bind_ip`	`TEMPORAL_STANDALONE_BIND_IP`	-
`temporal.standalone.namespace`	`TEMPORAL_STANDALONE_NAMESPACE`	-
`temporal.standalone.cluster_name`	`TEMPORAL_STANDALONE_CLUSTER_NAME`	-
`temporal.standalone.enable_ui`	`TEMPORAL_STANDALONE_ENABLE_UI`	-
`temporal.standalone.ui_port`	`TEMPORAL_STANDALONE_UI_PORT`	`--temporal-standalone-ui-port`
`temporal.standalone.log_level`	`TEMPORAL_STANDALONE_LOG_LEVEL`	-
`temporal.standalone.start_timeout`	`TEMPORAL_STANDALONE_START_TIMEOUT`	-

Validation Rules

Mode enum
Only remote and standalone are accepted values for temporal.mode.
Port ranges
frontend_port and ui_port must be between 1 and 65535. frontend_port reserves a block of four contiguous ports.
IP address validation
bind_ip must be a valid IP string. IPv4 loopback is recommended for development.
Log level enum
log_level accepts debug, info, warn, or error.
Start timeout
start_timeout must be positive. Increase it if your machine boots Temporal slower than 30 seconds.

Usage Patterns

Remote mode deployment

export TEMPORAL_MODE=remote
export TEMPORAL_HOST_PORT=temporal.prod.internal:7233
compozy start --temporal-namespace=compozy-prod

Temporal Modes

Compare remote and standalone deployments

Embedded Temporal

Understand how the embedded server is composed

Temporal Troubleshooting

Fix port conflicts, SQLite issues, and UI errors

compozy start CLI

Flags and examples for runtime configuration