Monstrum Agent

Prerequisite: Before reading this page, we recommend familiarizing yourself with the distinction between Bot, Agent, and LLM in Core Concepts.

Monstrum Agent is a lightweight program that runs in your local environment and connects to the Monstrum platform via a secure WebSocket connection. It bridges local tools — MCP servers, custom functions, shell commands, and more — to the platform. Bots on the platform can invoke these tools just like any other Resource, with all calls subject to full permission checks and audit logging.

Overview

What Is an Agent

An Agent is an independent entity in the Monstrum platform. It is neither a Resource nor a Bot — it is a bridge between your local environment and the platform.

Key characteristics:

  • Runs locally: The Agent runs on your machine (laptop, dev server, intranet host, etc.) and consumes no platform resources
  • WebSocket connection: The Agent initiates an outbound connection to the platform, so there is no need to expose local ports or configure firewall rules
  • Automatic tool registration: Once connected, the Agent automatically registers local tools with the platform, and the corresponding Resources appear in the resource list
  • No permission downgrade: Tool calls executed through the Agent follow the exact same permission model as cloud-based execution (Pre-LLM filtering + Post-LLM validation)
  • Full audit trail: Every tool call executed through the Agent is recorded in the audit log, with the execution location marked as agent:{name}

How It Works

Your Local Environment                       Monstrum Platform
┌─────────────────────┐                ┌──────────────────────┐
│  monstrum-agent     │   WebSocket    │                      │
│  ┌───────────────┐  │ ◄────────────► │  Agent Connection    │
│  │ MCP servers   │  │                │  Manager             │
│  │ @tool funcs   │  │                │       │              │
│  │ Shell cmds    │  │                │  ┌────▼─────┐        │
│  │ .mst plugins  │  │                │  │ Resource │        │
│  └───────────────┘  │                │  │(auto-created)│    │
│                     │                │  └────┬─────┘        │
└─────────────────────┘                │       │              │
                                       │  ┌────▼─────┐        │
                                       │  │   Bot    │        │
                                       │  │(bound)   │        │
                                       │  └──────────┘        │
                                       └──────────────────────┘

When a Bot invokes an Agent tool, the full flow is:

  1. A tool call is triggered during a Bot conversation
  2. The platform performs Pre-LLM visibility filtering and Post-LLM parameter validation
  3. The platform sends the tool call request to your local Agent over WebSocket
  4. The Agent executes the tool in your local environment
  5. The result is returned to the platform over WebSocket
  6. The platform delivers the result to the Bot and records an audit log entry

Differences from Manually Creating a Resource

Manually Created ResourceAgent Auto-Created Resource
Creation methodConfigured manually in the UICreated automatically when the Agent connects
Credential managementCredentials added manuallyNot needed — the Agent already runs in a trusted environment
Tool executionExecuted in the platform cloudExecuted locally by the Agent
Use casePublicly reachable servicesLocal/intranet tools, development environments
Resource source labeluseragent:{name}

Installing monstrum-agent

The platform provides a one-line install script. After creating an Agent, the full install command is displayed. The script automatically:

  • Detects the Python environment (Python 3.9+ required)
  • Downloads and installs the monstrum-sdk package from GitHub Releases
  • Writes the Agent configuration (platform URL + Agent Key) to ~/.monstrum/agent.yaml
  • Sets up PATH if needed
  • Starts the Agent automatically

The install command follows this format:

curl -fsSL https://{platform_url}/api/public/agent/install.sh | sh -s -- "{agent_key}" --url "{platform_url}"

You do not need to assemble this command manually — the platform generates it for you after you create an Agent.

The script supports the following options:

OptionDescription
--url <platform_url>Platform URL (auto-filled by the script)
--name <agent_name>Set a local display name (optional)
--version <version>Install a specific version (defaults to latest)
--no-startInstall only, do not start

Option 2: Manual Installation

pip install monstrum-sdk

After installation, the monstrum-agent command is available. Run monstrum-agent --version to verify.

Creating an Agent

Steps

  1. Click Agent in the left navigation bar to open the Agent management page
  2. Click the New Agent button in the top-right corner
  3. Enter a name for the Agent in the dialog
    • The name must be unique within the workspace
    • Use a name that identifies the environment, such as my-laptop, dev-server, or office-workstation
  4. Click OK

