compozy start

The compozy start command boots the Compozy production server. With Temporal standalone mode it can also launch the embedded Temporal server, making end-to-end execution possible without external infrastructure.

Use --temporal-mode=standalone for development and CI only. Keep production deployments pinned to --temporal-mode=remote and an external Temporal cluster.

Usage

compozy start [flags]

Temporal Flags

Flag	Description	Default
`--temporal-mode`	Selects Temporal connectivity (`remote` or `standalone`).	`remote`
`--temporal-host`	Overrides the Temporal gRPC endpoint when running in remote mode.	`localhost:7233`
`--temporal-namespace`	Specifies the Temporal namespace to target.	`default`
`--temporal-task-queue`	Sets the worker task queue name.	`compozy-tasks`
`--temporal-standalone-database`	SQLite path for embedded Temporal (`:memory:` or file path).	`:memory:`
`--temporal-standalone-frontend-port`	Anchors the service port block (services listen on `port`-`port+3`).	`7233`
`--temporal-standalone-ui-port`	HTTP port for the Temporal Web UI when enabled.	`8233`

Additional standalone fields (bind_ip, namespace, cluster_name, enable_ui, log_level, start_timeout) are configured via compozy.yaml or environment variables.

Database Flags

Flag	Description	Default
`--db-driver`	Selects the database backend (`postgres` or `sqlite`).	`postgres`
`--db-path`	SQLite database path or `:memory:`. Required when `--db-driver=sqlite`.	None
`--db-conn-string`	PostgreSQL connection string (`postgres://user:pass@host:port/db`). Overrides individual host/port flags.	None

SQLite file-backed

compozy start --db-driver=sqlite --db-path=./data/compozy.db

:memory: mode

compozy start --db-driver=sqlite --db-path=:memory:

When --db-driver=sqlite, configure an external vector database (Qdrant, Redis, or filesystem) because SQLite cannot host embeddings.

Examples

Production

compozy start \
  --temporal-mode=remote \
  --temporal-host=temporal.internal:7233 \
  --temporal-namespace=compozy-prod

During development you can keep temporal.mode=standalone in compozy.yaml and omit the flag entirely; the CLI flag still wins if you need to override temporarily.

Flag Precedence

CLI
Highest priority. Use flags for ad-hoc overrides or CI pipelines.
Config file
Values defined in compozy.yaml apply when flags are not supplied.
Environment
TEMPORAL_MODE, TEMPORAL_HOST_PORT, and friends populate defaults when neither flags nor config values are provided.
Defaults
Registry defaults supply sensible values for local development (remote mode + localhost ports).

Operational Notes

Port availability checks ensure standalone mode fails fast if 7233-7236 or 8233 are busy.
start_timeout controls how long the CLI waits for the embedded server to go healthy.
Logs flow through logger.FromContext(ctx); increase verbosity with --log-level debug alongside --temporal-standalone-log-level=debug in configuration.

Temporal Modes

Compare remote and standalone deployments

Temporal Configuration

Complete reference for the `temporal` configuration block

Temporal Troubleshooting

Resolve common issues when starting the server