Mattermost configuration
Connector ENV
| Variable | Default | Purpose |
|---|---|---|
ORPHEUS_BASE_URL | required | Orpheus API base without /api/v1 |
ORPHEUS_API_KEY | required | Service Bearer key |
WORKFLOWS_DIR | workflows | Flat directory of .md workflow files |
LISTEN_ADDR | :8080 | Health and metrics listener |
HTTP_TIMEOUT | 30s | HTTP request timeout |
MAX_REQUEST_BYTES | 1048576 | Request budget, 4096 to 1048576 bytes |
MAX_PARALLEL_THREADS | 8 | Parallel thread reconciliations, 1 to 128 |
AGENTBOX_API_KEY | unset | File clarifications during active runs |
AGENTBOX_API_URL | SDK default | Optional SDK endpoint override |
Workflow YAML
| Field | Default | Purpose |
|---|---|---|
id | required | Unique workflow name |
revision | required | Revision string |
reconcile_from | required | Fixed UTC RFC3339 processing cutover |
profile | required | Orpheus profile name |
sandbox_template | required | AgentBox template name |
mattermost.base_url | required | Mattermost URL |
mattermost.token_env | required | Bot token ENV name |
env_from | [] | Worker variables selected for the agent |
services | [] | Unique service codes passed to the agent session alongside env_from |
include_ids / exclude_ids | [] | Included and excluded channel IDs. Does not enable private or group channels |
direct_messages | false | Handle direct messages |
private_channels | false | Handle private channels |
group_messages | false | Handle group messages |
start_on_mention | true | Require a mention to start a thread |
trigger_bot_ids | [] | Allowed external bots |
send_commentary_messages | true | Publish progress messages |
draining | false | Deliver accepted results without admitting new work |
message_batch_window | 0 | Message batching window |
poll_interval | 30s | Channel reconciliation interval |
full_reconcile_interval | 5m | Full session reconciliation interval |
max_concurrent_runs | 10 | Concurrent workflow runs |
run_timeout_seconds | 3600 | Agent execution timeout |
hook_timeout_seconds | 120 | File hook timeout |
max_session_tokens | 100000000 | Session token budget |
max_post_chars | 12000 | Post character limit, also capped by the server |
initial_context_token_budget | 100000 | Approximate initial context budget |
files.max_per_post | 5 | Input files per post, 1 to 100 |
files.max_file_bytes | 10485760 | Ordinary input file bytes |
files.max_image_bytes | 20971520 | Input image bytes |
files.max_batch_bytes | 104857600 | Input batch bytes, maximum 100 MiB |
files.max_output_files | 5 | Output file count, 1 to 100 subject to the Mattermost server limit |
files.max_output_bytes | 31457280 | Bytes per output file |
link_expansion.enabled | true | Expand same-server Mattermost links |
link_expansion.max_links | 5 | Expanded link count |
link_expansion.max_posts | 20 | Linked post count |
Unrouted private channels are left automatically. Configure private-channel access before starting or reloading the connector and before inviting the bot. See channel routing.
Mandatory fields are marked required. Unknown fields, duplicate keys, duplicate IDs and overlapping specialized routes are rejected. Quote revision as a string. Put the complete agent instructions after the YAML.
Do not store secrets in workflow files. token_env and env_from hold variable names. Examples · Apply changes.
Message author and channel
Each post reaches the agent as a separate message with front matter:
---
kind: thread
post_id: post-id
root_id: root-id
channel: {"id":"channel-id","name":"dev-test-group"}
author: {"id":"user-id","username":"alice","nickname":"Alice","email":"alice@example.com"}
created_at: 2026-10-01T07:00:00Z
---channel.name is the name in ~dev-test-group without ~. Direct and group channels use generated names. Linked threads carry their own authors and channels.
Email comes from the Mattermost profile. Bot and webhook posts do not carry email. Empty optional fields are omitted. This lets the Space skill identify the author of a specific request, but does not itself establish access permissions.
For email-based tools, the connector token must read other users' addresses. An ordinary bot requires Mattermost's PrivacySettings.ShowEmailAddress setting. Check GET /api/v4/users/{human-user-id} with the connector token: email on the bot's own profile is not sufficient. If the address is unavailable, the agent must not guess the schedule owner.