Agent Key

After creation, an installation guide dialog appears with the following information:

  • Agent Key: An authentication key prefixed with ak_
  • Install command: The one-line installer command
  • Start command: The command to start the Agent after installation

Important: The Agent Key is displayed only once at creation time. Copy and save it immediately. If lost, you will need to regenerate the key (the old key is revoked immediately).

The Agent Key is generated using a cryptographically secure random number generator (48 hexadecimal characters). Each Agent has its own independent key. After the connection is established, the key is used only for the initial handshake and is not transmitted in subsequent communications.

Connecting the Agent

Using the One-Line Installer

If you used the one-line install script, the Agent starts automatically after installation and connects to the platform.

Manual Connection

If you installed monstrum-sdk manually, create a configuration file first, then start the Agent.

Configuration file ~/.monstrum/agent.yaml:

# Monstrum Agent Configuration
platform_url: "https://your-platform-url.com"
agent_key: "ak_your_agent_key_here"

# Built-in tools (all enabled by default)
builtins:
  system_info: true
  file_ops: true
  shell_exec: true
  sandbox: true
  browser: true

Start the Agent:

monstrum-agent start

You can also specify a custom config file path:

monstrum-agent start -c ./my-project/agent.yaml

After a Successful Connection

Once the Agent connects successfully, you will observe:

  1. Terminal output: The Agent prints a connection success message and the list of registered tools
  2. Platform status update: On the Agent management page, the Agent’s status changes to online (green dot)
  3. Automatic Resource creation: Tools registered by the Agent are grouped by source, and each group creates a Resource automatically
  4. Resources appear in the resource list: Agent-created Resources are visible on the resource management page

Connection Lifecycle

The Agent maintains a persistent connection with the platform, kept alive via a heartbeat mechanism:

  • The platform sends a heartbeat probe (ping) every 30 seconds; the Agent replies with pong
  • If the Agent fails to respond within 40 seconds, the platform considers the connection lost
  • When the Agent disconnects, its registered tools are removed from the platform (the Resource itself is retained with a “disconnected” status)
  • When the Agent reconnects, tools are automatically re-registered

Tool Registration

Tool Sources and Grouping

The Agent can register tools from multiple sources. Tools are automatically grouped by source, and each group creates a separate Resource:

SourceDescriptionResource TypeExample Resource Name
@tool decorated functionsPython custom toolsMonstrum Agent[my-laptop] agent
MCP serversProxied local/intranet MCPMCP[my-laptop] MCP: http://localhost:8080
.mst pluginsMonstrum plugin packagesCorresponding plugin type[my-laptop] Plugin: github

Benefits of this grouping design:

  • Tools from different sources have independently managed permissions
  • A Bot can bind to a subset of an Agent’s tool groups rather than all of them
  • MCP server tools and custom functions are governed separately

Tool Dynamics

Tools registered by the Agent follow a dynamic discovery model (see Tool Discovery Modes in Core Concepts):

  • The tool list is dynamically registered when the Agent connects and automatically removed when it disconnects
  • When binding, Bots select tools by name or use glob patterns (e.g., list_*, run_*) to control which tools are available
  • Tool definitions (name, description, parameter schema) are determined by the Agent side; the platform does not modify them

Tool vs Resource Persistence

Unlike MCP Resources, tools registered by the Agent are not persisted to the database — they exist only while the Agent is connected. When the Agent disconnects, tools are removed from the platform’s memory; when it reconnects, they are re-registered.

The Resource itself (name, binding relationships, permission configuration) is persisted and is not lost when the Agent disconnects.

Binding to a Bot

After the Agent registers its tools, the corresponding Resources automatically appear in the resource list. The binding process is identical to any other resource type.

Binding Steps

  1. Go to the Bot detail page and switch to the Resource Configuration tab
  2. Click Bind Resource
  3. Find the Agent-created Resource in the resource list (usually prefixed with [agent_name])
  4. Select the allowed tools:
    • Checkbox mode: Select individual tools from the registered list
    • Glob mode: Use wildcards (e.g., read_*, *_file) to match tool names
  5. Configure permission constraints (see Permission Dimensions below)
  6. Save the binding

Note: Agent-created Resources do not require credential selection. Tool execution is performed locally by the Agent and does not require credential decryption on the platform side.

