Application Configuration

Auth configures API authentication settings.

CORS configures Cross-Origin Resource Sharing policies.

Only applies when CORSEnabled is true.

CORSEnabled enables Cross-Origin Resource Sharing headers.

Set to true when the API is accessed from web browsers on different origins.

Host specifies the network interface to bind the server to.

Common values:

• "0.0.0.0": Listen on all interfaces (default)
• "127.0.0.1" or "localhost": Local access only
• Specific IP: Bind to a specific network interface

Port specifies the TCP port for the HTTP server.

Valid range: 1-65535. Common ports:

• 8080: Default development port
• 80: Standard HTTP (requires privileges)
• 443: Standard HTTPS (requires privileges)

Reconciler configures the workflow reconciler subsystem.

SeedFromRepoOnEmpty controls whether builder mode seeds the store from repository YAML once when the store is empty. Disabled by default.

SourceOfTruth selects where the server loads workflows from.

Values:

• "repo": load YAML from repository and index to store (default)
• "builder": load workflows from ResourceStore (compile-from-store)

Timeout sets the maximum duration for processing requests.

Applies to all HTTP operations including request reading, processing, and response writing. Default: 30s. Increase for long-running operations.

Timeouts contains operator-tunable timeouts and retry/backoff settings for server startup, shutdown, and HTTP behavior.

.timeouts

APIKey authenticates CLI requests to the Compozy API.

Security: Always use environment variables for API keys. Never commit API keys to version control.

BaseURL specifies the Compozy API endpoint.

Default: "https://api.compozy.com" Use custom endpoints for self-hosted or development environments.

ColorMode controls terminal color output.

Options:

• "auto": Detect terminal color support (default)
• "on": Force color output
• "off": Disable all color output

ConfigFile specifies a custom configuration file path.

Default: "./compozy.yaml" or "~/.compozy/config.yaml"

Debug enables verbose debug logging.

Shows detailed API requests, responses, and internal operations.

DefaultFormat sets the default output format.

Options:

• "json": JSON format for programmatic consumption
• "tui": Terminal UI with tables and formatting (default)
• "auto": Automatically detect based on terminal capabilities

EnvFile specifies a .env file to load environment variables from.

Variables in this file are loaded before processing configuration.

Interactive enables interactive prompts and confirmations.

Default: true Set to false for non-interactive environments.

Mode controls the CLI execution behavior.

Available modes:

• "normal": Standard interactive mode (default)
• "batch": Non-interactive batch processing
• "script": Optimized for scripting (minimal output)

NoColor disables all color output regardless of terminal support.

Overrides ColorMode when set to true.

OutputFormatAlias allows custom output format aliases.

Used internally for format customization.

PageSize sets the number of results per page in list operations.

Default: 50 Range: 1-1000

PortReleasePollInterval sets how often to check if a port has become available.

Default: 100ms

PortReleaseTimeout sets the maximum time to wait for a port to become available.

Default: 5s

Quiet suppresses all non-error output.

Useful for scripting and automation.

ServerURL overrides the server URL for local development.

This takes precedence over BaseURL when set. Example: "http://localhost:8080" for local server

Timeout sets the maximum duration for API requests.

Default: 30s Increase for long-running operations like workflow execution.

AutoMigrate enables automatic database migrations on startup.

When enabled, the system will automatically apply any pending database migrations when establishing a database connection. This eliminates the need for manual migration commands.

Default: true

ConnString provides a complete PostgreSQL connection URL.

Format: postgres://user:password@host:port/database?sslmode=mode Takes precedence over individual connection parameters.

Host specifies the database server hostname or IP address.

Default: "localhost"

MigrationTimeout sets the maximum allowed time for applying database migrations during startup. It must be equal to or greater than the advisory lock acquisition window used by ApplyMigrationsWithLock (45s).

Default: 2m

DBName specifies the database name to connect to.

Default: "compozy"

Password specifies the database password for authentication.

Security: Use environment variables in production.

Port specifies the database server port.

Default: "5432" (PostgreSQL default)

SSLMode configures SSL/TLS connection security.

Options:

• "disable": No SSL (development only)
• "prefer": Try SSL, fallback to non-SSL
• "require": SSL required (recommended)
• "verify-ca": SSL with CA verification
• "verify-full": SSL with full verification

User specifies the database username for authentication.

HostPort specifies the Temporal server endpoint.

Format: host:port Default: "localhost:7233"

Namespace isolates workflows within Temporal.

Use different namespaces for:

• Environment separation (dev, staging, prod)
• Multi-tenant deployments
• Workflow versioning Default: "default"

TaskQueue identifies the queue for workflow tasks.

