Temporal Modes
Choose between remote and standalone Temporal deployments for Compozy.
Mode Comparison
| Capability | Remote Mode | Standalone Mode |
|---|---|---|
| Target environment | Production, staging, shared QA | Local development, ephemeral CI jobs, automated tests |
| Runtime | External Temporal cluster (Temporal Cloud or self-managed) | Embedded temporal.NewServer() running in-process |
| Persistence | Managed persistence (Cassandra, MySQL, PostgreSQL) | SQLite (:memory: or file on disk) |
| High availability | Multi-node, supports failover and replication | Single-node; no HA guarantees |
| Web UI | Optional, usually deployed separately | Bundled UI on port 8233 when enable_ui: true |
| Default ports | Depends on cluster setup (usually 7233) | Frontend 7233, History 7234, Matching 7235, Worker 7236, UI 8233 |
| Startup latency | Depends on remote connectivity | < 10s typical; configurable via start_timeout |
Architecture Overview
Remote Mode (Production)
Use remote mode whenever you need durability, multi-node availability, or shared infrastructure.
temporal:
mode: remote
host_port: temporal.my-company.internal:7233
namespace: compozy-prod
task_queue: compozy-taskscompozy start --temporal-mode=remote --temporal-host=temporal.my-company.internal:7233- Provision namespaces per environment and align retention policies with compliance needs.
- Enable mTLS or mutual auth on the Temporal gateway.
- Monitor latency, workflow backlog, and activity heartbeats via Temporal metrics.
Standalone Mode (Development & CI)
Standalone mode spins up the Temporal server inside the Compozy process. It is perfect for developers who want zero external dependencies.
temporal:
mode: standalone
host_port: localhost:7233
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: 30scompozy start --temporal-mode=standalone --temporal-standalone-database=:memory:When to Use Standalone
- Local development
Reduce onboarding friction—no Docker Compose, just run
compozy startand start building workflows. - Continuous integration
Run integration tests inside CI jobs without provisioning external clusters. Point tests to
TEMPORAL_MODE=standalonefor predictable behavior. - Workshops & samples
Ship self-contained examples that boot end-to-end in seconds, ideal for tutorials and demos.
Port Allocation
| Service | Port | Description |
|---|---|---|
| Frontend | 7233 | gRPC entrypoint for clients and workers |
| History | 7234 | Internal history service |
| Matching | 7235 | Task queue matching service |
| Worker | 7236 | System worker service (internal workflows) |
| Web UI | 8233 | Temporal Web UI (when enable_ui is true) |
Use the frontend_port field to shift the entire block of service ports. For example, setting frontend_port: 9733 exposes the services on 9733–9736.
Migrating Between Modes
Plan the migration
Audit current workflows, ensure retries are idempotent, and decide migration direction (remote → standalone for dev, or standalone → remote for prod).
Update configuration
Change temporal.mode and related fields in compozy.yaml. For standalone → remote, remove the standalone block to rely on remote defaults.
Rotate secrets & endpoints
Adjust environment variables (TEMPORAL_MODE, TEMPORAL_HOST_PORT, TEMPORAL_STANDALONE_*) and restart any long-running workers.
Verify connectivity
For remote mode, run temporal namespace describe. For standalone mode, open http://localhost:8233 to confirm the embedded UI is available.