convez.ai
SkillDevOps & InfraestruturaIntermediário
vefmvai

Sysadmin Agent para Claude Code

vefmvai/sysadmin

Seu sysadmin pessoal em IA — automação de servidor em linguagem natural

Ver no GitHub
InicialPluginScore · de 0 a 100

Agente IA que automatiza rotinas de administração de servidores — configuração, segurança, backups, monitoramento e deploy. Funciona em linguagem natural: você escreve "verifica o servidor" e o agente executa a sequência completa, explicando cada passo e pedindo confirmação antes de ações críticas.

Instalação

$npx convez-ai vefmvai/sysadmin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
11
Acompanhando
0
Saúde
71%
Último commit
há 1 mês
Versão
v2.3.0
Issues abertas
16
Contribuidores
1

Casos de uso

  • Automatizar setup, segurança e monitoramento de servidores sem ser especialista
  • Gerenciar backups, deploys e investigação de problemas via conversa natural
  • Integrar rotinas DevOps em projetos desenvolvidos com Claude Code

Veredito

Ferramenta madura e bem documentada para quem precisa gerenciar infraestrutura via IA sem overhead de contratação. Excelente para equipes pequenas e empreendedores técnicos que usam Claude Code; requer Linux/macOS/Windows com git e jq.

README

A tradução para o português deste README ainda está na fila.

Sysadmin Agent — твой персональный сисадмин в чате

Готовый агент для Claude Code, который берёт на себя серверную рутину: настройку, безопасность, бэкапы, мониторинг, деплой, расследования. Ты пишешь нормальными фразами вроде «проверь сервер» или «настрой бэкапы» — агент сам выбирает нужную процедуру и выполняет её, объясняя каждый шаг и не делая ничего опасного без твоего подтверждения.

Для кого. Для людей, которые создают IT-продукты с помощью ИИ (вайбкодеров), имеют один-два собственных сервера и не хотят тратить месяцы на изучение сисадмин-профессии или нанимать фрилансера за деньги.

Открытый продукт. Бери, клонируй, настраивай под свой проект — всё открыто, ничего не скрыто за облачной подпиской.


Установка — одна команда в Claude Code

Открой Claude Code в любой папке и напиши:

Установи агента sysadmin из репо https://github.com/vefmvai/sysadmin по инструкции в INSTALL.md.

Claude всё сделает сам:

  1. Клонирует репо себе на машину (спросит куда).
  2. Создаст рядом папку infra/ для твоих данных (карта серверов, ADR, knowledge).
  3. Создаст «bridge»-файл, чтобы @sysadmin работал из любого проекта.
  4. Запустит интервью /sysadmin-init — 6 вопросов про твой проект (язык, менеджер паролей, сервер, мониторинг, бэкапы). На выходе — два твоих личных конфига: agent-config.json (мозг агента, в sysadmin/) и infra-config.json (карта инфры, в папке infra/).
  5. Опционально предложит /sysadmin-meet — ~20-минутное знакомство с агентом (рекомендую если впервые видишь).

После этого открой папку sysadmin/ в Claude Code — в терминале cd sysadmin && claude, либо открой её в IDE-расширении / desktop-приложении — и сразу пиши обычными фразами:

привет, познакомься с моим сервером

Ты уже говоришь с сисадмином — отдельную команду-вызов запоминать не нужно: персона загружается из CLAUDE.md при открытии папки (вход 2.0, ADR-0015). Агент сам поймёт, что делать, и сам выберет нужный скилл.

Работаешь из другого проекта и хочешь позвать сисадмина оттуда? Два пути: подключи папку агента через /add-dir <путь-к-sysadmin>, либо вызови разово @sysadmin <запрос> — для этого и создаётся bridge-файл (шаг 3).

Системные требования: macOS / Linux / Windows · git · jq · Claude Code.

Обновления. Агент сам раз в сутки проверит новые версии и предложит обновиться. Или скажи в любой момент «обнови sysadmin» — он подтянет свежий релизный тег (git fetch + переключение на тег), покажет changelog и попросит подтверждение перед применением. Что сделать руками при переходе между версиями — UPGRADE.md.

