amux Configuration Reference
This reference covers the settings read by amux from ~/.amux/config.toml. Common metadata lives in the public core's internal/config/reference.go; distributions register their own metadata through extensions. Update the owning module's metadata when changing keys, defaults, or constraints, then run make config-doc in that module. scripts/check.sh checks for omissions and stale generated files.
Common commands:
bash
amux system config path
amux system config get <key>
amux system config set <key> <value>
amux system config unset <key>“CLI-managed” specifically means the generic amux system config set/get/unset commands. Keys marked “No” may have dedicated commands listed in their descriptions; otherwise edit TOML directly. Replace <profile> with the actual Feishu Bot Profile name. <provider> supports only codex. This reference does not include example sensitive values.
Agent
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
adapter.codex.executable | string | codex | Program name, absolute path or ~/ path; not a shell command | Yes | Codex executable; empty uses codex. Resolved on the execution Runtime; save and restart to apply to new Sessions and model discovery. |
Runtime cleanup
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
maintenance.daily_cleanup.enabled | boolean | true | — | Yes | Automatically clean up ordinary and user-isolated topic data daily and privately report results to Bot owners. Installation-wide switch; applies immediately. |
maintenance.daily_cleanup.at | string | 06:17 | HH:MM | Yes | Daily cleanup time in the Hub local timezone; a missed run is performed once when the system resumes. |
maintenance.daily_cleanup.protected_paths | string array | [] | absolute paths | Yes | Absolute paths of shared or long-lived workspaces always retained by daily cleanup, across all Runtimes. |
runtime.task_cleanup.enabled | boolean | true | — | No | Whether to clean up terminal task history automatically. |
runtime.task_cleanup.terminal_history_ttl_seconds | integer seconds | 604800 (7 days) | >0 | No | Retention period for terminal task history. |
runtime.task_cleanup.sweep_interval_seconds | integer seconds | 3600 | >0 | No | Sweep interval for terminal task cleanup. |
runtime.broker_reap.enabled | boolean | true | — | No | Whether to periodically reap orphaned Session broker processes and their files (deleted or stopped Sessions, or duplicate brokers). |
runtime.broker_reap.sweep_interval_seconds | integer seconds | 300 | >0 | No | Sweep interval for orphaned broker reaping. |
Experimental Feishu features
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
bridge.feishu.group_settings.enabled | boolean | false | — | Yes | Installation-wide group settings experiment. When disabled, saved group settings and Sessions are retained and independently configured groups pause new work; unconfigured groups and private chats use Bot defaults. Restart to apply changes. |
bridge.feishu.presentation.completion_notification_enabled | boolean | false | — | Yes | Installation-wide experiment switch for long-session completion notifications, affecting every assistant. When disabled, no new success, input-needed, or failure notifications are sent. Restart after changing it. |
bridge.feishu.experimental.steer_foreground | boolean | false | — | Yes | Experiment switch for foreground coordination and busy-input steering. When enabled, follow-ups from the same sender while a turn runs are injected into that turn instead of interrupting it, and singleton and thread chats receive the foreground/background coordination prompt (first submit and every 20). When disabled, busy input interrupts and resubmits as before. AMUX_FEISHU_BUSY_INPUT=interrupt forces steering off. Restart after changing it. |
bridge.feishu.experimental.show_background_tasks | boolean | false | — | Yes | Background task progress card experiment: when on, each background task (subtask / background agent instance) started from a Feishu chat gets its own live progress card; off by default, background work posts no cards and the foreground agent reports results. Toggle on the Feishu experiments card; applies immediately on save. |
memory.enabled | boolean | false | — | Yes | Agent memory experiment switch, controlled by the Hub for all Runtimes without an Agent Profile; shared globally without isolation and scoped to the effective Principal with user isolation. Disabling blocks reads and writes while retaining files and native-memory suppression in existing conversations. Restart to apply. |
Hub and scheduling
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
hub.addr | string | 127.0.0.1:7100 | host:port | Yes | amuxd Hub address. |
hub.token | string | Sensitive; omitted | — | Yes | Shared authentication token for the Hub and Runtime. |
hub.allowed_targets | string array | [] | — | Yes | Allowlist of target IDs that may register with the Hub; empty means unrestricted. |
Runtime
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
runtime.id | string | Hostname | — | Yes | Stable Runtime identifier. |
runtime.name | string | runtime.id | — | Yes | Runtime display name. |
runtime.auto_start | boolean | false | — | Yes | Whether to start the Runtime automatically at installation or system startup. |
runtime.idle_timeout_seconds | integer seconds | 0 | 0 or >=60 | Yes | Legacy default sleep threshold; new configurations should use runtime.session_reclaim. |
runtime.max_sessions | integer | 100 (applied by the Runtime) | >=0 | Yes | Maximum concurrent Sessions on the machine; 0 uses the Runtime default. |
runtime.max_concurrency | integer | 10 (applied by the Runtime) | >=0 | Yes | Maximum concurrency per Agent type; 0 uses the Runtime default. |
runtime.labels.<label> | string map entry | None | — | Yes | Scheduling labels, such as pool and repo_cache. |
Session reclamation
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
runtime.session_reclaim.enabled | boolean | true | — | No | Master switch for staged Session reclamation. |
runtime.session_reclaim.sweep_interval_seconds | integer seconds | 600 | >0 | No | Sweep interval for Session reclamation. |
runtime.session_reclaim.local.sleep_after_seconds | integer seconds | 0 | 0 or >=60 | No | Automatic sleep threshold for local Sessions. |
runtime.session_reclaim.local.archive_after_seconds | integer seconds | 0 | 0 or >=60 | No | Automatic archive threshold for local Sessions. |
runtime.session_reclaim.local.prune_after_seconds | integer seconds | 0 | 0 or >=60 | No | Automatic deletion threshold for local Sessions. |
runtime.session_reclaim.feishu.sleep_after_seconds | integer seconds | 172800 (48 hours) | 0 or >=60 | No | Automatic sleep threshold for Feishu Sessions. |
runtime.session_reclaim.feishu.archive_after_seconds | integer seconds | 0 | 0 or >=60 | No | Automatic archive threshold for Feishu Sessions; disabled by default, enabled by an explicit positive value. |
runtime.session_reclaim.feishu.prune_after_seconds | integer seconds | 0 | 0 or >=60 | No | Threshold for automatically deleting local Feishu Session records and replay; disabled by default, enabled by an explicit positive value. Feishu messages are preserved. |
CLI and MCP
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
cli.default_target | string | local | — | Yes | Default CLI target. |
mcp.enabled | boolean | true | — | Yes | Whether to enable the built-in amux MCP server. |
mcp.auto_inject | boolean | true | — | Yes | Whether to automatically project the built-in MCP server into regular run Sessions. |
Isolated execution
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
isolation.global_env | KEY=VALUE string array | Sensitive; omitted | Valid, unique environment variable names | No | Installation-wide environment shared by all identified isolated executions. Manage with isolation global-env; explicit launch environment values take precedence. Restart the system after changes. |
Feishu basics
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
bridge.feishu.notify_chat_id | string | Empty | — | Yes | Legacy Feishu notification chat ID. |
bridge.feishu.prompt.shared_thread_enabled | boolean | false | — | Yes | Whether to inject shared thread history into the Prompt. |
bridge.feishu.prompt.topic_root_enabled | boolean | true | — | Yes | Whether to inject the root message into the first turn of a new topic. |
bridge.feishu.prompt.shared_thread_template_file | path | Empty | — | Yes | Shared thread Prompt template file. |
bridge.feishu.document_comments.enabled | boolean | false | — | Yes | Installation-wide switch for cloud document comment input. |
bridge.feishu.presentation.thinking_process | enum | collapsed | expanded、collapsed、hidden | Yes | Installation-wide activity display mode, inherited when a Profile does not override it. |
bridge.feishu.presentation.completion_notification_after_seconds | integer seconds | 60 | >=0; 0 disables all private-chat notifications for this feature | Yes | After a regular task succeeds, needs more input, or fails and reaches the duration threshold, send its initiator a private card linking back to the topic. No extra notification is added to the topic. Read status is not checked; agent-triggered work does not notify. |
Agent collaboration
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
bridge.feishu.bot_to_bot.enabled | boolean | false | — | Yes | Whether to accept structured, explicit mentions from external agents in shared workspace groups. |
bridge.feishu.bot_to_bot.max_turns_per_thread | integer | 10 | >0 | Yes | Maximum accepted agent collaboration turns per group topic. |
Group watch
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
bridge.feishu.group_watch.enabled | boolean | false | — | Yes | Installation-wide group watch switch; root messages with text or valid image, file, or merged-forward material can trigger it automatically. |
bridge.feishu.group_watch.chat_ids | string array | [] | — | Yes | Group chat_ids allowed to trigger automatically. |
bridge.feishu.group_watch.sender_types | string array | [user, app] | user、app | Yes | Message sender types allowed to trigger automatically. |
bridge.feishu.group_watch.chat_sender_types.<chat_id> | string array | Inherits sender_types | chat_id must also be present in chat_ids; values are user or app | Yes | Sender types allowed to trigger automatically for one watched group; groups without an override use sender_types. |
bridge.feishu.group_watch.poll_interval_seconds | integer seconds | 15 | 5-300 | Yes | History polling interval to recover messages from other apps. |
bridge.feishu.group_watch.lookback_seconds | integer seconds | 60 | 5-3600 and at least the polling interval | Yes | History recovery lookback window. |
bridge.feishu.group_watch.dedup.enabled | boolean | false | — | Yes | Whether to suppress duplicate app-authored alerts in the same group before creating a Session or reply card. |
bridge.feishu.group_watch.dedup.window_seconds | integer seconds | 1800 (30 minutes) | 60-86400 | Yes | Semantic deduplication window for app-authored alerts, measured from the last matching alert that was allowed to create a Session. The fingerprint uses the sending app, Rule ID and title, or normalized visible content when those fields are unavailable. |
bridge.feishu.group_watch.max_active_sessions_per_chat | integer | 50 | 1-500 | Yes | Maximum active group watch Sessions per watched group for the current agent. |
bridge.feishu.group_watch.idle_timeout_seconds | integer seconds | 10800 (3 hours) | 60-604800 | Yes | Automatic sleep threshold for new group watch Sessions. |
bridge.feishu.group_watch.thinking_process | enum | collapsed | expanded、collapsed、hidden | Yes | Installation-wide group watch activity display mode. |
Feishu workspace defaults
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
bridge.feishu.workspace_defaults.agent | string | builtin/codex | — | Yes | Default Agent Profile for new workspaces. |
bridge.feishu.workspace_defaults.target | string | Empty (automatic selection) | — | Yes | Default target for new workspaces. |
bridge.feishu.workspace_defaults.cwd | path | Empty | — | Yes | Legacy cwd; natural entry points still use an independent empty workspace. |
bridge.feishu.workspace_defaults.model | string | Empty | — | Yes | Default model override for new workspaces. |
bridge.feishu.workspace_defaults.args | string array | [] | — | Yes | Default Agent arguments for new workspaces. |
bridge.feishu.workspace_defaults.idle_timeout_seconds | integer seconds | 0 | 0 or >=60 | Yes | Sleep threshold for new workspace Sessions. |
bridge.feishu.claude_models | string array | [] | — | Yes | Extra Claude model names the Feishu model picker lists for the Claude runtime, appended after the built-in opus, sonnet, and haiku in declaration order so the latest models are selectable. Takes effect after restart. |
Feishu Bot Profiles
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
bridge.feishu.profiles.<profile>.workspace_defaults.agent | string | Inherit installation settings | — | Yes | Profile-level default workspace expert. |
bridge.feishu.profiles.<profile>.workspace_defaults.target | string | Inherit installation settings | — | Yes | Profile-level default workspace target. |
bridge.feishu.profiles.<profile>.workspace_defaults.cwd | path | Inherit installation settings | — | Yes | Profile-level legacy cwd. |
bridge.feishu.profiles.<profile>.workspace_defaults.model | string | Inherit installation settings | — | Yes | Profile-level default workspace model. |
bridge.feishu.profiles.<profile>.workspace_defaults.args | string array | Inherit installation settings | — | Yes | Profile-level default workspace arguments. |
bridge.feishu.profiles.<profile>.workspace_defaults.idle_timeout_seconds | integer seconds | Inherit installation settings | 0 or >=60 | Yes | Profile-level workspace sleep threshold. |
bridge.feishu.profiles.<profile>.interaction.mode | enum | thread | thread、singleton | Yes | Message routing mode for groups without independent settings. Group watch requires the target group’s effective mode to be thread. |
bridge.feishu.profiles.<profile>.presentation.thinking_process | enum | Inherit installation settings (collapsed) | expanded、collapsed、hidden | Yes | Activity display mode for the current assistant's regular tasks. |
bridge.feishu.profiles.<profile>.presentation.completion_notification_after_seconds | integer seconds | Inherit installation settings (60) | >=0; 0 disables all private-chat notifications for this feature | Yes | Completion notification threshold for the current assistant's regular tasks. |
bridge.feishu.profiles.<profile>.bot_e2e.sender_open_ids | string array | [] | — | Yes | Bot/app sender open_ids allowed to submit owner-authorized test input through @Bot /e2e. |
bridge.feishu.profiles.<profile>.bot_e2e.sender_roles | map[string]string | {} | owner、shared | Yes | Maps trusted test Bot sender open_ids to the projected identity of their /e2e requests (owner or shared). unauthorized is not supported; unmatched senders retain owner. |
bridge.feishu.profiles.<profile>.document_comments.enabled | boolean | Inherit installation settings | — | Yes | Profile-level cloud document comment switch. |
bridge.feishu.profiles.<profile>.document_comments.agent_profile_ref | string | Empty (inherit assistant) | — | Yes | Expert used for new cloud document comment Sessions. |
bridge.feishu.profiles.<profile>.document_comments.runtime_ref | string | Empty (inherit assistant or legacy configuration) | — | Yes | Runtime engine used for new cloud document comment Sessions. |
bridge.feishu.profiles.<profile>.document_comments.model_ref | string | Empty (Runtime engine default) | — | Yes | Model for new cloud document comment Sessions, validated against the selected Runtime engine. Without a Runtime override, follow the expert's model policy; native model names are allowed when supported_models is not declared. |
bridge.feishu.profiles.<profile>.document_comments.reasoning_effort | string | Empty (Runtime engine default) | — | Yes | Reasoning effort for new cloud document comment Sessions. |
bridge.feishu.profiles.<profile>.bot_to_bot.enabled | boolean | Inherit installation settings | — | Yes | Profile-level agent collaboration switch. |
bridge.feishu.profiles.<profile>.bot_to_bot.max_turns_per_thread | integer | Inherit installation settings (10) | >0 | Yes | Profile-level agent collaboration turn limit per topic. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.enabled | boolean | true | — | Yes | Enable watch in this group; automatic work also requires the master watch switch. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.agent_profile_ref | string | Empty (inherit ordinary conversations in this group) | — | Yes | Watch expert for this group; empty inherits its ordinary conversation execution settings. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.runtime_ref | string | Empty (inherit ordinary conversations in this group) | — | Yes | Runtime for custom watch execution in this group; required with a custom expert. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.model_ref | string | Empty (Runtime engine default) | — | Yes | Watch model for this group, validated against the selected runtime. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.reasoning_effort | string | Empty (Runtime engine default) | — | Yes | Watch reasoning effort for this group, validated against the selected runtime and model. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.thinking_process | enum | Inherit watch defaults | expanded、collapsed、hidden | Yes | Activity presentation for watch tasks in this group. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.max_active_sessions_per_chat | integer | Inherit watch defaults | 1-500 | Yes | Maximum active watch Sessions in this group. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.idle_timeout_seconds | integer seconds | Inherit watch defaults | 60-604800 | Yes | Idle timeout for new watch Sessions in this group. |
bridge.feishu.profiles.<profile>.group_watch.chat_settings.<chat_id>.version | integer | 0 | Non-negative integer | Yes | Watch settings version for this group, used to reject stale card writes. |
bridge.feishu.profiles.<profile>.group_watch.enabled | boolean | Inherit installation settings | — | Yes | Profile-level group watch switch; image-only, file-only, and merged-forward messages without text can also trigger automatically. |
bridge.feishu.profiles.<profile>.group_watch.chat_ids | string array | Inherit installation settings | — | Yes | Profile-level watched-group allowlist. |
bridge.feishu.profiles.<profile>.group_watch.sender_types | string array | Inherit installation settings | user、app | Yes | Profile-level sender types. |
bridge.feishu.profiles.<profile>.group_watch.chat_sender_types.<chat_id> | string array | Inherit installation settings | chat_id must also be present in this Profile's effective chat_ids; values are user or app | Yes | Profile-level sender type override for one watched group; groups without an override use the current Profile's sender_types. |
bridge.feishu.profiles.<profile>.group_watch.poll_interval_seconds | integer seconds | Inherit installation settings | 5-300 | Yes | Profile-level history polling interval. |
bridge.feishu.profiles.<profile>.group_watch.lookback_seconds | integer seconds | Inherit installation settings | 5-3600 | Yes | Profile-level history lookback window. |
bridge.feishu.profiles.<profile>.group_watch.dedup.enabled | boolean | Inherit installation settings | — | Yes | Profile-level semantic deduplication switch for app-authored alerts. |
bridge.feishu.profiles.<profile>.group_watch.dedup.window_seconds | integer seconds | Inherit installation settings (1800) | 60-86400 | Yes | Profile-level semantic deduplication window for app-authored alerts. |
bridge.feishu.profiles.<profile>.group_watch.max_active_sessions_per_chat | integer | Inherit installation settings (50) | 1-500 | Yes | Profile-level active Session limit per group. |
bridge.feishu.profiles.<profile>.group_watch.idle_timeout_seconds | integer seconds | Inherit installation settings (10800) | 60-604800 | Yes | Profile-level automatic sleep threshold for group watch. |
bridge.feishu.profiles.<profile>.group_watch.agent_profile_ref | string | Empty (inherit assistant) | — | Yes | Agent Profile for new group-watch Sessions. An empty value inherits the group’s effective default Profile; a custom selection is independent of Runtime. |
bridge.feishu.profiles.<profile>.group_watch.runtime_ref | string | Empty (inherit assistant) | — | Yes | Runtime for new group-watch Sessions. Inherited execution uses the group’s effective default Runtime; custom execution requires this field. |
bridge.feishu.profiles.<profile>.group_watch.model_ref | string | Empty (Runtime engine default) | — | Yes | Model for new group watch Sessions, validated against the selected Runtime engine. Without a Runtime override, follow the expert's model policy; native model names are allowed when supported_models is not declared. |
bridge.feishu.profiles.<profile>.group_watch.reasoning_effort | string | Empty (Runtime engine default) | — | Yes | Reasoning effort for new group watch Sessions; must be supported by the selected Runtime engine and model. |
bridge.feishu.profiles.<profile>.group_watch.thinking_process | enum | Inherit installation group watch settings (collapsed) | expanded、collapsed、hidden | Yes | Activity display mode for the current assistant's group watch tasks, configured separately from regular tasks. |
Structured Provider
| Configuration key | Type | Default | Constraints | CLI-managed | Description |
|---|---|---|---|---|---|
provider.structured.turn_idle_timeout_seconds | integer seconds | 900 | 0 disables; negative values use the default; maximum 604800 | No | Structured provider and ACP turn timeout when no meaningful activity occurs; paused while awaiting permission or an ACP tool without a progress contract. |
provider.structured.turn_hard_cap_seconds | integer seconds | 21600 | 0 disables; negative values use the default; maximum 604800 | No | Absolute duration limit for a structured provider or ACP turn, including time awaiting permission or tools. |
provider.structured.tool_idle_timeout_seconds | integer seconds | 3600 | 0 disables; negative values use the default; maximum 604800 | No | Structured provider tool timeout when no progress occurs. ACP has no verified tool progress contract and uses the turn hard cap. |
provider.structured.repeat_tool_call_limit | integer count | 50 | 0 disables; negative values use the default; maximum 1000 | No | Maximum consecutive identical tool calls in a structured provider or ACP turn. ACP counts only distinct call IDs with complete tool identity and input. |
provider.structured.<provider>.turn_idle_timeout_seconds | integer seconds | Inherit global settings | Provider is codex; 0 disables; negative values use the provider default; maximum 604800 | No | Turn idle timeout override for the specified provider. |
provider.structured.<provider>.turn_hard_cap_seconds | integer seconds | Inherit global settings | Provider is codex | No | Turn hard cap override for the specified provider. |
provider.structured.<provider>.tool_idle_timeout_seconds | integer seconds | Inherit global settings | Provider is codex | No | Tool idle timeout override for the specified provider. |
provider.structured.<provider>.repeat_tool_call_limit | integer count | Inherit global settings | Provider is codex; 0 disables; negative values use the provider default; maximum 1000 | No | Consecutive identical tool call limit override for the specified provider. |
State outside config.toml
Feishu App Secrets and legacy-host credentials live in $AMUX_HOME/secrets/; identified Agent credentials are stored per Principal in $AMUX_HOME/principals/<principal-id>/secrets/. Runtime state such as workspace Session quotas, thread bindings, and group watch bindings lives in Bridge/Runtime SQLite databases. These are not config.toml keys and must not be written to that file.