Workers poll this queue for tasks to execute. Use different queues for:

• Workflow type separation
• Priority-based routing
• Resource isolation Default: "compozy-tasks"

AsyncTokenCounterBufferSize sets the token counter queue size.

Larger buffers handle traffic spikes better but use more memory. Default: 100

AsyncTokenCounterWorkers sets the number of token counting workers.

More workers improve throughput for high-volume token counting. Default: 4

BunPermissions defines runtime security permissions for Bun.

Default: ["--allow-read"]

DispatcherHeartbeatInterval sets how often dispatchers report health.

Lower values provide faster failure detection but increase load. Default: 30s

DispatcherHeartbeatTTL sets heartbeat expiration time.

Must be greater than heartbeat interval to handle network delays. Default: 90s

DispatcherStaleThreshold defines when a dispatcher is considered failed.

Triggers reassignment of dispatcher's workflows. Default: 120s

Entrypoint specifies the path to the JavaScript/TypeScript entrypoint file. Overrides global runtime.entrypoint_path setting if specified.

EntrypointPath specifies the path to the JavaScript/TypeScript entrypoint file.

Default: "./tools.ts"

Environment specifies the deployment environment.

Affects:

• Error verbosity and stack traces
• Performance optimizations
• Debug endpoints availability
• Default timeouts and limits

Values: "development", "staging", "production"

LogLevel controls logging verbosity.

Levels (least to most verbose):

• "error": Critical errors only
• "warn": Warnings and errors
• "info": General operational info (default)
• "debug": Detailed debugging information

NativeTools configures native cp__ tool behavior and guards.

Permissions defines runtime security permissions. Overrides global runtime.bun_permissions setting if specified.

RuntimeType specifies the JavaScript runtime to use for tool execution.

Values: "bun", "node" Default: "bun"

TaskExecutionTimeoutDefault controls the fallback timeout applied when direct task executions omit a timeout value. Applies to synchronous and asynchronous direct executions triggered via API. Default: 60s

TaskExecutionTimeoutMax caps the maximum timeout allowed for direct task executions. Client-specified or configuration-derived timeouts exceeding this value are rejected. Default: 300s

ToolExecutionTimeout sets the maximum time for tool execution.

Prevents runaway tools from blocking workflows. Default: 60s

Type specifies the JavaScript runtime to use for tool execution. Overrides global runtime.runtime_type setting if specified.

MaxConfigFileNestingDepth limits nesting depth when parsing configuration files.

Prevents stack overflow from deeply nested YAML documents supplied by users. Default: 100

MaxConfigFileSize limits configuration file size during loads.

Prevents memory exhaustion when loading large YAML/JSON documents. Default: 10MB (10485760 bytes)

MaxMessageContent limits LLM message content size.

Prevents excessive API costs and timeouts. Default: 50MB (52428800 bytes)

MaxNestingDepth limits JSON/YAML structure nesting.

Prevents stack overflow from deeply nested data. Default: 20

MaxStringLength limits individual string values.

Applies to all string fields in requests and responses. Default: 10MB (10485760 bytes)

MaxTaskContextDepth limits task execution stack depth.

Prevents infinite recursion in workflow execution. Default: 10

MaxTotalContentSize limits total request/response size.

Prevents memory exhaustion from large payloads. Default: 100MB (104857600 bytes)

ParentUpdateBatchSize controls database update batching.

Larger batches improve throughput but increase memory usage. Default: 100

MaxEntries limits memory entries per conversation.

Prevents unbounded memory growth. Default: 10000

Prefix namespaces memory keys in Redis.

Prevents key collisions when sharing Redis. Default: "compozy:memory:"

TTL sets memory entry expiration time.

Balances context retention with storage costs. Default: 24h

AllowedMCPNames restricts which MCP servers/tools are considered eligible for advertisement and invocation. When empty, all discovered MCP tools are eligible.

ContextCompactionCooldown specifies how many loop iterations to wait between compaction attempts.

ContextCompactionThreshold expresses the context usage ratio (0-1) that triggers compaction.

DeniedMCPNames excludes MCP servers/tools from advertisement and invocation. Entries take precedence over the allow list.

EnableContextCompaction toggles summary-based compaction when context usage nears limits.

EnableDynamicPromptState toggles inclusion of orchestrator loop state inside the system prompt.

EnableLoopRestarts toggles whether the orchestrator may restart the loop when no progress is detected.

EnableProgressTracking toggles loop progress tracking to detect stalled conversations or repeated tool usage without advancement. Default: false

FailOnMCPRegistrationError enforces fail-fast behavior when registering MCP configurations sourced from agents/projects. When true, MCP registration failures cause service initialization to error.

