Skip to content

Mattermost configuration ​

Connector ENV ​

VariableDefaultPurpose
ORPHEUS_BASE_URLrequiredOrpheus API base without /api/v1
ORPHEUS_API_KEYrequiredService Bearer key
WORKFLOWS_DIRworkflowsFlat directory of .md workflow files
LISTEN_ADDR:8080Health and metrics listener
HTTP_TIMEOUT30sHTTP request timeout
MAX_REQUEST_BYTES1048576Request budget, 4096 to 1048576 bytes
MAX_PARALLEL_THREADS8Parallel thread reconciliations, 1 to 128
AGENTBOX_API_KEYunsetFile clarifications during active runs
AGENTBOX_API_URLSDK defaultOptional SDK endpoint override

Workflow YAML ​

FieldDefaultPurpose
idrequiredUnique workflow name
revisionrequiredRevision string
reconcile_fromrequiredFixed UTC RFC3339 processing cutover
profilerequiredOrpheus profile name
sandbox_templaterequiredAgentBox template name
mattermost.base_urlrequiredMattermost URL
mattermost.token_envrequiredBot 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_messagesfalseHandle direct messages
private_channelsfalseHandle private channels
group_messagesfalseHandle group messages
start_on_mentiontrueRequire a mention to start a thread
trigger_bot_ids[]Allowed external bots
send_commentary_messagestruePublish progress messages
drainingfalseDeliver accepted results without admitting new work
message_batch_window0Message batching window
poll_interval30sChannel reconciliation interval
full_reconcile_interval5mFull session reconciliation interval
max_concurrent_runs10Concurrent workflow runs
run_timeout_seconds3600Agent execution timeout
hook_timeout_seconds120File hook timeout
max_session_tokens100000000Session token budget
max_post_chars12000Post character limit, also capped by the server
initial_context_token_budget100000Approximate initial context budget
files.max_per_post5Input files per post, 1 to 100
files.max_file_bytes10485760Ordinary input file bytes
files.max_image_bytes20971520Input image bytes
files.max_batch_bytes104857600Input batch bytes, maximum 100 MiB
files.max_output_files5Output file count, 1 to 100 subject to the Mattermost server limit
files.max_output_bytes31457280Bytes per output file
link_expansion.enabledtrueExpand same-server Mattermost links
link_expansion.max_links5Expanded link count
link_expansion.max_posts20Linked 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:

yaml
---
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.