{"id":51492013,"url":"https://github.com/kazetama/agents-server","last_synced_at":"2026-07-07T12:02:03.004Z","repository":{"id":368327004,"uuid":"1268972641","full_name":"Kazetama/agents-server","owner":"Kazetama","description":"Server backend untuk manajemen, orkestrasi, dan integrasi sistem AI/Automation Agents","archived":false,"fork":false,"pushed_at":"2026-06-30T04:14:12.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T05:18:35.224Z","etag":null,"topics":["agent-server","ai-agents","automation","server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kazetama.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T06:36:33.000Z","updated_at":"2026-06-30T04:14:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kazetama/agents-server","commit_stats":null,"previous_names":["kazetama/agents-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Kazetama/agents-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazetama%2Fagents-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazetama%2Fagents-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazetama%2Fagents-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazetama%2Fagents-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kazetama","download_url":"https://codeload.github.com/Kazetama/agents-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kazetama%2Fagents-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35226918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-server","ai-agents","automation","server"],"created_at":"2026-07-07T12:01:58.027Z","updated_at":"2026-07-07T12:02:02.999Z","avatar_url":"https://github.com/Kazetama.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐳 Local ChatOps: Automated Bi-Directional Docker Server Management\n\nSistem ChatOps otomatisasi pengelolaan Docker Server dua arah secara lokal berbasis Python, pustaka `pyTelegramBotAPI`, dan mesin kecerdasan buatan lokal **Ollama (Model qwen2.5-coder:7b)**. Proyek ini didesain sebagai dokumentasi arsitektur DevOps untuk memenuhi tugas **Literasi Informasi**.\n\n---\n\n## 📌 Pengenalan ChatOps \u0026 Literasi Informasi IT\nDalam dunia DevOps modern, **ChatOps** adalah kolaborasi kerja berbasis obrolan (chat) yang menghubungkan manusia, alat otomatisasi server, dan sistem operasi dalam satu alur kerja terintegrasi. \n\nProyek ini mendemonstrasikan **Literasi Informasi IT** dengan membuktikan bagaimana kecerdasan buatan lokal (LLM) dapat dipadukan dengan modul pemrograman deterministik secara aman untuk menjembatani instruksi bahasa manusia biasa (natural language) ke dalam eksekusi CLI server yang presisi, tanpa mengorbankan privasi data (100% berjalan offline/lokal).\n\n---\n\n## 🏛️ Arsitektur Sistem \u0026 Alur Kerja\n\nSistem ini berjalan secara **dua arah (Bi-Directional ChatOps)**:\n\n```mermaid\ngraph TD\n    %% Arah A: User ke Server %%\n    User([Telegram User]) --\u003e|1. Kirim Instruksi Bahasa Alami| Bot[main.py Bot Engine]\n    Bot --\u003e|2. Muat Aturan \u0026 Prompt| Skill[skills/docker_management.md]\n    Bot --\u003e|3. Kirim Prompt Kontekstual| Ollama[Ollama: qwen2.5-coder:7b]\n    Ollama --\u003e|4. Balas Perintah Docker CLI| Bot\n    Bot --\u003e|5. Lolos Guardrail? Jalankan Subprocess| Host[Ubuntu Host CLI]\n    Host --\u003e|6. Ambil Output CLI| Bot\n    Bot --\u003e|7. Minta Penjelasan Manusiawi| Ollama\n    Ollama --\u003e|8. Kirim Ringkasan Penjelasan| Bot\n    Bot --\u003e|9. Kirim Format Rapi \u0026 Detail| User\n\n    %% Arah B: Server ke User %%\n    DockerDaemon[Docker Daemon Engine] -.-\u003e|1. Stream Event: Die/OOM| MonitorThread[Event Monitor Thread]\n    MonitorThread --\u003e|2. Tangkap Event \u0026 Ambil Logs| DockerSDK[Docker Python SDK]\n    DockerSDK --\u003e|3. Kirim Logs \u0026 Status| Ollama\n    Ollama --\u003e|4. Ringkas Penyebab Error AI| MonitorThread\n    MonitorThread --\u003e|5. Kirim Notifikasi \u0026 Tombol Aksi| User\n```\n\n### 🔄 Alur Dua Arah (Bi-Directional Workflow)\n1. **Arah A (User ke Server - Kontrol Aktif):**\n   * Pengguna mengirim instruksi (contoh: *\"tampilkan container aktif\"*).\n   * `main.py` memuat panduan dari `skills/docker_management.md`.\n   * Payload dikirim ke **Ollama** untuk dievaluasi.\n   * Perintah Docker CLI yang dihasilkan oleh Ollama divalidasi oleh filter **Safety Guardrail**.\n   * Jika aman, perintah dieksekusi secara aman menggunakan `subprocess` (tanpa shell evaluation).\n   * Hasil output dibaca, dirangkum ulang oleh Ollama ke dalam penjelasan bahasa Indonesia yang ramah, lalu dikirim ke Telegram pengguna.\n\n2. **Arah B (Server ke User - Notifikasi Pasif):**\n   * Asynchronous thread memantau event Docker melalui `docker.from_env().events()`.\n   * Jika mendeteksi container mati mendadak (`die` atau `oom`), thread mengambil log container tersebut.\n   * **Ollama** menganalisis log kesalahan tersebut menjadi ringkasan penyebab error 1-2 kalimat (bahasa Indonesia).\n   * Notifikasi peringatan dikirim ke pengguna via Telegram lengkap dengan tombol interaktif **Inline Keyboard**: `[🔄 Restart Container]` dan `[📝 Lihat Log Singkat]`.\n\n---\n\n## 💻 Spesifikasi Infrastruktur Lokal\n* **Sistem Operasi**: Ubuntu Linux (Native)\n* **Perangkat Keras**: RAM 8GB, GPU NVIDIA RTX 2050 (4GB VRAM)\n* **AI Engine**: Ollama lokal running model `qwen2.5-coder:7b`.\n  * *Optimalisasi Memori*: Dikompilasi menggunakan split-processing **53% CPU / 47% GPU** (melalui dynamic memory swap Ollama) karena ukuran model 5.8 GB melampaui VRAM fisik 4GB.\n  * *HTTP Request Timeout*: Dikonfigurasi sebesar **90 detik** guna mengakomodasi latensi pemrosesan split-computing pada CPU-GPU.\n\n---\n\n## 📁 Struktur Direktori\n```text\nchatops-project/\n├── .env                  # Menyimpan token bot, host Ollama, \u0026 whitelist ID\n├── .env.example          # Template panduan konfigurasi variabel server\n├── main.py               # Berkas utama ChatOps engine (Python)\n├── requirements.txt      # Daftar dependensi modul Python yang dibutuhkan\n└── skills/\n    └── docker_management.md  # File Markdown berisi panduan batasan instruksi AI\n```\n\n---\n\n## 🚀 Panduan Instalasi \u0026 Pengaturan\n\n### 1. Prasyarat Sistem\nPastikan Docker, Python3, pip, dan Ollama sudah terpasang di sistem Ubuntu Anda:\n```bash\nsudo apt update\nsudo apt install python3 python3-pip python3-venv docker.io -y\n```\n\nPastikan user Anda terdaftar dalam group docker agar dapat mengakses Docker API tanpa `sudo`:\n```bash\nsudo usermod -aG docker $USER\nnewgrp docker\n```\n\n### 2. Persiapan AI Model di Ollama\nJalankan service Ollama dan pasang model Qwen2.5 Coder secara lokal:\n```bash\nsystemctl start ollama\nollama pull qwen2.5-coder:7b\n```\n\n### 3. Clone \u0026 Inisialisasi Dependensi Python\nBuat virtual environment dan instal modul pustaka proyek:\n```bash\n# Buat Virtual Environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Instal Pustaka Pendukung\npip install -r requirements.txt\n```\n\n### 4. Konfigurasi Variabel Lingkungan\nSalin berkas template `.env.example` menjadi `.env`:\n```bash\ncp .env.example .env\n```\nBuka berkas `.env` dan lengkapi nilainya:\n* `TELEGRAM_BOT_TOKEN`: Token bot Anda dari `@BotFather`.\n* `ALLOWED_TELEGRAM_IDS`: ID unik Telegram Anda (untuk keamanan autentikasi).\n* `ALERT_CHAT_ID`: ID unik chat tempat notifikasi error akan dikirimkan.\n\n---\n\n## 🛡️ Fitur Keamanan (Safety Guardrail)\nMengandalkan model bahasa kecerdasan buatan (LLM) saja tidak cukup untuk keamanan sistem operasi. Oleh karena itu, berkas `main.py` menyematkan lapisan keamanan deterministik mutlak sebelum instruksi dieksekusi:\n\n1. **Pemeriksaan Prefix**: Perintah wajib diawali dengan keyword `docker`.\n2. **Blokir Operator Shell Chaining**: Mencegah command injection dengan menolak adanya karakter `;`, `\u0026\u0026`, `||`, `|`, `\u0026`.\n3. **Blokir Redirection**: Menolak tanda `\u003e`, `\u003e\u003e`, `\u003c` agar tidak terjadi pembacaan/manipulasi file sistem luar.\n4. **Blokir Subshell \u0026 Backticks**: Menolak ekspresi `$()`, dan `` ` `` untuk menghentikan nested command execution.\n5. **Whitelist \u0026 Blacklist Kata Kunci**: Memblokir keyword berbahaya secara deterministik seperti `rm -rf`, `sudo`, `/etc`, `docker.sock`, `sh`, dan `bash`.\n6. **Subprocess execution (Shell=False)**: Menggunakan `shlex.split` untuk mengubah string command menjadi parameter list diskrit, memotong kemungkinan shell mengevaluasi operator berbahaya yang lolos.\n\n---\n\n## 🔬 Skenario Pengujian (Test Plan)\n\n### 1. Jalankan Bot Server\nAktifkan bot ChatOps Anda dengan perintah:\n```bash\npython3 main.py\n```\n\n### 2. Pengujian Arah A (Teks Bahasa Manusia)\n* **Langkah**: Kirim pesan `\"tampilkan daftar container\"` ke Telegram Bot Anda.\n* **Hasil Diharapkan**: Bot membalas dengan penjelasan naratif bersahabat dari Ollama AI (misal: *\"Halo, saat ini tidak ada container yang berjalan\"*), diikuti oleh command asli `docker ps` dan output tabel raw CLI yang rapi.\n\n### 3. Pengujian Filter Keamanan (Guardrail Block)\n* **Langkah**: Kirim pesan *\"tampilkan container; rm -rf /\"* ke Telegram Bot.\n* **Hasil Diharapkan**: Bot langsung mendeteksi upaya injeksi karakter `;` dan `rm -rf` lalu mengembalikan pesan: `⚠️ Akses Ditolak / Perintah Tidak Aman!`. Eksekusi langsung dibatalkan secara deterministik.\n\n### 4. Pengujian Arah B (Alerting Otomatis \u0026 Tombol Aksi)\n* **Langkah**: Sengaja buat kontainer uji coba yang akan langsung mati di terminal server Anda:\n  ```bash\n  docker run --name container-test-error -d alpine sh -c \"sleep 5 \u0026\u0026 echo 'Koneksi database terputus' \u0026\u0026 exit 1\"\n  ```\n* **Hasil Diharapkan**:\n  * Dalam 5 detik, container berhenti karena error.\n  * Thread monitor secara real-time menangkap event tersebut.\n  * Bot mengirim pesan peringatan ke Telegram Anda lengkap dengan ringkasan AI: *\"Analisis AI: Container 'container-test-error' mengalami kegagalan karena koneksi database terputus.\"*\n  * Di bawah pesan terdapat 2 tombol interaktif: **[🔄 Restart Container]** dan **[📝 Lihat Log Singkat]**.\n  * Klik tombol **[🔄 Restart Container]** -\u003e teks pesan akan berupah menjadi `\"⏳ Memproses restart...\"` lalu berubah sukses `\"✅ Container container-test-error Berhasil Dinyalakan Kembali!\"`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazetama%2Fagents-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkazetama%2Fagents-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazetama%2Fagents-server/lists"}