FinalizeOutputRetryAttempts overrides the number of retries allowed when final structured output is invalid.

MaxConcurrentTools limits the number of tools that can execute in parallel.

Controls resource usage and prevents overwhelming downstream services. Higher values improve throughput, lower values reduce resource contention. Default: 10

MaxConsecutiveSuccesses controls how many consecutive successful tool calls without progress are tolerated before the orchestrator halts the loop. Default: 3 (orchestrator default)

MaxLoopRestarts caps how many restarts are attempted per loop execution.

MaxSequentialToolErrors caps how many sequential tool execution/content errors are tolerated for the same tool before aborting the task. Set to 0 to use the orchestrator's built-in default. Default: 10 (registry default)

MaxToolIterations caps the maximum number of tool-iteration loops per request.

This acts as a global default and can be overridden by model-specific configuration in project files. Set to 0 to use the orchestrator's built-in default. Default: 100 (registry default)

MCPClientTimeout sets the HTTP client timeout for MCP proxy communication.

MCPHeaderTemplateStrict enables strict template validation for MCP HTTP headers. When true, allows only simple lookups (no pipelines/function calls/inclusions). Default: false

MCPReadinessPollInterval sets how often to poll the proxy for MCP connection status. Default: 200ms

MCPReadinessTimeout bounds how long to wait for MCP clients to connect during setup. Default: 60s

NoProgressThreshold configures how many loop iterations without progress are tolerated before the orchestrator considers the interaction stalled. Default: 3 (orchestrator default)

ProxyURL specifies the MCP proxy server endpoint.

The proxy handles:

• MCP server connections
• Tool discovery and routing
• Protocol translation Default: "" (empty; supply MCP proxy URL explicitly or derive from MCPProxy.BaseURL)

RegisterMCPs contains additional MCP configurations to be registered with the MCP proxy at runtime. Represented as a generic slice to avoid import cycles with engine packages.

RestartStallThreshold controls how many stalled iterations trigger a loop restart. Values greater than no_progress_threshold are automatically clamped to match the no progress limit and emit a warning event.

RetryAttempts configures the number of retry attempts for LLM operations.

Controls how many times the orchestrator will retry failed LLM requests before giving up. Higher values improve reliability but may increase latency. Default: 3

RetryBackoffBase sets the base delay for exponential backoff retry strategy.

The actual delay will be calculated as base * (2 ^ attempt) with optional jitter. Lower values retry faster, higher values reduce server load. Default: 100ms

RetryBackoffMax limits the maximum delay between retry attempts.

Prevents exponential backoff from creating extremely long delays. Should be set based on user tolerance for response time. Default: 10s

RetryJitter enables random jitter in retry delays to avoid thundering herd.

When enabled, adds randomness to retry delays to prevent all clients from retrying simultaneously. Improves system stability under load. Default: true

RetryJitterPercent controls jitter strength when retry_jitter is enabled.

ToolCallCaps configures per-tool invocation caps enforced during orchestration.

APIKeyRate applies per API key.

Ensures fair usage across different clients.

GlobalRate applies to all requests system-wide.

Protects against total system overload.

MaxRetry sets retry attempts for rate-limited requests.

Default: 3

Prefix namespaces rate limit keys in Redis.

Default: "ratelimit:"

DB selects the Redis database number.

Default: 0

DialTimeout sets timeout for establishing new connections.

Default: 5s

Host specifies the Redis server hostname or IP address.

Default: "localhost"

MaxIdleConns sets the maximum number of idle connections.

Default: 0

MaxRetries sets the maximum number of retries before giving up.

Default: 3

MaxRetryBackoff sets maximum backoff between retries.

Default: 512ms

MinIdleConns sets the minimum number of idle connections.

Default: 0

MinRetryBackoff sets minimum backoff between retries.

Default: 8ms

NotificationBufferSize sets buffer size for pub/sub notifications.

Default: 100

Password authenticates with Redis.

Security: Use environment variables in production.

PingTimeout sets timeout for ping command.

Default: 1s

PoolSize sets the maximum number of socket connections.

Default: 10 per CPU

PoolTimeout sets timeout for getting connection from pool.

Default: ReadTimeout + 1s

Port specifies the Redis server port as a string.

Format: String representation of port number (1-65535) YAML: Both "6379" (quoted) and 6379 (numeric) are accepted Breaking Change: Changed from int to string in v2.0.0

Default: "6379"

ReadTimeout sets timeout for socket reads.

Default: 3s

TLSEnabled enables TLS encryption.

Default: false