Удаление. rm -rf <папка-sysadmin> ~/.claude/agents/sysadmin.md. Папка infra/ (твои данные) останется — её удалишь руками если нужно.


Что внутри

Агент-персона

Ядро персоны живёт в CLAUDE.md репозитория (≈390 строк; загружается при открытии папки — вход 2.0, ADR-0015) + 9 references-документов в .claude/agents/references/ — это «мозг» агента: ценности, конституция (что нельзя нарушать ни при каких обстоятельствах), характер, протоколы работы, три зоны безопасности, ритуал памяти, реакции на VPN-сценарии. Файл .claude/agents/sysadmin.md остаётся тонкой заглушкой-указателем (для @sysadmin из чужих папок). Всё открыто и читаемо — никакого чёрного ящика. Размер ядра под бюджетом (≤ 42 КБ, wc -c, проверяется pre-commit — ADR-0016; поднять бюджет можно только осознанным ADR).

22 готовых скилла

Каждый скилл — это отдельная процедура для типовой задачи. Агент сам выбирает нужный скилл по твоей фразе.

ГруппаСкиллыКогда нужно
Знакомство и настройка/sysadmin-meet, /sysadmin-initПервый раз: знакомство → настройка под проект
Настройка с нуля/bootstrap-new-server, /setup-secrets-vault, /setup-backups, /install-monitoring-stackПосле покупки нового VPS
Сеть и обход блокировок/setup-vpn-panel, /extract-subscription-servers, /configure-vpn-routing, /setup-server-proxy, /generate-client-config, /refresh-vpn-knowledgeСвой VPN-узел, извлечение серверов из закрытой (зашифрованной/HWID-locked) подписки, маршрутизация через подписку/свой загр.VPS, серверный прокси для программ, vless-ссылки и QR для устройств, актуализация knowledge раз в месяц (блокировки меняются)
Текущая работа/health-check, /inventory-scan, /deploy-service, /restore-from-backupРегулярно — утренний обход, обновления, диагностика, восстановление из бэкапа и плановый restore-тест
Безопасность/audit-security, /rotate-secretsРаз в квартал + при подозрении на проблему
Спецоперации/cleanup-existing-server, /migrate-server-to-serverУнаследованный хаос или переезд на другой провайдер

Подробное описание каждого — в /sysadmin-meet (часть 3) или в .claude/skills/<имя>/SKILL.md.

Честно о глубине: где специализирован, где операционно компетентен

Чтобы не продавать «эксперта во всём» — где какая глубина на самом деле:

  • Специализация (глубокая, с отдельной базой знаний): VPN и обход блокировок РФ-2026. Доменная база .claude/knowledge/networking/ (3 слоя по TTL, ежемесячная актуализация через /refresh-vpn-knowledge), 6 профильных скиллов, рефлексы под TSPU / 3X-UI / sing-box. Это то, ради чего агент создавался, и где он сильнее всего.
  • Операционная компетентность (надёжные процедуры, без отдельной базы знаний): базовая настройка VPS, Docker/compose, бэкапы (restic + проверенный restore), мониторинг, секреты, аудит безопасности, деплой, миграция. Здесь агент закрывает большую часть рутины одного оператора готовыми скиллами и общими SRE-навыками — но это не узкоспециализированный тюнинг.
  • Базовый уровень (через скиллы + общая эрудиция, не глубокий тюнинг): БД и nginx. Диагностика, дампы, типовые конфиги — да; тонкая оптимизация запросов PostgreSQL или сложные nginx-сценарии под нагрузку — нет: тут агент честно скажет «это за моим профилем, нужен профильный специалист», а не сымитирует экспертизу.

Если задача за пределами — агент не блефует: говорит прямо и, если она повторяющаяся, предлагает оформить её в новый скилл (режим разработки мозга — /dev).

Inventory — паспорт твоей инфраструктуры

