Документация

Всё что нужно для старта с mttrly.

Руководство по быстрому старту

Запусти mttrly на сервере за 2 минуты.

Шаг 1: Подключи мессенджер

Выберите мессенджер (Telegram, Slack или Discord) и подключитесь. Получите API-токен.

Шаг 2: Установи агента

Подключись к серверу по SSH и выполни команду установки. Агент — лёгкий Go-бинарник (~10MB) без зависимостей.

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

Шаг 3: Проверь подключение

Отправь /status в мессенджер. Через пару секунд увидишь метрики здоровья сервера.

Справочник по командам

Полный список доступных команд и их опций.

$ /status

Показать здоровье сервера: CPU, RAM, диск и запущенные сервисы.

Options:

-vПодробный вывод со списком процессов
-jВывод в формате JSON

Example:

/status -v

$ /logs

Просмотр логов приложения в реальном времени или поиск по истории.

Options:

<service>Имя сервиса (nginx, app и т.д.)
-n <lines>Количество строк (по умолчанию: 50)
-fСледить за логами в реальном времени
--errorsПоказать только ошибки

Example:

/logs nginx -n 100 --errors

$ /restart

Перезапустить сервис. Требует подтверждения для безопасности.

Options:

<service>Имя сервиса для перезапуска
--forceПропустить подтверждение (осторожно)

Example:

/restart nginx

$ /deploy

Подтянуть последний код и перезапустить приложение.

Options:

<app>Имя приложения
--branch <name>Git-ветка (по умолчанию: main)

Example:

/deploy myapp --branch staging

$ /run

Выполнить кастомный playbook.

Options:

<playbook>Имя playbook

Example:

/run cleanup-logs

Настройка

Настрой поведение mttrly через конфиг-файл.

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

services

Список сервисов, которыми может управлять агент

services:
  - nginx
  - myapp
  - redis

playbooks

Кастомные скрипты для запуска через /run

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

alerts

Автоматические алерты при высоком потреблении ресурсов

alerts:
  cpu_threshold: 80
  memory_threshold: 90
  disk_threshold: 85

Модель безопасности

Безопасность встроена в архитектуру mttrly.

Только исходящие соединения

Агент подключается к нашим серверам через WebSocket. Входящие порты не нужны. Файрвол остаётся закрытым.

Подтверждение опасных действий

Команды типа restart, deploy и кастомные скрипты требуют явного подтверждения кнопкой. Никаких случайных катастроф.

Ограниченные права

Агент работает от выделенного пользователя с минимальными привилегиями. Предоставляй sudo только для нужных команд.

Сквозное шифрование

Всё общение между сервером и Telegram зашифровано. Логи и чувствительные данные не хранятся.

Ротация токенов

Перегенерируй API-токен в любое время при подозрении на компрометацию. Старые токены мгновенно инвалидируются.

Решение проблем

Частые проблемы и их решения.

Агент не подключается

→Проверь, разрешены ли исходящие WebSocket-соединения (порт 443)
→Убедись, что API-токен правильный
→Проверь логи агента: journalctl -u mttrly

Команды зависают

→Возможно, сервер под высокой нагрузкой
→Проверь сетевое подключение
→Перезапусти агента: systemctl restart mttrly

Ошибки доступа

→Убедись, что пользователь mttrly имеет доступ к управляемому сервису
→Добавь sudo-права для нужных команд в /etc/sudoers.d/mttrly

MCP-сервер

Подключение mttrly к AI-ассистентам кодинга через Model Context Protocol. Endpoint: https://api.mttrly.com/mcp

Подключение

MCP-сервер mttrly использует HTTP-транспорт с аутентификацией OAuth 2.1. Добавь его в клиент:

Claude Codebash

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

OAuth-авторизация откроется в браузере автоматически.

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"

Добавь в ~/.codex/config.toml. Запусти codex mcp login mttrly для OAuth.

Аутентификация

Поддерживаются два режима аутентификации:

OAuth 2.1 (рекомендуется)

Стандартный OAuth flow с PKCE S256. JWT-токены подписаны RS256. Issuer: https://app.mttrly.com. Audience: https://api.mttrly.com/mcp. MCP-клиенты обрабатывают это автоматически — ты просто подтверждаешь вход в браузере.

API Key

Bearer-токен с префиксом mtr_. Передавай как Authorization: Bearer mtr_your_key. Доступен в дашборде.

Неавторизованные запросы возвращают 401 с заголовком WWW-Authenticate, указывающим на OAuth discovery endpoint.

Справочник инструментов

35+ инструментов организованы по уровню доступа. Всегда вызывай mttrly_get_capabilities первым, чтобы проверить план и доступные инструменты.

Доступно на всех планах

mttrly_get_capabilities

Текущий план, доступные инструменты, ограниченные инструменты и лимиты плана. Вызывай первым.

mttrly_list_servers

Список всех подключённых серверов со статусом (online/offline).

mttrly_get_server_status

Детальный статус сервера: CPU, RAM, диск и количество активных алертов.

server_idstringrequired— ID сервера из mttrly_list_servers

mttrly_get_alerts

Алерты (инциденты) сервера с фильтрацией по severity/status. Retention ограничен планом.

server_idstringrequired— ID сервера

limitnumberoptional— Макс. алертов, 1–500. По умолчанию: 20

since_daysnumberoptional— Глубина поиска в днях, 1–30. По умолчанию: 7

statusstringoptional— Фильтр: active | resolved | all. По умолчанию: all

mttrly_run_diagnostic

AI-диагностика сервера. Опиши проблему — система проведёт расследование. Кулдаун 30 секунд на сервер.

