Build · 4h · ₹0
An autonomous infrastructure control agent that translates natural-language goals into verified multi-step execution plans across remote Linux, Docker, Kubernetes, AWS, and local systems.
What it does
The mechanics, data flow, and user interaction model behind SYNAPSE.
Instead of manually SSH-ing into a server, running the right Docker command, copying a container ID, and curling an endpoint, you describe the outcome: 'build the Flask image on the RHEL server, run it on port 5000, curl the health check, and SMS me the response.' SYNAPSE breaks that into a step plan, executes each step with the appropriate tool, verifies success (not just that a tool ran, but that it didn't report success: false), retries once on failure, and replans (capped at 2 replans per session) if a step still fails. Simple queries ('list running docker containers') skip planning and go straight to a single ReAct tool call. Compound commands trigger a Planner → Executor loop, with the live plan rendered in the UI as it executes.
Technical Highlights
- Planner/Executor architecture with automatic retry and bounded replanning (capped at 2 replans per session), not just a single LLM tool-call loop
- Model router with provider fallback chain (Groq Llama-3.3 → Gemini 2.0 → Cerebras → local Ollama) for resilient execution with zero rate-limit downtime
- Strict safety gates: destructive commands (recursive delete, docker prune/rm, kubectl delete, AWS terminate) require human-in-the-loop confirmation
- Real-time plan visualization over WebSocket (Socket.IO) streaming live step progress and terminal outputs to the React frontend
- Complete pytest test suite covering tools, planner, executor, and router, plus full CI workflow
Why it matters
The architectural judgment, practical engineering decisions, and core problems solved.
This is the gap between 'an LLM wrapper that answers questions' and 'an agent that does things and knows whether they worked.' The verify → retry → replan loop is the part most toy agent demos skip — it's what makes multi-step automation trustworthy enough to point at a real server instead of a sandbox. What it controls: remote Linux (SSH via paramiko), local Docker, local Kubernetes (kubectl), local PowerShell, AWS CLI, local ML training (scikit-learn), GitHub Actions, plus email/SMS/Telegram notifications.
Personal homelab and server infrastructure management
Quick-turnaround DevOps and container operations where describing the outcome is faster than writing commands
Multi-cloud deployment orchestration and automated health-check verification
Reference architecture for building safe, verified autonomous agents against real-world systems
System architecture
End-to-end execution pipeline running across LangGraph, FastAPI, Groq, Docker, Kubernetes.
Provider fallback chain (Groq Llama-3.3 → Gemini 2.0 → Cerebras → Ollama) for zero rate-limit downtime
DAG plan generation with verify-retry-replan loop (capped at 2 replans per session)
Blocks destructive commands (rm -rf, docker prune, kubectl delete) until user confirmation
Remote SSH (Paramiko), Docker Engine, kubectl, AWS CLI, and PowerShell runtime adapters
Real-time WebSocket step status streaming to React frontend + Telegram/SMS dispatch
The path
Step-by-step implementation guide. Verbatim code snippets, configurations, and prompts.
Building the Model Router & Provider Fallback Chain
Set up the multi-provider client pool prioritizing ultra-fast Groq Llama-3.3 70B with automatic fallback to Gemini 2.0 Flash and local Ollama when hitting rate limits or network drops.
Verbatim Code / Config
Implement Router with fallback priority: [Groq(llama-3.3-70b-versatile), Gemini(gemini-2.0-flash), Cerebras(llama-3.1-70b), Ollama(local-qwen)]. Catch 429 RateLimitError and transparently reroute to next provider.LangGraph State Machine with Verify-Retry-Replan Loop
Construct the LangGraph workflow separating simple ReAct tool queries from compound goal planning. Inject post-step verification that inspects stderr and return codes before advancing.
Verbatim Code / Config
StateGraph(AgentState): RouterNode -> [SimpleReAct | PlannerExecutor]. PlannerNode creates Plan(steps=[Step]). ExecutorNode runs tool -> VerifierNode checks (exit_code == 0 and 'error' not in stderr). If failed: RetryNode(max=1) -> ReplanNode(max=2).Safety Interceptors & Destructive Action Gates
Implement AST and regex security interceptors that intercept dangerous operations (recursive deletion, container prunes, cluster teardowns) and require interactive human-in-the-loop approval.
Verbatim Code / Config
BLOCKED_PATTERNS = [r'rm\s+(-rf|-fr)', r'docker\s+(system\s+prune|rm\s+-f)', r'kubectl\s+delete\s+(all|namespace)']. Intercept command before execution; if matches: yield Event(status='NEEDS_CONFIRMATION', action_id=uuid).Socket.IO Real-Time Visualization & Alert Dispatch
Stream live step status, terminal output snippets, and retry counts over WebSockets to the React frontend while triggering Telegram/Twilio alerts upon overall workflow completion.
Verbatim Code / Config
@sio.on('goal') async def handle_goal(sid, data): async for event in agent.astream_events(data['goal']): await sio.emit('step_update', {'step_id': event.id, 'status': event.status, 'output': event.output})Where it broke
The failure mode, root-cause breakdown, and resolution discovered during development.
The Tell
“The agent parsed an exit code of 0 from a command that silently logged 'Docker daemon not running' to stdout, falsely reporting step success.”
Why it failed
Standard ReAct tool executor checked only OS return code ($? == 0). Many CLI utilities write failure notices to stdout while still exiting with code 0.
The Fix
Built a semantic verifier layer that performs regex heuristics on stdout/stderr and runs an active probe check (e.g., verifying port 5000 responds with HTTP 200) rather than trusting return codes alone.
What it cost
₹0 to build and run permanently within verified free tiers.
| Service / Tool | Cost | Free Tier Limits |
|---|---|---|
| Groq Cloud | ₹0 | Free tier (30 RPM / 14.4k TPM) covers real-time planning and execution |
| Google Gemini API | ₹0 | Free tier (15 RPM / 1M TPM) fallback provider |
| Local Docker & Kubernetes | ₹0 | Runs locally on workstation or homelab node |
| Telegram Bot API | ₹0 | Unlimited free instant alert notifications |
| FastAPI, LangGraph & Socket.IO | ₹0 | Open-source runtime stack (MIT / Apache 2.0) |
Make it yours
Three concrete variations you can build and ship using this exact foundation.
- 01
Database Migration & Backup Agent: Automates PostgreSQL schema backups, runs migrations, verifies table indices, and posts audit logs.
- 02
CI/CD Incident Triage Agent: Listens to GitHub Actions failure webhooks, fetches workflow logs, isolates stack traces, and suggests code fixes.
- 03
Multi-Cloud Cost Optimizer Agent: Queries AWS, GCP, and DigitalOcean APIs to identify unattached EBS volumes and idle VM instances, requesting approval before downsizing.
Where next
Ready to ship SYNAPSE?
Review the architecture, clone the prompt and implementation steps, and deploy your live URL for ₹0.