Папка infra/inventory/ хранит актуальное состояние сервера: контейнеры, домены, базы данных, сети, тома, cron-задачи, автоматизации, TLS-сертификаты + до 5 mermaid-диаграмм (общая топология, Docker-сети, маршрутизация доменов, VPN-архитектура, карта автоматизаций). Это не статичная документация — агент сам обновляет её через /inventory-scan и при любом архитектурном изменении на сервере.

Inventory живёт в твоей приватной папке infra/, не в этом публичном репо. У каждого оператора своя инфраструктура и свои данные. Связь между публичным мозгом (этот репо) и твоей infra/ — через реестр проектов projects[] в agent-config.json (см. ниже): каждый проект указывает на свою папку инфры через infra_root.

Два конфига — мозг агента и карта инфры (ADR-0013)

Настройка живёт в двух файлах с разными ролями:

  • agent-config.json — мозг агента. Живёт в sysadmin/ (дом агента). Описывает самого агента: имя оператора, язык, менеджер паролей, реестр проектов (projects[] — какие у тебя есть инфраструктуры и где каждая живёт) и какой проект активен по умолчанию (default_project).
  • infra-config.json — карта инфры. Живёт в твоей папке infra/ (рядом с inventory/). Описывает конкретный сервер: какие подсистемы включены (мониторинг, бэкапы, Telegram), какие серверы, секция VPN-блока, опциональное оглавление map.

Оба создаются через /sysadmin-init (он же мигрирует старый единый sysadmin-config.json, если он у тебя остался). Потом скиллы читают их перед работой.

В этом репо лежат только публичные шаблоны и JSON-схемы для валидации: agent-config.example.json + agent-config.schema.json и infra-config.example.json + infra-config.schema.json.


Принципы работы

Три зоны безопасности

Каждое действие на сервере агент классифицирует по одной из трёх категорий:

  • 🟢 Зелёная — диагностика. Что только смотрит, ничего не меняет (логи, состояние контейнеров, замер ресурсов). Делает самостоятельно, без вопросов.
  • 🟡 Жёлтая — изменения с подтверждением. Что меняет, но обратимо (запуск сервиса, правка конфига). Брифинг из 6 пунктов → пауза → твоё «ок» → выполнение.
  • 🔴 Красная — необратимые операции. Что может уничтожить данные навсегда (удаление БД, контейнера с volume). Четырёхшаговая процедура с дословным type-to-confirm. Защита от случайностей.

Подробнее — в /sysadmin-meet (часть 5) или в персоне (раздел 6 Trust Zones).

Что агент НЕ делает

  • Не пишет твоё приложение (код продукта — твой).
  • Не делает бизнес-логику.
  • Не работает с серверами в обход своих правил даже под давлением.
  • Не делает ничего самовольно, что не входит в текущую задачу.
  • Не заменяет твою голову — финальные решения за тобой.

Карта файлов проекта

