Goose Mm Bridge

License Python CI

A bridge that connects Goose to Mattermost, allowing you to interact with your Goose agent directly from your Mattermost channels and direct messages.

🚀 Features

• Seamless Integration: Chat with Goose or Hermes as if they were another user on Mattermost.
• Session Management: Maintains conversation context using Mattermost threads.
• Multi-user Support: Multiple users can interact with the bot simultaneously in their own sessions.
• Multi-agent Support: Dynamically switch between agents (such as Goose and Hermes) per user or per thread.
• OS-Native Isolation: Map Mattermost users to dedicated Linux accounts for strict security and tool isolation.
• MCP Tooling: Automatically exposes Mattermost capabilities to agents via the Model Context Protocol (MCP), allowing them to search history, find users, and send messages across channels.
• Thinking Transparency: Stream the agent's thinking process to Mattermost as message attachments.
• Interactive Commands: Use commands like !stop to interrupt the agent mid-response.

🏗 How it Works

1. Mattermost Polling: The bridge periodically polls the Mattermost API for new posts in channels the bot has joined.
2. Session Mapping: It tracks conversations by mapping the Mattermost user_id and root_id (thread ID) to a specific agent's ACP session.
3. Agent ACP Subprocess: The bridge spawns the selected agent (e.g., goose acp or hermes acp) as a subprocess and communicates via JSON-RPC.
4. Internal MCP Server: The bridge runs an internal FastMCP server that the agent connects to, providing tools for Mattermost interaction.
5. Asynchronous Handling: Uses asyncio to handle concurrent messages and streaming responses from the agent.

🛠 MCP Tools for Agents (Goose & Hermes)

When interacting with the agent (whether running Goose or Hermes), it has access to the following Mattermost tools:

• send_message: Send messages to any channel or thread.
• get_channels: List available channels.
• get_thread_context: Fetch full history of a thread with user attribution.
• search_messages: Search for content across all accessible teams.
• search_users: Find users by name, username, or email.
• get_user_info: Get detailed profile information for a user.
• send_direct_message: Start or continue a DM with one or more users.

🛡️ Security Model: OS-Native Isolation

The bridge supports user segmentation by mapping Mattermost users to dedicated Linux accounts. Each user's Goose session runs in its own process under its specific UID/GID, providing:

• Filesystem Isolation: The AI can only access files that the mapped Linux user has permissions for.
• Tool Isolation: Shell commands are executed as the mapped user.
• Memory/Config Isolation: Goose configuration and history are stored in the user's home directory (/home/username/.config/goose).

Per-User Config Overrides

The bridge allows you to override default settings (from .env) on a per-user basis. This lets individual Linux users have unique configurations (e.g., specific AI providers, models, custom API keys, or dedicated MCP servers).

To configure overrides for a user:

1. Create a .env file for the user inside the directory specified by USER_CONFIGS_DIR (defaults to user_configs/):

   mkdir -p user_configs
   touch user_configs/goose_user_1.env
   

2. Define any settings you want to override or add for that user. For example, in user_configs/goose_user_1.env:

   GOOSE_PROVIDER=openai
   OPENAI_API_KEY=sk-proj-...
   GOOSE_MODEL=gpt-4o
   # You can also supply custom MCP servers or environment variables for tools
   MY_CUSTOM_TOOL_API_KEY=secret_token
   

Any variables defined in the user's .env file will override the default values from the global .env file when running the agent as that user. Any extra custom environment variables will also be safely passed through the sudo security boundary.

Configuring Hermes and Specialized Extension Kits

Hermes supports a broad set of specialized developer toolkits (extension kits). You can customize Hermes behavior and set strict security boundaries on a per-user basis inside user_configs/<username>.env by toggling specific environment variables. For example, in user_configs/hermes_user_1.env:

# Switch to the Hermes agent
HERMES_PROVIDER=openrouter
HERMES_MODEL=nousresearch/hermes-3-llama-3.1-405b
OPENROUTER_API_KEY=sk-or-v1-...

# Optional: Run in YOLO (non-interactive autonomous) mode
HERMES_YOLO_MODE=true

# Configure specific tools and credentials for Hermes extension kits
GITHUB_TOKEN=ghp_...
AMAZON_AWS_ACCESS_KEY_ID=...

🛠 Prerequisites

• Goose and/or Hermes installed and available in your PATH.
• A Mattermost Bot account and Personal Access Token.
• Python 3.8+
• (Optional) sudo access on the host for OS-native isolation.

📦 Installation

1. Clone the repository:

   git clone https://github.com/mrazza/goose-mm-bridge.git
   cd goose-mm-bridge
   

2. Set up a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure your environment:

   cp .env.example .env
   # Edit .env with your Mattermost details
   

🛡️ Administrative Setup (Optional Isolation)

If you wish to use the OS-native isolation feature:

1. Provision Users: Use the provided setup_user.sh script to create isolated Linux users:

   sudo ./setup_user.sh goose_user_1
   

2. Configure Sudoers: Allow the bridge user to execute Goose as these managed users. See sudoers.template for guidance.

3. User Mapping: Create a user_mapping.json file to associate Mattermost IDs with Linux usernames:

   {
     "mattermost_user_id_1": "goose_user_1",
     "mattermost_username_2": "goose_user_2"
   }
   

   Set USER_MAPPING_FILE in your .env if you use a different path.

⚙️ Configuration

The bridge is configured via environment variables in the .env file:

