Documentation

Setup, commands, config. Everything in one place.

Quick Start

Three steps. Under 2 minutes. No, really.

Step 1: Connect your messenger

Find mttrly in your messenger: Telegram (@mttrly_bot), Slack (add to workspace), or Discord (invite bot). Start a chat — you'll get your API token right away.

Step 2: Install the agent

SSH into your server and run this. It's a lightweight Go binary (~10MB), no dependencies, no bloat.

curl -sL https://mttrly.com/install.sh | bash -s -- -t YOUR_TOKEN

Step 3: Say hello

Send /status in your messenger. If you see your server's CPU, RAM, and disk stats — you're done. That was fast.

Commands

Every command mttrly understands, with options and examples.

$ /status

Server health at a glance: CPU, RAM, disk, running services.

Options:

-vVerbose — includes process list
-jOutput as JSON (for scripts)

Example:

/status -v

$ /logs

Read logs without SSH. Filter by service, tail in real-time, or show only errors.

Options:

<service>Which service (nginx, app, etc.)
-n <lines>How many lines (default: 50)
-fFollow — like tail -f
--errorsErrors only

Example:

/logs nginx -n 100 --errors

$ /restart

Restart a service. Asks you to confirm first (unless you --force it).

Options:

<service>Service to restart
--forceSkip confirmation — you're sure

Example:

/restart nginx

$ /deploy

Git pull + restart. The deploy button you always wanted.

Options:

<app>Which app to deploy
--branch <name>Git branch (default: main)

Example:

/deploy myapp --branch staging

$ /run

Run a custom playbook you've defined in config.

Options:

<playbook>Playbook name

Example:

/run cleanup-logs

Configuration

One YAML file. Three main sections. Here's what you can tweak.

Config file location: /etc/mttrly/config.yaml

services

Tell mttrly which services it can manage. Only these will show up in commands.

services:
  - nginx
  - myapp
  - redis

playbooks

Your own scripts, triggerable via /run. Set confirm: true for anything scary.

playbooks:
  cleanup-logs:
    script: /opt/scripts/cleanup.sh
    confirm: true

alerts

Get pinged when resource usage crosses a threshold. Set percentages that make sense for your setup.

alerts:
  cpu_threshold: 80
  memory_threshold: 90
  disk_threshold: 85

Security

How mttrly keeps your servers safe. The short version: we're paranoid so you don't have to be.

Outbound-only connections

The agent connects to us — not the other way around. No ports to open. Your firewall stays exactly as it is.

Confirmation before anything scary

Restart, deploy, custom scripts — all need you to tap "Confirm" first. No surprises, no accidental nukes.

Minimal permissions

The agent runs as its own user with bare minimum privileges. You decide which commands get sudo. Nothing else does.

Encrypted everything

All traffic between your server and your messenger is encrypted. We don't store your logs or sensitive data. Period.

Token rotation

Think your token leaked? Regenerate it. The old one dies instantly. Takes 10 seconds.

Troubleshooting

Something not working? Start here.

Agent won't connect

→Make sure outbound WebSocket connections are allowed (port 443)
→Double-check your API token — copy-paste errors are real
→Check agent logs: journalctl -u mttrly

Commands timeout

→Your server might be under heavy load — the agent needs CPU too
→Check if the server has internet access
→Try restarting the agent: systemctl restart mttrly

Permission denied

→The mttrly user needs access to the service you're managing
→Add specific sudo permissions in /etc/sudoers.d/mttrly

MCP Server

Connect mttrly to AI coding assistants via the Model Context Protocol. Endpoint: https://api.mttrly.com/mcp

Connection

mttrly MCP server uses HTTP transport with OAuth 2.1 authentication. Add it to your client:

Claude Codebash

claude mcp add mttrly --transport http https://api.mttrly.com/mcp

OAuth login opens in browser automatically.

Cursorjson

{
  "mcpServers": {
    "mttrly": {
      "url": "https://api.mttrly.com/mcp"
    }
  }
}

Cursor → Settings → Cursor Settings → MCP → Add server.

Claude Desktopjson

{
  "mcpServers": {
    "mttrly": {
      "url": "https://api.mttrly.com/mcp"
    }
  }
}

Settings → Developer → Edit Config → claude_desktop_config.json.

OpenAI Codextoml

[mcp_servers.mttrly]
url = "https://api.mttrly.com/mcp"

Add to ~/.codex/config.toml. Run codex mcp login mttrly for OAuth.

Authentication

Two authentication modes are supported:

OAuth 2.1 (recommended)

Standard OAuth flow with PKCE S256. JWT tokens signed with RS256. Issuer: https://app.mttrly.com. Audience: https://api.mttrly.com/mcp. MCP clients handle this automatically — you just approve the login in browser.

API Key

Bearer token with mtr_ prefix. Pass as Authorization: Bearer mtr_your_key. Available from your dashboard.

Unauthenticated requests return 401 with a WWW-Authenticate header pointing to the OAuth discovery endpoint.

Tools Reference

35+ tools organized by access level. Always call mttrly_get_capabilities first to check your plan and available tools.

Available on all plans

mttrly_get_capabilities

Get current plan, available tools, restricted tools, and plan limits. Call this first before using any other tool.

mttrly_list_servers

List all connected servers with their status (online/offline).

mttrly_get_server_status

Get detailed server status including CPU, RAM, disk usage and active alerts count.

server_idstringrequired— Server ID from mttrly_list_servers

mttrly_get_alerts

Get alerts (incidents) for a server with severity/status filtering. Plan-based retention limits apply.

server_idstringrequired— Server ID