server_idstringrequired— ID сервера

descriptionstringrequired— Описание проблемы, напр. "высокий CPU", "nginx не отвечает", "диск заполняется". Макс. 2000 символов.

mttrly_list_playbooks

Список доступных плейбуков с категориями и требованиями подтверждения.

server_idstringoptional— Опциональный фильтр по серверу

categorystringoptional— Фильтр: monitoring, logs, services, nginx_certs, docker, scheduling, config, security, fix, maintenance или all. По умолчанию: all

Требуется план Deployment Bro

mttrly_run_playbook

Выполнить плейбук на сервере. Read-only плейбуки выполняются сразу. Опасные возвращают pending_approval — вызови mttrly_approve_action после подтверждения пользователя.

server_idstringrequired— ID сервера

playbook_idstringrequired— ID плейбука из mttrly_list_playbooks

parametersobjectoptional— Key-value параметры, напр. {"service": "nginx"}. Проверь mttrly_list_playbooks для списка параметров

mttrly_execute_command

Запрос на ограниченное выполнение команды на сервере. Если есть подходящий playbook, предпочитай mttrly_run_playbook. Требует подтверждения или явного investigation bypass, а выполнение записывается в audit log.

server_idstringrequired— ID сервера

commandstringrequired— Команда, запрошенная для выполнения с подтверждением

reasonstringoptional— Опциональная причина выполнения (записывается в аудит-лог, если указана)

mttrly_get_pending_actions

Список действий, ожидающих подтверждения.

server_idstringoptional— Опциональный фильтр по серверу

mttrly_approve_action

Подтвердить или отклонить pending action. Вызывай только после явного подтверждения пользователя. Блокирует до завершения выполнения (до 60с).

action_idstringrequired— ID действия из mttrly_run_playbook, mttrly_execute_command или mttrly_get_pending_actions

decisionstringrequired— approve = выполнить, reject = отменить

mttrly_get_audit_log

Аудит-трейл сервера — подтверждения действий, выполнения команд, запуски плейбуков, авто-фиксы.

server_idstringrequired— ID сервера

limitnumberoptional— Макс. записей, 1–200. По умолчанию: 50

sincestringoptional— ISO 8601 timestamp — записи после этого времени

Workflow подтверждения

Деструктивные действия следуют двухэтапному паттерну:

1.Вызови mttrly_run_playbook или mttrly_execute_command для действия, требующего подтверждения → получи action_id и описание.

2.Покажи детали действия пользователю и спроси подтверждение.

3.Вызови mttrly_approve_action с action_id и решением (approve/reject).

4.Если одобрено, инструмент блокирует до завершения выполнения (до 60с) и возвращает результат.

Read-only плейбуки выполняются сразу без подтверждения. Явный investigation bypass ограничен областью действия и временем. Проверь поле requires_approval из mttrly_list_playbooks.

Коды ошибок

Все ошибки возвращают JSON-объект с code, message и suggested_action.

PLAN_REQUIRED

Инструмент требует более высокий план. Ответ содержит URL для апгрейда.

→ Сообщи пользователю об ограничении плана и покажи ссылку на апгрейд.

SERVER_OFFLINE

Агент на сервере не подключён.

→ Проверь, запущен ли агент на сервере.

SERVER_NOT_FOUND

Неверный server_id.

→ Вызови mttrly_list_servers чтобы увидеть доступные ID серверов.

DIAGNOSTIC_COOLDOWN

30-секундный кулдаун диагностики на сервере не истёк.

→ Подожди окончания кулдауна перед повторным запросом.

DOCKER_NOT_AVAILABLE

Запрошен Docker-плейбук, но Docker не установлен на сервере.

→ Пропусти Docker-плейбуки или установи Docker на сервер.

ACTION_EXPIRED

Pending action превысил TTL 30 минут и был автоматически отменён.

→ Повтори исходную команду или плейбук для создания нового pending action.

RATE_LIMITED

API-ключ превысил лимит 60 запросов в минуту. Возвращает HTTP 429.

→ Подожди сброса окна rate limit (1 минута) и повтори.

VALIDATION_ERROR

Тело запроса не прошло валидацию (напр. пропущено обязательное поле, description свыше 2000 символов).

→ Проверь параметры запроса по схеме инструмента.

TIMEOUT

Запрос превысил таймаут (по умолчанию 60с).

→ Повтори запрос.

Лимиты

•Глобальный: 60 запросов в минуту на API-ключ. Превышение возвращает HTTP 429 с кодом RATE_LIMITED. Окно сбрасывается через 1 минуту.

•mttrly_run_diagnostic: 30-секундный кулдаун на сервер. Возвращает DIAGNOSTIC_COOLDOWN при раннем вызове.

•mttrly_approve_action: блокирует до 60 секунд, ожидая завершения выполнения.

•Retention алертов и лимиты логов ограничены планом (Watchdog: 7 дней, Deployment Bro: 30 дней).

Лимиты планов

Конкретные ограничения ресурсов по планам, контролируемые API:

Лимит	Watchdog (бесплатно)	Deployment Bro (3900₽/мес)	Deployment Crew (9900₽/мес)
Серверы	1	3	9
Строк логов за запрос	50	500	500
Retention алертов/логов	7 дней	30 дней	30 дней
Scheduled checks	—	5	Без ограничений

Матрица доступа по планам

Инструмент	Watchdog (бесплатно)	Deployment Bro (3900₽/мес)	Deployment Crew (9900₽/мес)
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 имеет тот же набор MCP-инструментов, что и Deployment Bro, плюс: до 9 серверов сейчас; командный доступ и webhook-интеграции выкатываются поэтапно.