ODIN — MCP Agent para Gerenciamento de Servidores
Syamsuddin/ODIN
IA para servidor Linux via linguagem natural, sem SSH manual
Ver no GitHubAgent MCP baseado em IA que permite gerenciar servidores Linux através de instruções em linguagem natural via Claude. Transforma comandos de texto em operações automatizadas no servidor, com camadas de segurança, detecção de erros e rollback automático.
Instalação
npx convez-ai Syamsuddin/ODIN1 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
Casos de uso
- Deploy e gerenciamento de aplicações em VPS com linguagem natural
- Detecção automática e correção de erros em tempo real
- Automação de workflows consistentes com runbook engine
- Auditoria e rollback seguro de operações destrutivas
Veredito

ODIN é um servidor MCP robusto para automação de infraestrutura Linux via Claude, com 17 ferramentas, segurança em 5 camadas e análise inteligente de erros. Excelente para times que precisam bridgear entre Claude Code (cliente) e VPS (executor) sem SSH manual ou daemons adicionais.
README
A tradução para o português deste README ainda está na fila.
Mengapa ODIN
| Tanpa ODIN | Dengan ODIN |
|---|---|
| SSH manual, ketik command satu per satu | Instruksi natural language, eksekusi otomatis |
| Lupa urutan deploy, skip langkah | Workflow konsisten via runbook engine |
| Error tak terdeteksi sampai user komplain | 22 pola error dianalisis real-time + saran perbaikan |
| Rollback panik: "commit sebelumnya apa?" | State dicatat otomatis sebelum operasi destruktif |
| Setiap sesi mulai dari nol | Memory persisten: ODIN ingat server, preferensi, instruksi |
| Risk fatigue: approve semua tanpa baca | Kartu risiko 5 tier: baca sekilas, putuskan cepat |
| Server state tak diketahui | Auto-inspect: type, stack, mode terdeteksi otomatis |
Arsitektur
LAPTOP (Claude Code CLI) SERVER (Ubuntu VPS, user: odin)
┌─────────────────────────┐ SSH stdio MCP ┌────────────────────────────────┐
│ │ ──────────────▶ │ │
│ odin_guard.py │ spawn fresh │ odin_agent.py (ODIN server) │
│ ├─ READ/WRITE classify │ per sesi │ ├─ 17 MCP tools │
│ ├─ Risk engine (5 tier)│ │ ├─ Output intelligence (23) │
│ ├─ Mode-aware tier │ │ ├─ Rollback tracking │
│ ├─ Undo hints (12 pat) │ │ ├─ Runbook engine + templates │
│ └─ Kartu risiko UI │ │ ├─ Server profiler + modes │
│ │ │ ├─ Memory persisten (JSONL) │
│ 651 baris Python │ │ ├─ Audit log + audit_tail │
│ │ │ ├─ Deploy fingerprint & drift │
│ │ │ └─ Watchdog (health://live) │
│ │ │ 2046 baris Python │
└─────────────────────────┘ └────────────────────────────────┘
Koneksi: SSH stdio — tidak perlu port tambahan, tidak perlu daemon, tidak perlu API key di server. MCP server di-spawn fresh tiap sesi Claude Code, lalu mati otomatis saat sesi berakhir.
Struktur Proyek
ODIN/
├── server/
│ ├── odin_agent.py # MCP server ODIN (2046 baris) — jalan di VPS
│ └── run.sh # Launcher: set env + exec venv python
├── client/
│ ├── odin_guard.py # Risk engine + gerbang read/write (651 baris) — jalan di laptop
│ └── update_checker.py # Cek versi terbaru dari GitHub (155 baris)
├── tests/ # 485 tests across 10 files
│ ├── test_core.py # Core functions (44 tests)
│ ├── test_guard.py # Guard classifier & risk engine (160 tests)
│ ├── test_memory.py # Memory system (58 tests)
│ ├── test_output_intelligence.py # Error patterns (48 tests)
│ ├── test_fase2_intelligence.py # Suggestions, tracking, trends (25 tests)
│ ├── test_fase3.py # Runbook & rollback (36 tests)
│ ├── test_fase3_ux.py # Audit tail, undo hints, templates (32 tests)
│ ├── test_fase4_proactive.py # Fingerprint, drift, budget, watchdog (38 tests)
│ └── test_profile_mode.py # Server profiler & mode (44 tests)
├── docs/
│ └── MEMORY_NOTES.md # Dokumentasi sistem memory
├── install.sh # Installer + server setup wizard (macOS & Linux, 857 baris)
├── install.ps1 # Installer Windows (PowerShell)
├── uninstall.sh # Uninstaller + auto-clean config (macOS & Linux)
├── uninstall.ps1 # Uninstaller Windows (PowerShell)
├── requirements.txt # Dependensi: mcp[cli]
├── CLAUDE.md # Instruksi untuk Claude Code
├── CHANGELOG.md # Riwayat perubahan
├── EXECUTIVE_SUMMARY.md # Rangkuman eksekutif
└── REVIEW_EMPAT_FAKTOR.md # Review teknis 4 dimensi
Total: 2852 baris source + 3545 baris test = 6397 baris
17 Tools MCP + 2 Resources
Eksekusi & Inspeksi
| Tool | Fungsi | Approval |
|---|---|---|
run_command | Jalankan command shell apa pun di server | READ: otomatis, WRITE: kartu risiko |
tail_log | Baca N baris terakhir file log (Laravel, Nginx, system) | Otomatis |
service_action | Kelola systemd: status, restart, reload, start, stop | READ: otomatis, WRITE: kartu risiko |
server_info | Ringkasan server: OS, disk, memory, PHP, uptime | Otomatis |
inspect_server | Full inspection: type detection, stack scan, mode derivation | Otomatis |
Deploy & Testing
| Tool | Fungsi | Approval |
|---|---|---|
laravel_deploy | Deploy Laravel satu tombol: git reset, composer, migrate, cache, FPM reload | Kartu risiko TINGGI |
run_tests | Jalankan PHPUnit/Pest test suite | Otomatis |
http_health_check | Verifikasi HTTP status (response code + body) | Otomatis |
Workflow Intelligence
| Tool | Fungsi | Approval |
|---|---|---|
runbook | Eksekusi workflow multi-langkah (maks 20 step) dengan error analysis & rollback per step | Kartu risiko (tier tertinggi) |
runbook_templates | List/ambil template runbook builtin & custom | Otomatis |
rollback_plan | Tampilkan saran undo untuk operasi destruktif terakhir | Otomatis |
session_history | Riwayat semua operasi di sesi ini (in-memory, hilang saat respawn) | Otomatis |
audit_tail | Baca audit log dengan filter (last, tool, success, since) | Otomatis |
Memory Persisten
| Tool | Fungsi | Approval |
|---|---|---|
memory_write | Simpan fakta/instruksi yang bertahan lintas sesi | Kartu risiko RENDAH |
memory_recall | Cari memory berdasarkan namespace/tag/keyword | Otomatis |
memory_forget | Hapus memory entry (tombstone) | Kartu risiko RENDAH |
memory_digest | Tampilkan seluruh memory aktif (sama dengan yang di-inject saat startup) | Otomatis |
MCP Resources
| Resource | Fungsi |
|---|---|
memory://{ns} | Baca memory per namespace (read-only, tanpa tool call) |
health://live | Watchdog: cek disk, memory, load, service status — untuk polling via /loop |
Model Keamanan — 4 Lapis Defense-in-Depth
Lapis 1: READ/WRITE Classifier (client — odin_guard.py)
23 sub-command classifier (git, docker, mysql, npm, curl, ufw, nginx, ...)
READ → auto-approve WRITE → lanjut ke lapis 2
↓
Lapis 2: Risk Engine + Kartu Risiko (client)
5 tier: AMAN → RENDAH → SEDANG → TINGGI → KRITIS
26 aturan shell + DB risk assessor
User membaca kartu, memutuskan approve/reject
↓
Lapis 3: Hard-block Katastrofik (server — _DANGER_RE)
rm -rf /, mkfs, dd of=/dev, fork bomb, shutdown, DROP DATABASE
Ditolak kecuali allow_dangerous=True (double brake)
↓
Lapis 4: OS-level (server)
User odin dengan sudoers terbatas
Batas keamanan sesungguhnya
Contoh Kartu Risiko
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟠 RISIKO: TINGGI
Cmd : git reset --hard origin/main
Dir : /var/www/simuru
Aksi : Buang semua perubahan lokal
Efek : Perubahan belum commit hilang permanen
Saran : Stash dulu jika ada kerja penting
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Perlindungan Tambahan
- Command substitution (
$()dan backtick) di-detect dan di-force ke "ask" — mencegah bypass via subshell - Secret detection di memory: password, token, private key, JWT, AWS key ditolak masuk JSONL
- Memory di luar webroot: tidak bisa diakses via web, tidak ikut
git reset --hardsaat deploy - Audit trail: setiap eksekusi tercatat append-only — untuk forensik pasca-insiden
- Production mode: tier risiko naik 1 level + warning
MODE PRODUCTIONdi kartu risiko
Kecerdasan Bawaan
Output Intelligence (22 Pola Error)
Setiap output command dianalisis terhadap 22 pola error — dari spesifik ke generik:
| Kategori | Pola yang Dideteksi |
|---|---|
| Database | SQLSTATE (auth, connection, constraint, general), deadlock, max connections |
| PHP/Laravel | Fatal error, OOM, timeout, class not found, composer lock |
| System | Disk full, OOM kill, permission denied, command not found |
| Tools | Nginx config error, SSL expired, npm build failure |
Hasil analisis dilampirkan otomatis:
{"error_type": "db_conn", "hints": ["Cek service MySQL, pastikan berjalan..."]}
Rollback Tracking
Sebelum command destruktif (git reset, artisan migrate, service restart):
_capture_pre_state()— tangkap git HEAD, migration status, service status- Eksekusi command
_suggest_rollback()— sarankan undo command spesifik berdasarkan state yang ditangkap
Runbook Engine
Claude menyusun langkah berdasarkan konteks — ODIN mengeksekusi berurutan (maks 20 step):
- Error analysis per langkah
- Rollback tracking per langkah
- Berhenti otomatis pada kegagalan (kecuali
continue_on_fail=True) - Laporan terstruktur: executed/total/skipped/failed
Pre-flight Checks
Sebelum laravel_deploy, otomatis cek: disk (blokir jika >= 95%), git dirty files, commit saat ini, versi PHP. Blocker = deploy dibatalkan dengan laporan.
Server Profiler & Mode Operasi
Pada startup, ODIN menjalankan inspeksi penuh:
- Base inspection — OS, kernel, uptime, disk, memory, firewall, fail2ban, SSH, cron, users
- Type detection — klasifikasi:
web-app,database,container,general - Stack inspection — per-type: web (nginx/PHP/FPM/composer/DB/Redis/SSL), database (MySQL/PG/Mongo), container (Docker/compose)
- App inspection — .env, vendor, framework detection, git state
- Mode derivation — otomatis:
setup/deploy/production
Mode enforcement (dual layer):
- Server (
_mode_gate): production mode memblokirlaravel_deploydan package-install commands - Guard (
_shift_tier): production mode menaikkan tier risiko +1 level
Memory Persisten
3 namespace: server (fakta infrastruktur), instruction (arahan user), profile (identitas).
- Append-only JSONL + fold (last-write-wins, tombstone, TTL)
- Auto-inject ke konteks saat spawn — setiap sesi baru langsung "ingat"
- Compaction otomatis saat melebihi
MEMORY_MAX_ENTRIES - Storage di luar webroot dan
PROJECT_ROOT— aman dari deploy & run_command
Audit Log
Setiap eksekusi tool dicatat ke audit.jsonl: timestamp, tool, summary, success, exit_code, durasi, mode. Append-only, tidak pernah dihapus.
Instalasi
Installer Otomatis (Rekomendasi)
curl -fsSL https://raw.githubusercontent.com/Syamsuddin/ODIN/main/install.sh | bash
Installer terintegrasi menangani laptop + server dalam satu langkah:
Tahap 1 — Laptop (otomatis)
- Clone repo, buat venv, install
mcp[cli], setup guard hook, buat perintahodin-update - Wizard interaktif: 3 pertanyaan (SSH host, path
run.sh, scope guard) → config ditulis otomatis ke~/.claude.jsondansettings.json - Tes koneksi SSH ke server
Tahap 2 — Server via SSH (opsional, ditawarkan setelah laptop selesai)
- Cek Python 3 dan
python3-venvdi server - Buat user
odinjika belum ada - Buat venv + install
mcp[cli] - Upload
odin_agent.pydan generaterun.shdengan config yang benar - Set password user
odin - Verifikasi semua file terpasang
SSH ControlMaster digunakan agar hanya satu kali autentikasi selama setup.
Windows: irm https://raw.githubusercontent.com/Syamsuddin/ODIN/main/install.ps1 | iex (laptop only, server setup manual)
Manual
Jika lebih memilih setup manual (atau installer gagal):
1. Di Laptop (client)
git clone https://github.com/Syamsuddin/ODIN.git ~/.odin
cd ~/.odin
python3 -m venv .venv && .venv/bin/pip install "mcp[cli]"
2. Di Server (VPS)
# Buat user odin (sebagai root)
useradd -m -s /bin/bash odin
passwd odin
# Setup venv + install dependensi
python3 -m venv /home/odin/.venv
/home/odin/.venv/bin/pip install "mcp[cli]"
# Salin file dari laptop
scp ~/.odin/server/odin_agent.py <host>:/home/odin/
scp ~/.odin/server/run.sh <host>:/home/odin/
# Set permissions
chmod 600 /home/odin/odin_agent.py
chmod 755 /home/odin/run.sh
chown -R odin:odin /home/odin/
3. Konfigurasi Claude Code
MCP server (~/.claude.json):
{
"mcpServers": {
"odin": {
"type": "stdio",
"command": "ssh",
"args": ["your-server-alias", "/home/odin/run.sh"]
}
}
}
Guard hook (.claude/settings.json):
{
"permissions": {
"allow": [
"mcp__odin__server_info",
"mcp__odin__tail_log",
"mcp__odin__http_health_check",
"mcp__odin__memory_recall",
"mcp__odin__memory_digest",
"mcp__odin__session_history",
"mcp__odin__rollback_plan",
"mcp__odin__inspect_server"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__odin__(run_command|service_action|laravel_deploy|run_tests|runbook|inspect_server|memory_write|memory_forget)",
"hooks": [
{
"type": "command",
"command": "python3 '<path-to>/odin_guard.py'",
"timeout": 10
}
]
}
]
}
}
Update
odin-update
Uninstall
curl -fsSL https://raw.githubusercontent.com/Syamsuddin/ODIN/main/uninstall.sh | bash
Uninstaller menghapus direktori ODIN, membersihkan config mcpServers.odin dan hook mcp__odin__ dari ~/.claude.json dan semua settings.json secara otomatis, serta menawarkan cleanup server via SSH.
Windows: irm https://raw.githubusercontent.com/Syamsuddin/ODIN/main/uninstall.ps1 | iex
Cara Kerja End-to-End
User: "Cek kenapa website error 500, perbaiki kalau bisa"
Claude Code (otak):
1. server_info → "Ubuntu 24.04, disk 42%, PHP 8.3"
2. http_health_check → "HTTP 500"
3. tail_log laravel.log → "SQLSTATE[HY000] [2002] Connection refused"
4. ODIN analisis → {error_type: "db_conn", hints: ["Cek service MySQL..."]}
5. service_action mysql → "inactive (dead)" ← DITEMUKAN
6. service_action restart mysql → [KARTU RISIKO SEDANG → user approve] → "active"
7. http_health_check → "HTTP 200" ← SELESAI
User membaca laporan: "MySQL mati, sudah di-restart, website kembali normal."
Total waktu: < 2 menit. Intervensi user: 1x approve restart MySQL.
Environment Variables
| Variable | Default | Keterangan |
|---|---|---|
DEPLOY_MODE | local | local atau ssh |
SSH_TARGET | — | user@host (wajib jika mode ssh) |
SSH_PORT | 22 | Port SSH |
SSH_KEY | — | Path private key (opsional) |
PROJECT_ROOT | cwd | Root aplikasi di server |
LOCK_CWD_TO_PROJECT | 0 | 1 = kunci cwd ke PROJECT_ROOT |
ALLOWED_LOG_DIRS | /var/log,/var/www,... | Folder yang boleh dibaca tail_log |
DEFAULT_TIMEOUT | 180 | Timeout default (detik) |
MAX_TIMEOUT | 900 | Timeout maksimum (detik) |
OUTPUT_LIMIT | 20000 | Potong output panjang (karakter) |
AGENT_LOG_LEVEL | INFO | Level log |
MEMORY_DIR | /home/odin/memory | Folder simpanan memory |
MEMORY_MAX_TEXT | 4000 | Panjang maks teks satu entry |
MEMORY_MAX_ENTRIES | 2000 | Ambang compaction |
AUDIT_ENABLED | 1 | 0 = matikan audit log |
ODIN_SKIP_INSPECT | 0 | 1 = skip startup inspection (untuk testing) |
Testing
python3 -m pytest tests/ -v # full test suite (80 tests)
python3 -m py_compile server/odin_agent.py
python3 -m py_compile client/odin_guard.py
Stack yang Didukung
Dirancang untuk dan diuji dengan:
- OS: Ubuntu Linux (VPS)
- Web: Laravel / PHP 8.x
- Database: MySQL / MariaDB
- Web server: Nginx
- Process: systemd, PHP-FPM
- Build: Composer, NPM
- VCS: Git
Auto-detect juga mendukung: PostgreSQL, MongoDB, Docker, Apache, Redis, Supervisor, Let's Encrypt SSL.
run_command adalah primitif serbaguna — ODIN bisa mengeksekusi command apa pun yang tersedia di server, tidak terbatas stack di atas.
Angka-Angka Kunci
| Metrik | Nilai |
|---|---|
| Total kode | 2852 baris Python (server 2046 + guard 651 + updater 155) |
| Total test | 3545 baris (485 automated tests, 10 files) |
| Dependensi runtime | 1 (mcp[cli]) |
| MCP tools | 17 |
| MCP resources | 2 (memory://{ns}, health://live) |
| Error patterns | 23 (18 with suggested_commands) |
| Risk rules | 26 shell + DB assessor |
| Undo hint patterns | 12 |
| Runbook templates | 4 builtin + custom |
| READ sub-classifiers | 23 (git, docker, mysql, npm, curl, ufw, nginx, ...) |
| Risk tiers | 5 (AMAN / RENDAH / SEDANG / TINGGI / KRITIS) |
| Operation modes | 3 (setup / deploy / production) |
| Security layers | 4 (classifier → risk engine → hard-block → OS) |
| Memory namespaces | 3 (server / instruction / profile) |
| Framework | Tidak ada — pure Python + FastMCP |
| Overhead server | 0 (spawn-per-session, tidak ada daemon) |
Keamanan
Batas sebenarnya = hak OS user odin + sudoers. Hook + _DANGER_RE = jaring pengaman, bukan sandbox. Keputusan akhir selalu di operator (konfirmasi WRITE).
Filosofi: READ auto-approve, WRITE wajib konfirmasi, katastrofik double-brake. Guard lebih ketat dari server (by design).
Lisensi & Versi
Versi aktif: 1.3.0 — tersimpan di __version__ pada kedua file Python.
Lihat CHANGELOG.md untuk riwayat perubahan lengkap.
ODIN v1.3 — ringan, cerdas, aman. Satu file di server, satu file di laptop, otak Claude.