Permission Dimensions

Monstrum Agent Resources support the following permission dimensions:

DimensionDescriptionExample
toolsAllowed tool namesrun_shell, read_file, list_*
pathsAllowed file paths/home/user/project/*, /var/log/*
commandsAllowed commandsls *, git *, npm *
imagesAllowed container imagespython:3.*, node:*

Glob pattern matching is used. Unconfigured dimensions are unrestricted.

If the Agent also registers MCP-type tools (proxied MCP servers), the corresponding Resource’s permission dimensions follow MCP-type rules (the tools dimension). See the MCP Resources section in Resources and Credentials.

If you have created role templates (see Roles and Permissions), you can select a role when binding to quickly apply a preset permission configuration.

Execution Flow

When a Bot conversation triggers a call to an Agent tool, the full execution pipeline is as follows:

1. Pre-LLM: Tool Visibility Filtering

Before the Bot begins inference, the platform filters the tool list based on resource bindings. Only Agent tools explicitly allowed in the binding appear in the LLM’s tool list. Unauthorized tools are completely invisible to the LLM.

2. LLM Inference

The LLM decides whether to call a tool and which tool to call based on the visible tool list and the user’s message.

3. Post-LLM: Parameter-Level Permission Validation

After the LLM returns a tool call, the platform validates that the call parameters fall within the configured permission constraints (e.g., the paths and commands dimensions). If parameters are out of bounds, the request is rejected.

4. Agent Routing

After permission validation passes, the platform checks whether the Resource’s associated Agent is online:

  • Agent online: The request is forwarded to the Agent via WebSocket
  • Agent offline: An “Agent not connected” error is returned

5. Local Execution and Result Return

The Agent executes the tool in the local environment and returns the result to the platform over WebSocket. The platform delivers the result to the Bot and records an audit log entry.

Timeout Handling

Tool calls have a default timeout of 30 seconds. If the Agent does not return a result within the timeout period, the platform returns a timeout error to the Bot. For tools that require longer execution times, consider implementing an asynchronous pattern in the tool implementation.

Agent Management

Agent List

Click Agent in the left navigation bar to open the management page. Each Agent in the list displays:

ColumnDescription
StatusOnline (green dot) or offline (gray dot)
NameAgent name (set at creation)
Agent KeyMasked display (first 8 characters + … + last 4 characters); click to copy the full key
ResourcesNumber of Resources auto-created by the Agent
Last OnlineTime of the Agent’s last connection or heartbeat

Enabling/Disabling an Agent

Toggle the Agent’s enabled state using the switch in the actions column:

  • Enabled: The Agent can connect to the platform
  • Disabled: The Agent cannot connect. If currently connected, it will be disconnected at the next heartbeat check

Regenerating the Agent Key

If the Agent Key is compromised or needs to be rotated per security policy:

  1. Click the regenerate icon in the Agent’s actions column
  2. Confirm the operation
  3. The new key is displayed in the installation guide dialog

Note: The old key is revoked immediately. You must update the agent_key field in your local Agent configuration file and restart the Agent.

Deleting an Agent

Click the delete icon in the Agent’s actions column and confirm. After deletion:

  • The Agent’s key is revoked and can no longer be used to connect
  • Resources auto-created by the Agent change to a “disconnected” status
  • Existing Bot bindings are preserved, but tool calls will fail because the Agent is offline
  • Historical records in the audit log are unaffected

One-Line Install Script Details

The platform’s one-line install script performs the following steps:

  1. Environment detection: Checks that Python 3.9+ is available
  2. Download package: Downloads the latest monstrum-sdk wheel from GitHub Releases
  3. Install dependencies: Installs monstrum-sdk[agent] via pip (which includes additional dependencies required by the Agent)
  4. Write configuration: Writes the platform URL and Agent Key to ~/.monstrum/agent.yaml
  5. PATH setup: If the monstrum-agent command is not on the PATH, provides instructions for adding it
  6. Auto-start: By default, starts the Agent after installation (skip with --no-start)

If the configuration file ~/.monstrum/agent.yaml already exists, the script backs up the original file as agent.yaml.bak, updates only the agent_key field, and preserves all other settings.

Running the install script again automatically upgrades to the latest version. You can also specify a version with the --version option.

Common Use Cases

Bridging Local Development Tools

Register tools from your local development environment with the platform so Bots can participate in your development workflow:

  • Code quality: Register linters, formatters, and type checkers so a Bot can directly check code quality
  • Build and test: Register commands like npm run build and pytest so a Bot can trigger builds and run tests
  • File and Git operations: Register file I/O and Git command tools so a Bot can view changes and create branches

Use the commands and paths permission dimensions to restrict which commands a Bot can execute and which file paths it can access.

Connecting Existing MCP Servers

If you have MCP servers running locally or on an intranet that are not publicly accessible, you can use the Agent as a proxy:

  1. The Agent starts locally and connects to the local/intranet MCP server
  2. The Agent retrieves the MCP server’s tool list
  3. The Agent registers these tools with the platform as MCP-type Resources
  4. Bots on the platform invoke the MCP server’s tools indirectly through the Agent

Advantages: No need to expose the MCP server to the public internet, no need to configure credentials on the platform, and you can proxy multiple MCP servers simultaneously.

Custom @tool Functions

Define custom tool functions using Python decorators, and the Agent will automatically discover and register them. Typical scenarios:

  • Database queries: Wrap internal database queries so a Bot can retrieve report data
  • Internal API calls: Wrap internal company APIs so a Bot can query tickets or send notifications
  • Domain-specific logic: Encapsulate business operations as tools, such as “generate report” or “check inventory”

Multi-Agent Collaboration

You can run multiple Agents in different environments, each registering a different set of tools:

  • Development Agent: Registers code tools (editors, compilers, test frameworks)
  • Operations Agent: Registers ops tools (monitoring queries, log viewing, service management)
  • Data Agent: Registers data tools (database queries, ETL operations, report generation)

Different Bots bind to Resources from different Agents, achieving separation of responsibilities.

Security Considerations

Protecting the Agent Key

  • The Agent Key is equivalent to the Agent’s identity credential — keep it safe
  • Do not commit the Agent Key to version control
  • Set the configuration file permissions to 600 (owner read/write only)
  • If you suspect the key has been compromised, regenerate it on the platform immediately

Principle of Least Privilege for Tools

  • When binding an Agent Resource to a Bot, select only the tools that are necessary
  • Make good use of the paths and commands dimensions to limit the scope of operations
  • Avoid registering broad shell execution tools without any constraints

Network Security

  • The WebSocket connection from Agent to platform uses WSS (TLS encrypted)
  • The Agent maintains only outbound connections and does not require opening local ports
  • Tool call credentials (if any) are decrypted by the platform and passed per call; the Agent does not cache them

Audit Trail

All tool calls executed through the Agent are recorded in the audit log with the execution location marked as agent:{agent_name}. You can filter by execution location in the Data Center’s audit log view.

FAQ

Agent connects but no tools are registered

Possible causes: No built-in tools are enabled in the Agent configuration; custom @tool functions are not being discovered correctly; the MCP server address is unreachable.

Troubleshooting: Check the Agent’s terminal output for tool discovery logs; verify the builtins configuration in ~/.monstrum/agent.yaml; confirm that the MCP server is running and its address is correct.

Agent disconnects frequently

Possible causes: Unstable network connection; incorrect platform URL in configuration; local firewall blocking WebSocket connections.

Troubleshooting: Verify that platform_url in agent.yaml is correct; check whether a proxy or firewall is blocking WebSocket connections (WSS uses port 443). The Agent will automatically attempt to reconnect after a disconnect.

Tool calls time out

Possible causes: Local tool execution exceeds the default 30-second timeout; high network latency; local tool execution is blocking.

Troubleshooting: Check the local tool execution time and consider optimizing or splitting long-running operations; review tool execution logs in the Agent terminal.

Agent cannot connect after key regeneration

Copy the newly generated Agent Key, edit the local configuration file ~/.monstrum/agent.yaml to update the agent_key field, then restart the Agent: monstrum-agent start.

Bot reports “Agent not connected” when calling Agent tools

Check the Agent’s status on the Agent management page to confirm it is online; verify that the local Agent process is running; make sure the Agent’s enable toggle is turned on.

How to update the Agent

Run the install command again to automatically upgrade to the latest version while preserving existing configuration. You can also update manually with pip install --upgrade monstrum-sdk, then restart the Agent.

Next Steps

Edit this page on GitHub