Your AI on-call assistant for Docker operations
Open-source, self-hosted AI agent that helps you manage Docker infrastructure through natural language commands via Telegram.
Never miss an incident. Your on-call buddy is always watching. 🚨
Why trust an AI with your infrastructure?
OnCallMate is built security-first for on-premise deployment:
- ✅ 100% Self-Hosted - Runs entirely in your network, no cloud dependency
- ✅ Docker Socket Proxy - Never exposes
/var/run/docker.sockdirectly (read-only by default) - ✅ Zero Telemetry - Your container data never leaves your infrastructure
- ✅ Admin Allowlist - Telegram ID-based access control (no public access)
- ✅ Full Audit Trail - Every AI decision logged to SQLite with timestamp/user/action
- ✅ AI Provider Choice - You control what data is sent to which AI (OpenAI/Claude/local)
- ✅ Open Source - MIT license, audit the code yourself
Default security posture:
- Docker operations: Read-only (list, inspect, logs, stats)
- Write operations: Disabled (require explicit opt-in)
- Network: Isolated (containers on private bridge network)
- 🐳 Docker Operations - List, inspect, logs, stats, system info
- 🤖 AI-Powered - Natural language understanding (Claude, GPT, Gemini)
- 💬 Telegram Interface - Control from anywhere, anytime
- 🔒 Security First - Docker socket proxy, audit logs, admin-only access
- 📊 Audit Trail - All operations logged to SQLite
- 🔌 Extensible - Plugin architecture for providers & channels
- ⏱️ Proactive Scheduler - Periodic container checks + anomaly alerts
- 🧠 Self-Learning Baseline - Learns normal running-container profile over time
- 🧩 Configurable Prompts - Prompts are stored in
prompts/*.md(not hard-coded) - 🆓 Free AI Options - Multiple AI providers including free tiers (OpenRouter!)
- Docker & Docker Compose
- Telegram Bot Token (create one)
- AI Provider API Key (choose one):
- OpenRouter (get free key) - FREE models available! ⭐
- Anthropic Claude (get key)
- OpenAI (get key)
- Clone the repo
git clone https://github.com/ismailperim/oncallmate.git
cd oncallmate
- Configure environment
cp .env.quickstart .env
nano .env
Fill in your credentials:
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ADMIN_IDS=123456789
# Use OpenRouter for FREE tier
AI_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-your-key-here
OPENROUTER_MODEL=google/gemini-flash-1.5
# Proactive mode
MAIN_CONTACT_ID=123456789
LEARN_MODE_ENABLED=true
LEARN_INTERVAL_MINUTES=15
💡 Tip: OpenRouter offers FREE models! See PROVIDERS.md for all options.
- Start the agent
docker-compose up -d
- Test it - Open Telegram and message your bot:
/start
/ps
🎉 Done! You're now managing Docker via AI chat.
/start - Welcome message
/help - Show all commands
/ps - List containers
/logs <container> - Show container logs
/stats <container> - Container statistics
/inspect <container> - Detailed container info
/images - List Docker images
/info - Docker system info
/health - Agent health check
Just ask naturally:
- "Show me running containers"
- "What's using the most CPU?"
- "Get the last 50 lines of logs from nginx"
- "List all images"
- "What's the system memory usage?"
OnCallMate
├── Core
│ ├── Agent Engine (AI intent parsing)
│ ├── Database (audit + memory)
│ └── Logger
├── Providers (pluggable infrastructure adapters)
│ ├── Docker ✅
│ ├── Docker Swarm 🚧
│ ├── Kubernetes 🚧
│ └── AWS ECS 🚧
├── Channels (communication interfaces)
│ ├── Telegram ✅
│ ├── Slack 🚧
│ ├── Discord 🚧
│ └── Webhooks 🚧
└── AI Providers (multiple backends)
├── OpenRouter ✅ (FREE!)
├── Anthropic Claude ✅
└── OpenAI GPT ✅
See PROVIDERS.md for AI provider comparison.
/var/run/docker.sock directly in production!
OnCallMate includes docker-socket-proxy by default:
- ✅ Read-only by default
- ✅ Allowlist-based API filtering
- ✅ Isolated network
To enable write operations (start/stop), edit docker-compose.yml:
socket-proxy:
environment:
- POST=1 # Enable container start/stop
- DELETE=0 # Keep delete disabled
Only Telegram users in TELEGRAM_ADMIN_IDS can control the agent.
All operations are logged to /data/oncallmate.db:
- Who requested what
- When and from where
- Result and approval status
Query audit logs:
docker exec -it oncallmate sqlite3 /data/oncallmate.db \
"SELECT * FROM audit_logs ORDER BY timestamp DESC LIMIT 10;"
npm install
npm run dev
npm run build
npm start
- Create
src/providers/your-provider.ts - Implement the
Providerinterface - Register in
src/index.ts
Example: Docker Provider
- Create
src/channels/your-channel.ts - Implement the
Channelinterface - Register in
src/index.ts
Example: Telegram Channel
- v0.2 - Docker Swarm support + approval workflow
- v0.3 - Proactive learning mode (anomaly detection, scheduled checks)
- v0.4 - Kubernetes provider
- v0.5 - Slack & Discord channels
- v0.6 - RBAC + multi-host support
- v1.0 - Production-ready release
Roadmap details are maintained internally during private incubation.
OnCallMate is 100% free and open-source (MIT License).
AI Provider Costs (per 1000 queries):
| Provider | Model | Cost | Quality |
|---|---|---|---|
| OpenRouter | gemini-flash-1.5 | $0 (FREE/low-cost depending on route) | ⭐⭐⭐ |
| OpenAI | gpt-4o-mini | ~$0.20 | ⭐⭐⭐⭐ |
| Anthropic | claude-sonnet-4 | ~$4.50 | ⭐⭐⭐⭐⭐ |
See PROVIDERS.md for detailed pricing.
- PROVIDERS.md - AI provider comparison & setup
- CHANGELOG.md - Release history
- CONTRIBUTING.md - Contribution guidelines
- SECURITY.md - Security policy
Contributions are welcome! Please read CONTRIBUTING.md before opening a PR.
MIT License - see LICENSE
Built with:
- Anthropic Claude / OpenRouter / OpenAI - AI engines
- Dockerode - Docker API client
- node-telegram-bot-api - Telegram bot
- Winston - Logging
Made with 💙 by @ismailperim
OnCallMate - Your AI on-call assistant. Because incidents don't wait for business hours. 🚨