sysadmin/                          ← публичный репо (этот). Только мозг агента.
├── CLAUDE.md                      ← ★ ЯДРО ПЕРСОНЫ (вход 2.0: открыл папку → ты сисадмин, ADR-0015)
├── .claude/
│   ├── agents/
│   │   ├── sysadmin.md            ← тонкая заглушка-указатель на CLAUDE.md (для @sysadmin из чужих папок)
│   │   └── references/            ← 9 references (trust-zones, cold-start, vpn-reflexes, ...)
│   ├── knowledge/                 ← общие доменные знания (ADR-0003)
│   │   └── networking/            ← VPN-домен в 3 слоях (ADR-0006)
│   │       ├── _live/             ← фронт борьбы по странам (RU/CN/IR/BY) + timeline, TTL 14 дней
│   │       ├── _reference/        ← протоколы/панель/клиенты/транспорты/fronting, TTL 60 дней
│   │       └── _meta/             ← источники, глоссарий, конфликты, TTL 365 дней
│   └── skills/                    ← 22 операционных скилла + dev + retro (конструкторы мозга)
│       ├── dev/                   ← /dev: правка самого агента (персона/скиллы/ADR/knowledge)
│       ├── retro/                 ← /retro: пострефлексия сессии — разбор диалога, находки → backlog/ADR
│       ├── sysadmin-meet/         ← знакомство (запускай первым)
│       ├── sysadmin-init/         ← настройка конфига
│       ├── bootstrap-new-server/
│       ├── setup-secrets-vault/
│       ├── setup-backups/
│       ├── install-monitoring-stack/
│       ├── setup-vpn-panel/       ← установка 3X-UI
│       ├── extract-subscription-servers/ ← сервера из закрытой (зашифрованной/HWID) подписки
│       ├── configure-vpn-routing/ ← маршрутизация: подписка или свой загр.VPS
│       ├── finalize-vpn-routing/  ← доктор для застрявшей VPN-настройки
│       ├── setup-server-proxy/    ← прокси для программ на сервере
│       ├── generate-client-config/← vless/sing-box/QR для устройств
│       ├── refresh-vpn-knowledge/ ← актуализация VPN-knowledge раз в месяц
│       ├── _lib/                  ← общие helper-скрипты (find-config, check-knowledge-freshness)
│       ├── health-check/
│       ├── inventory-scan/
│       ├── deploy-service/
│       ├── audit-security/
│       ├── rotate-secrets/
│       ├── restore-from-backup/   ← restore из restic + плановый restore-тест
│       ├── cleanup-existing-server/
│       └── migrate-server-to-server/
│
├── decisions/                     ← ADR-канон + 16 архитектурных решений
│   ├── 0000-template.md
│   ├── 0001-skill-canon.md
│   ├── 0002-persona-canon.md
│   ├── 0003-knowledge-architecture.md
│   ├── 0004-evals-format.md
│   ├── 0005-vpn-architecture.md
│   ├── 0006-vpn-knowledge-layers.md
│   ├── 0007-happ-default-client.md
│   ├── 0008-infra-path-resolution.md
│   ├── 0009-snapshot-stderr-separation.md
│   ├── 0010-hwid-locked-subscriptions.md
│   ├── 0011-balancer-single-country.md
│   ├── 0012-bump-persona-core-cap-460.md
│   ├── 0013-config-split-brain-vs-infra.md   ← расщепление конфига: мозг + карта
│   ├── 0014-red-zone-loss-line-anti-copypaste.md   ← барьер необратимых операций
│   ├── 0015-persona-in-claude-md-entry-2.0.md   ← персона → CLAUDE.md (вход 2.0)
│   └── 0016-brain-budget-kb-anti-ratchet.md   ← бюджет ядра в КБ + анти-храповик
│
├── agent-config.json              ← твой личный конфиг МОЗГА (оператор, проекты; в .gitignore)
├── agent-config.example.json      ← публичный шаблон конфига мозга
├── agent-config.schema.json       ← JSON Schema конфига мозга
├── infra-config.example.json      ← публичный шаблон конфига карты инфры
├── infra-config.schema.json       ← JSON Schema конфига карты инфры
│
├── README.md                      ← этот файл (для человека)
├── INSTALL.md                     ← инструкция установки (для Claude Code)
├── UPGRADE.md                     ← обновление мозга: механизм и переходы версий
├── VERSION                        ← текущая версия мозга (2.2.1)
├── CONTRIBUTING.md                ← как сообщить о баге или предложить улучшение
└── LICENSE                        ← лицензия