limitnumberoptional— Max alerts to return, 1–500. Default: 20

since_daysnumberoptional— Look back N days, 1–30. Default: 7. Clamped by plan retention

statusstringoptional— Filter: active | resolved | all. Default: all

mttrly_run_diagnostic

Run AI-powered diagnostic on a server. Describe the problem and the system will investigate. 30-second cooldown per server.

server_idstringrequired— Server ID

descriptionstringrequired— Problem description, e.g. "high CPU", "nginx not responding", "disk filling up". Max 2000 characters.

mttrly_list_playbooks

List available playbooks (remediation actions) with categories and approval requirements.

server_idstringoptional— Optional server ID filter

categorystringoptional— Filter by category: monitoring, logs, services, nginx_certs, docker, scheduling, config, security, fix, maintenance, or all. Default: all

Requires Deployment Bro plan

mttrly_run_playbook

Execute a playbook on a server. Read-only playbooks run immediately. Dangerous playbooks return pending_approval — call mttrly_approve_action after explicit user confirmation.

server_idstringrequired— Server ID

playbook_idstringrequired— Playbook ID from mttrly_list_playbooks

parametersobjectoptional— Key-value pairs, e.g. {"service": "nginx"}. Check mttrly_list_playbooks for accepted parameters

mttrly_execute_command

Request execution of a shell command on a server. Always returns pending_approval. Call mttrly_approve_action after explicit user confirmation.

server_idstringrequired— Server ID

commandstringrequired— Shell command to execute

reasonstringoptional— Optional reason for execution (recorded in audit log when provided)

mttrly_get_pending_actions

List pending actions awaiting approval.

server_idstringoptional— Optional filter by server ID

mttrly_approve_action

Approve or reject a pending action. Only call after explicit user confirmation — never automatically. Blocks until execution completes (up to 60s).

action_idstringrequired— Action ID from mttrly_run_playbook, mttrly_execute_command, or mttrly_get_pending_actions

decisionstringrequired— approve = execute, reject = cancel

mttrly_get_audit_log

Get audit trail for a server — approval decisions, command executions, playbook runs, and agent fixes.

server_idstringrequired— Server ID

limitnumberoptional— Max entries, 1–200. Default: 50

sincestringoptional— ISO 8601 timestamp — only return entries after this time

Approval workflow

Destructive actions follow a two-step approval pattern:

1.Call mttrly_run_playbook or mttrly_execute_command → returns pending_approval with action_id and description.

2.Show the action details to the user and ask for confirmation.

3.Call mttrly_approve_action with the action_id and decision (approve/reject).

4.If approved, the tool blocks until execution completes (up to 60s) and returns the result.

Read-only playbooks execute immediately without approval. Check requires_approval field from mttrly_list_playbooks.

Error codes

All errors return a JSON object with code, message, and suggested_action.

PLAN_REQUIRED

Tool requires a higher plan. The response includes an upgrade URL.

→ Inform the user about the plan limitation and show the upgrade URL.

SERVER_OFFLINE

The target server agent is not connected.

→ Check if the agent is running on the server.

SERVER_NOT_FOUND

Invalid server_id.

→ Call mttrly_list_servers to see available server IDs.

DIAGNOSTIC_COOLDOWN

30-second per-server cooldown on diagnostics has not expired.

→ Wait for the cooldown period to expire before retrying.

DOCKER_NOT_AVAILABLE

Docker playbook requested but Docker is not installed on the target server.

→ Skip Docker-related playbooks or install Docker on the server.

ACTION_EXPIRED

Pending action exceeded 30-minute TTL and was automatically cancelled.

→ Re-run the original command or playbook to create a new pending action.

RATE_LIMITED

API key exceeded 60 requests per minute. Returns HTTP 429.

→ Wait and retry after the rate limit window resets (1 minute).

VALIDATION_ERROR

Request body failed validation (e.g. missing required field, description over 2000 chars).

→ Check the request parameters against the tool schema.

TIMEOUT

Request exceeded the timeout (default 60s).

→ Retry the request.

Rate limits

•Global: 60 requests per minute per API key. Exceeding returns HTTP 429 with RATE_LIMITED code. Window resets after 1 minute.

•mttrly_run_diagnostic: 30-second cooldown per server. Returns DIAGNOSTIC_COOLDOWN if called too soon.

•mttrly_approve_action: blocks up to 60 seconds waiting for execution to complete.

•Alert retention and log limits are clamped by plan (Watchdog: 7 days, Deployment Bro: 30 days).

Plan limits

Each plan has concrete resource limits enforced by the API:

Limit	Watchdog (Free)	Deployment Bro ($39/mo)	Deployment Crew ($99/mo)
Servers	1	3	9
Log lines per request	50	500	500
Alert/log retention	7 days	30 days	30 days
Scheduled checks	—	5	Unlimited

Plan access matrix

Tool	Watchdog (Free)	Deployment Bro ($39/mo)	Deployment Crew ($99/mo)
mttrly_get_capabilities	✓	✓	✓
mttrly_list_servers	✓	✓	✓
mttrly_get_server_status	✓	✓	✓
mttrly_get_alerts	✓	✓	✓
mttrly_run_diagnostic	✓	✓	✓
mttrly_list_playbooks	✓	✓	✓
mttrly_run_playbook	—	✓	✓
mttrly_execute_command	—	✓	✓
mttrly_get_pending_actions	—	✓	✓
mttrly_approve_action	—	✓	✓
mttrly_get_audit_log	—	✓	✓

* Deployment Crew has the same MCP tool access as Deployment Bro, plus: up to 9 servers, team access, and webhook integrations.