Capacity, storage and network
These controls are for operators and AI agents maintaining a setup. Leave defaults unless you have a concrete capacity, storage or connection problem. They are available through the command line even when the app does not expose a developer settings screen.
Read the live catalog first
catalex settings --json
catalex settings advanced --json
The live catalog reports each key’s effective value, default, range, unit, editability and restart requirement. The settings catalog explains individual keys. Your installed release’s catalog takes precedence for supported keys and bounds. Secrets are not listed.
catalex settings set limits.max_active_turns=4
catalex settings set limits.max_active_turns=null
The first changes the maximum simultaneous turns; the second restores its default. Values are JSON, so quote shell arguments that contain a list or JSON string. Invalid or incompatible changes are refused. Running services restart automatically when required; a controller restart requirement is reported separately. Check the resulting operation and status, then verify a reply.
Common settings in practical units
catalex settings advanced set accepts integer fields in the units below. Unnamed values are retained. The read-only capability fields rich_cards and chart_kinds are also reported. Use the full settings catalog for supported editable boolean/list fields and more precise units.
| Advanced field | Unit / purpose | Why change it? |
|---|---|---|
max_active_turns | Replies running at once | Lower it to reduce CPU/memory pressure; raise only with capacity |
max_warm_runtimes | Idle agent processes retained | Balance quick replies against idle memory |
max_queued_inputs | Waiting messages per session | Bound how much work a busy chat can accumulate |
bootstrap_messages | Earlier messages given to a replacement session | Balance continuity against context size |
decision_expiry_minutes | Minutes before a pending decision expires | Match how long people realistically take to respond |
max_attachments | Files per message | Bound per-message processing |
attachment_retention_days | Days original attachments remain available | Balance later downloads against storage/privacy |
attachment_storage_mib | Total attachment spool size in MiB | Fit disk capacity; it is not a message-history deletion policy |
audio_max_mib | Maximum audio size in MiB | Bound upload and transcription work |
audio_max_seconds | Maximum audio duration in seconds | Keep transcription work practical |
tool_retries | Malformed communication-call retries before plain-text fallback | Recover limited formatting errors without endless retrying |
recovery_attempts | Automatic recovery attempts | Bound recovery loops after a session failure |
progress_per_second | Routine update rate | Prevent excessive intermediate output |
rich_cards | Reports whether new chats use interactive cards | Inspect structured interaction support; not changed by the integer-only advanced command |
chart_kinds | Reports allowed chart kinds | Inspect visual-output support; not changed by the integer-only advanced command |
catalex settings advanced set max_active_turns=2 attachment_retention_days=7
This reduces simultaneous work and keeps attachment availability shorter. Existing recipients may already have downloaded copies. Changing retention cannot retract those copies.
Addresses and ports
For initial setup, catalex setup --help lists --control-port, --native-chat-console-port, --native-chat-gateway-port, --agent-console-port, --agent-gateway-port, --service-port and --database-port. Set only ports you need to change; omitted flags preserve saved/default choices.
For an existing owned control endpoint:
catalex settings endpoints show --json
catalex settings endpoints set --port 7478
CatalEx reserves the new endpoint, checks readiness and manages recovery. A numeric loopback bind such as 127.0.0.1 or ::1 keeps management private to the computer. Do not expose it to receive messaging callbacks. Manual saved connections may need their address updated after a move.
For other listeners, inspect before changing:
catalex settings endpoints deployments show service --json
Use catalex settings endpoints deployments set TARGET FIELD PORT only for fields advertised as supported by that result. The command reports the original operation ID. If the outcome is uncertain, inspect that original ID using the endpoint command’s operation/recover help rather than starting another port move. Keep control, native-chat, agent and messaging-service addresses distinct.
Advanced client configuration
CATALEX_RELAY_HOME selects an absolute state/configuration home instead of ~/.catalex-relay. Use it only when intentionally maintaining a separate installation; changing it can make the existing setup appear missing.
The command-line client also supports bounded request, attachment, history and polling settings. See client environment settings. Set them for the command process, not in agent instructions or a secret-bearing transcript. A timeout change does not repair an offline service.