URL provides a complete Redis connection string.

Format: redis://[user:password@]host:port/db Takes precedence over individual connection parameters.

WriteTimeout sets timeout for socket writes.

Default: ReadTimeout

CompressionEnabled activates data compression for cached items.

Reduces memory usage and network bandwidth at the cost of CPU. Uses gzip compression for items above CompressionThreshold.

Default: true

CompressionThreshold sets the minimum size for compression.

Items smaller than this are stored uncompressed to avoid CPU overhead for minimal space savings.

Default: 1024 (1KB)

Enabled determines if caching is active.

When disabled, all cache operations become no-ops. Useful for debugging or when Redis is unavailable.

Default: true

EvictionPolicy controls how items are removed when cache is full.

Options:

• "lru": Least Recently Used (default)
• "lfu": Least Frequently Used
• "ttl": Time-based expiration only

Default: "lru"

KeyScanCount controls the COUNT hint used by Redis SCAN for key iteration. Larger values reduce round-trips but may increase per-iteration latency. Set to a positive integer; defaults to 100.

MaxItemSize limits the maximum size of a single cached item.

Prevents large objects from consuming excessive memory. Items larger than this are not cached.

Default: 1048576 (1MB)

Prefix namespaces cache keys in Redis.

Prevents key collisions when sharing Redis with other applications. Format: "<app>:<environment>:cache:"

Default: "compozy:cache:"

StatsInterval controls how often cache statistics are logged.

Set to 0 to disable statistics logging. Useful for monitoring cache hit rates and performance.

Default: 5m

TTL sets the default time-to-live for cached items.

Balances data freshness with cache efficiency. Can be overridden per operation.

Default: 24h

ConfigStoreTTL sets how long worker configurations are cached.

Default: 24h

Dispatcher defines heartbeat tracking for dispatcher leases.

DispatcherMaxRetries sets maximum dispatcher retry attempts.

Default: 2

DispatcherRetryDelay sets delay between dispatcher retry attempts.

Default: 50ms

HeartbeatCleanupTimeout sets timeout for heartbeat cleanup operations.

Default: 5s

MCPProxyHealthCheckTimeout sets timeout for MCP proxy health checks.

Default: 10s

MCPShutdownTimeout sets timeout for MCP server shutdown.

Default: 30s

StartWorkflowTimeout bounds the HTTP handler's call to start a workflow execution to avoid hanging requests when Temporal is slow or unreachable. If zero or negative, a safe default is used.

Default: 5s

BaseURL specifies the base URL for MCP proxy API endpoints.

Default: "" (empty string)

Host specifies the network interface to bind the MCP proxy server to.

Default: "0.0.0.0"

Mode controls how the MCP proxy runs within Compozy.

Values:

• "standalone": embed MCP proxy inside the server
• "": external MCP proxy (default)

When embedded, the server manages lifecycle and health of the proxy and will set LLM.ProxyURL if empty.

Port specifies the TCP port for the MCP proxy server.

Default: 0 (ephemeral)

ShutdownTimeout sets timeout for graceful shutdown.

Default: 30s

AllowedMIMETypes specifies MIME allowlists by content category.

Empty lists do not allow everything; they mean "use built-in defaults" per attachment type. Resolvers fall back to type heuristics when the allowlist for a category is empty.

DownloadTimeout sets the timeout for downloading a single attachment. Default: 30s

HTTPUserAgent sets the User-Agent header for outbound downloads. Default: "Compozy/1.0"

MaxDownloadSizeBytes caps the maximum size (in bytes) for any single download. Default: 10_000_000 (10MB)

MaxRedirects limits the number of HTTP redirects followed during download. Default: 3

MIMEHeadMaxBytes controls how many initial bytes are used for MIME detection. Default: 512

PDFExtractMaxChars caps the number of characters extracted from PDFs. Default: 1_000_000

SSRFStrict enforces blocking of local/loopback/private/multicast destinations even in tests. Default: false

TempDirQuotaBytes optionally caps total temp storage used by attachment resolution. 0 disables the quota.

TextPartMaxBytes caps the number of bytes loaded from text files into LLM parts. Default: 5_242_880 (5MB)

DefaultDedupeTTL sets the default time-to-live for webhook deduplication. Default: 10m (10 minutes) Must be non-negative

DefaultMaxBody caps the maximum size (in bytes) for webhook request bodies. Default: 1,048,576 (1MB) Must be greater than 0

DefaultMethod specifies the default HTTP method for webhook requests. Default: "POST" Valid values: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

StripeSkew sets the allowed timestamp skew for Stripe webhook verification. Default: 5m (5 minutes) Must be non-negative