infra/                             ← ТВОЯ ПРИВАТНАЯ папка (создаст установка через INSTALL.md)
├── infra-config.json              ← карта инфры: серверы, мониторинг, бэкапы, vpn (заполнит /sysadmin-init)
├── inventory/                     ← карта твоей реальной инфраструктуры
│   ├── README.md                  ← заполняется через /inventory-scan
│   ├── topology.md
│   ├── diagrams/                  ← до 5 mermaid-диаграмм инфры (см. ADR-0002 + правило §3.2)
│   │   ├── topology.mmd
│   │   ├── services-network.mmd
│   │   ├── domains-routing.mmd
│   │   ├── vpn-architecture.mmd   ← только при vpn.enabled
│   │   └── automations.mmd        ← только при наличии автоматизаций
│   ├── hosts/<server>/            ← один сервер = одна папка
│   │   ├── server.md
│   │   ├── services.md
│   │   ├── databases.md
│   │   ├── domains.md
│   │   ├── networks.md
│   │   ├── volumes.md
│   │   ├── cron.md
│   │   ├── host-scripts.md
│   │   └── automations.md         ← сводная витрина «что работает само»
│   └── shared/
│       └── access.md              ← реестр секретов (только индекс, не значения)
│
├── decisions/                     ← твои ADR (по шаблону 0000-template.md)
├── incidents/                     ← постмортемы инцидентов
├── knowledge/                     ← lessons-learned, operator-profile, working-patterns
└── runbooks/                      ← пошаговые процедуры под твою инфру

Две папки рядом, два независимых git-репо. Публичный sysadmin/ — мозг агента, одинаковый у всех, кто его берёт. Приватный infra/ — твои реальные данные, которые публиковать нельзя. Связь — через реестр projects[] в agent-config.json (мозг): каждый проект указывает на свою папку инфры через infra_root.


Требования

  • Claude Code (как установить)
  • Git
  • bash — единственное, что нужно обеспечить тебе самому:
    • macOS / Linux — bash уже встроен, ничего делать не надо.
    • Windows — поставь Git for Windows (он даёт Git Bash; без него Claude Code работает через PowerShell и скиллы агента не запускаются): winget install --id Git.Git -e, затем перезапусти сессию Claude Code.
  • jq — агент ставит его сам. При первом запуске /sysadmin-init проверяет jq и, если его нет, доустанавливает: сначала через твой пакетный менеджер (brew/apt/dnf/winget/choco/…), а если менеджера нет — просто скачивает официальный бинарник jq под твою ОС. В конце настройки агент сам тестирует, что всё работает, и честно скажет, если что-то не вышло.
  • SSH-доступ к твоему серверу
  • VPS (виртуальный сервер) — любой провайдер по выбору. Минимум — 2 ГБ RAM если планируешь использовать мониторинг-стек.

Менеджер секретов по ОС: macOS — Keychain (рекомендуется), Linux — pass / KeePassXC / Bitwarden, Windows — Bitwarden / KeePassXC. Выбор делается в /sysadmin-init.


Безопасность

  • Секреты НИКОГДА не лежат в репозитории. Только индекс — в файле inventory/shared/access.md твоей приватной папки infra/ (создаст /sysadmin-init). Сами значения — в выбранном менеджере паролей.
  • Pre-commit hook через gitleaks (рекомендуется настроить — см. CONTRIBUTING.md). Ловит случайные коммиты секретов.
  • Оба конфига — в .gitignore: agent-config.json (мозг, в sysadmin/) и infra-config.json (карта, в infra/). Личные данные не попадают в репозитории; публикуются только обезличенные *.example.json + *.schema.json.
  • Конституция агента запрещает выдумывать данные, обходить процедуры, делать деструктивы без явного подтверждения.

Углубление

Когда захочешь разобраться глубже — карта в /sysadmin-meet (часть 7). Краткий порядок чтения:

  1. CLAUDE.md — ядро персоны и главный документ: ценности, конституция, характер, три зоны, протоколы (вход 2.0: открыл папку → ты сисадмин). Обязательно в первую неделю.
  2. .claude/agents/references/*.md — полные протоколы персоны (читаются по триггеру из ядра)
  3. .claude/skills/<имя>/SKILL.md — конкретный скилл, который тебя интересует
  4. decisions/0000-template.md — шаблон ADR. Когда будешь принимать своё архитектурное решение — копируй шаблон в свою infra/decisions/ и заполняй.

Лицензия

Свободно для образовательных и личных проектов.

Ver o original no GitHub

Bom para

Relacionados