Variable	Description	Default
MATTERMOST_URL	The base URL of your Mattermost instance (e.g., chat.example.com).
MATTERMOST_TOKEN	Your Mattermost Bot Personal Access Token.
MATTERMOST_SCHEME	The protocol used by Mattermost (http or https).	https
MATTERMOST_PORT	The port number Mattermost is listening on.	443
APPROVED_USERS	A comma-separated list of usernames or user IDs authorized to use the bot. If empty, any user who can reach the bot can use it.	(None)
ADMIN_USERS	A comma-separated list of usernames or user IDs authorized as administrators to run admin-only commands (e.g., !impersonate).	(None)
USER_MAPPING_FILE	Path to the JSON configuration file for OS-level user isolation.	user_mapping.json
POLL_INTERVAL	How often (in seconds) the bridge checks for new messages.	1
DEBUG	Set to true to see detailed JSON-RPC logs for troubleshooting.	false
GOOSE_THINKING_TRACE	When enabled, the agent's internal "thinking" steps are shown as message attachments.	true
GOOSE_THINKING_TRACE_SIMPLIFIED	When enabled, shows a compact "Thinking... [Last action]" status instead of full attachments.	true
RPC_TIMEOUT	Seconds to wait for Goose to respond before timing out.	600
REQUIRE_USER_MAPPING	If true, only users explicitly listed in the mapping file can use the bot.	false
MAX_SESSIONS	The maximum number of active thread contexts to keep before recycling.	100
MCP_ENABLED	Enables the internal MCP server, allowing Goose to call Mattermost tools.	true
MCP_HOST	The host address the internal MCP server binds to.	127.0.0.1
MCP_PORT	The port used by the internal MCP server.	8000
GOOSE_PROVIDER	The LLM provider configured inside the Goose process (e.g. openai, anthropic, google, mistral). Overrides any global configurations.	(None)
GOOSE_MODEL	The specific model identifier Goose will execute (e.g., claude-3-5-sonnet-latest, gpt-4o). Overrides global configurations.	(None)
OPENAI_API_KEY	OpenAI API Key injected into the Goose subprocess. Overrides global keys.	(None)
ANTHROPIC_API_KEY	Anthropic API Key injected into the Goose subprocess. Overrides global keys.	(None)
GOOGLE_API_KEY	Google API Key injected into the Goose subprocess. Overrides global keys.	(None)
MISTRAL_API_KEY	Mistral API Key injected into the Goose subprocess. Overrides global keys.	(None)
GOOSE_BUILTIN_EXTENSIONS	Comma-separated list of built-in Goose extension toolkits to load (e.g., developer,memory).	(None)
GOOSE_MCP_SERVERS	A single-line JSON array of Model Context Protocol server configuration objects to register with Goose.	[]
DEFAULT_AGENT	The default agent executable to start if none is specified by thread or user preferences (e.g. goose, hermes).	goose
HERMES_PROVIDER	The LLM provider configured inside the Hermes process (e.g., openai, anthropic, google, mistral, openrouter, deepseek, xai, gemini).	(None)
HERMES_MODEL	The specific model identifier Hermes will execute (e.g., nousresearch/hermes-3-llama-3.1-405b, deepseek-chat).	(None)
HERMES_INFERENCE_PROVIDER	Optional override for the Hermes inference endpoint provider.	(None)
HERMES_INFERENCE_MODEL	Optional override for the Hermes inference model.	(None)
HERMES_YOLO_MODE	When set to true, enables non-interactive, autonomous execution mode for Hermes.	false
OPENROUTER_API_KEY	OpenRouter API Key injected into the Hermes subprocess.	(None)
DEEPSEEK_API_KEY	DeepSeek API Key injected into the Hermes subprocess.	(None)
XAI_API_KEY	xAI API Key injected into the Hermes subprocess.	(None)
GEMINI_API_KEY	Gemini API Key injected into the Hermes subprocess.	(None)

💡 Note on Threading: The bridge uses Mattermost thread IDs (root_id) to isolate conversations. This allows you to have multiple, independent discussions with the bot simultaneously—even within the same channel. Mentioning the bot in a reply will continue that specific conversation thread.

🎮 Commands

The bridge supports specific commands that can be typed directly into the Mattermost chat:

• !stop: Immediately cancels the active prompt in the current thread.
• !agents: Lists all available configured agents (e.g., goose, hermes), indicating which one is active in the current thread and which one is your persistent default.
• !agent <name>: Switches the agent used for the current conversation thread to <name>. If <name> is omitted, shows the active agent for the current thread.
• !agent-default <name>: Sets <name> as your persistent default agent for all new threads. If <name> is omitted, shows your current default agent.
• !impersonate <username | user_id>: Allows administrators (configured in ADMIN_USERS) to operate as other users.
  • To impersonate: !impersonate @username or !impersonate user_id.
  • All subsequent prompts will execute under the target user's context (including Linux user mappings, dynamic configuration overrides, and thread histories).
  • Prompts will be automatically prepended with [Sender: @username] so the agent is aware of who it is interacting with.
  • Control commands like !stop will route directly to the impersonated user's session.
  • To clear impersonation: !impersonate clear, !impersonate off, or !impersonate stop.

🏃 Usage

You can start the bridge manually:

source venv/bin/activate
python src/bridge.py

The bot will start polling Mattermost for new messages and respond using the selected agent's ACP process.

---

Built with ❤️ for the Goose community.