Documentation

Setup, commands, config. Everything in one place.

Quick Start

Three steps: create an account, install the required agent, and run the first check.

Step 1: Create your account

Sign up with email. Telegram can be connected later for mobile alerts and approvals; Slack and Discord are limited beta channels for selected customers.

Step 2: Install the agent

Open Add server in your account, then copy the token-specific installer shown in onboarding. The command is unique to that server connection and installs the required systemd agent.

app.mttrly.com → Add server → Copy install command

Step 3: Check status

Open the dashboard or Telegram and run /healthcheck. In an MCP-enabled IDE, call mttrly_get_server_status. If the agent returns current CPU, memory, and disk evidence, the connection is ready.

Commands

A current starter set of messenger commands. Run /help in the connected channel for the full command catalog available to your account.

$ /healthcheck

Run the overall server health check, including load, memory, disk, and configured HTTP evidence.

Example:

/healthcheck

$ /status

Show detailed systemd status for one service.

Options:

<service>Exact systemd service name

Example:

/status nginx

$ /logs

Read a bounded snapshot of journal logs for one service.

Options:

<service>Exact systemd service name

Example:

/logs nginx

$ /restart

Request a systemd service restart. This is an approval-required action; there is no confirmation-bypass flag.

Options:

<service>Exact allowlisted systemd service name

Example:

/restart nginx

$ /setup_deploy

Create the deploy profile that defines the existing app path, build/restart steps, and health check. After setup, request a deploy in natural language.

Example:

/setup_deploy

Configuration

Hosted settings and deploy profiles are managed through your account and guided chat flows. The agent does not use a general /etc/mttrly/config.yaml file.

Configuration model: Hosted account settings plus generated agent files under /etc/mttrly

Hosted server settings

Add and select servers in the dashboard or connected messenger. The installer writes server-specific identity files; do not copy tokens between servers.

app.mttrly.com → Servers → Add server

/etc/mttrly/allowed-services.conf

The systemd wrappers permit state-changing service actions only for exact unit names present in this allowlist. Use one unit name per line.

nginx
myapp.service
redis-server

Deploy profile

Configure an existing application with /setup_deploy and edit it with /deploy_config. Profiles are hosted configuration, not custom YAML playbooks on the agent.

/setup_deploy
/deploy_config

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 initiates an encrypted outbound connection. No new inbound mttrly control port is required; existing firewall and application-port rules stay under your control.

Confirmation before anything scary

Approval-required restarts, deploys, and scripts normally create a pending action. A user-authorized, bounded mttrly_execute_command Investigation or narrowly configured preauthorization are explicit exceptions; both remain audited.

Minimal permissions

The agent runs as a dedicated service user and uses scoped wrappers for privileged operations. Exact privileges depend on the capabilities enabled for that server.

Encrypted transport and explicit data boundary

The agent uses encrypted transport. Relevant diagnostic excerpts and operational records may be processed or stored to provide diagnosis and audit. Avoid putting secrets in prompts or logs; see the Privacy Policy for the current data boundary.

Token rotation

If you suspect a token leaked, rotate it from the authenticated account flow. The previous credential is invalidated as part of the rotation.

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 Desktopconnector

Settings -> Connectors -> Add custom connector -> https://api.mttrly.com/mcp

Use the Connectors UI in Claude Desktop or Claude.ai.

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

40 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_quick_triage

Run the Watchdog-safe deterministic first-pass triage for a server. This uses simple symptom matching rather than an AI investigation.

server_idstringrequired— Server ID

symptomstringoptional— Optional symptom hint, max 500 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_diagnostic

Run a non-destructive diagnostic investigation on a server. Deployment Bro or higher is required; a 30-second cooldown applies per server.

server_idstringrequired— Server ID

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

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 a scoped command execution action on a server. Prefer mttrly_run_playbook when a playbook exists. Requires approval or an explicit investigation bypass, and execution is recorded in the audit log.

server_idstringrequired— Server ID

commandstringrequired— Command requested for approval-gated execution

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

Approval-required actions normally follow a two-step approval pattern:

1.Call mttrly_run_playbook or mttrly_execute_command for an approval-gated action → receive 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. A user-authorized Investigation bypass applies only to mttrly_execute_command and remains scoped, time-limited, action-limited, and audited. Check requires_approval 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-query look-back is clamped by plan (Watchdog: 7 days; Deployment Bro and Crew: 30 days). This query limit is not a storage-retention promise.

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 query look-back	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_quick_triage	✓	✓	✓
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 now; team access and webhook integrations are rolling out in stages.

Ready to test the docs on a real server?

Create an account with email. Onboarding shows the token-specific command for the required outbound agent.

Create account with email Scan a public URL first