Agent Vortex is a fully Dockerized, personal AI operating system built with LangGraph, PostgreSQL, MCP servers, and modern LLM tooling.
It seamlessly integrates multiple disparate tools into a single autonomous workflow capable of reasoning, planning, executing, and persisting context across sessions.
- Browser Automation: Powered by Playwright MCP. Can navigate to URLs, extract content, capture snapshots, interact with web pages, and manage tabs.
- WhatsApp Automation: Powered by a built-in WhatsApp MCP sidecar. Allows the agent to send WhatsApp messages natively.
- Google Workspace Integration: Connects to Gmail and Google Calendar to read/send emails and manage scheduling.
- Persistent Memory Stack: Short-Term Memory (STM) for conversational context and Long-Term Memory (LTM) stored in PostgreSQL for permanent context injection.
- File Generation: Capable of generating robust PDF documents and Excel spreadsheets on the fly.
- Human-In-The-Loop (HITL): Built-in risk assessment and approval workflows before executing dangerous actions.
START
↓
Planner Node (Designs execution steps)
↓
Risk Assessment (Evaluates action danger level)
↓
Approval (Optional HITL for high-risk plans)
↓
Executor (Runs the tools using Browser-First Logic)
↓
END
Agent Vortex is now fully Dockerized! The repository contains everything you need to run the Agent, the PostgreSQL database, and the WhatsApp MCP sidecar seamlessly.
- Docker and Docker Compose installed on your host machine.
- An API key for your chosen LLM (default is via OpenRouter).
git clone https://github.com/CherukuriPavanKumar/AgentVortex.git
cd AgentVortexCopy the example environment file:
cp .env.example .envEdit your .env file:
- Provide your
OPENROUTER_API_KEY. - Generate a secure token for the WhatsApp MCP sidecar:
Paste this value into
openssl rand -hex 32
WHATSAPP_MCP_TOKEN.
If you wish to use the Gmail or Google Calendar features:
- Generate your
credentials.jsonfrom the Google Cloud Console. - Run the local script to authenticate and generate
token.pickle. - Uncomment the volume mounts for these files in
docker-compose.yml.
Run Docker Compose to build and start the ecosystem:
docker compose up -d --buildThe WhatsApp MCP server runs securely isolated in its container, requiring a one-time QR code scan from your phone.
- Ensure the system is running (
docker compose ps). - Open your host machine's browser and navigate to: http://localhost:8765/pair
- Open WhatsApp on your phone → Settings → Linked Devices → Link a Device.
- Scan the QR code shown on the screen.
Security Note: This pairing page is bound strictly to
127.0.0.1on your host. It is not exposed to your local network.
Attach to the agent container's terminal interface:
docker attach agentvortex-agent-1(Tip: To detach without stopping the container, press Ctrl+p, then Ctrl+q).
Any PDFs or Excel spreadsheets generated by the agent will appear automatically in your host machine's generated_pdfs/ or generated_excels/ directories via Docker volume mounts.
| Tool Group | Tools |
|---|---|
| Core | terminal_tool, generate_pdf, generate_excel |
| Browser | browser_navigate, browser_read, browser_interaction, browser_tabs |
whatsapp_send_message |
|
gmail_read, gmail_send, calendar_read, calendar_write |
Current version: v0.2.0
Implemented in V2:
- ✅ Complete Dockerization (Agent + Postgres + MCPs)
- ✅ Secure WhatsApp MCP Pairing via Docker Networking
- ✅ Browser MCP integration (Playwright)
- ✅ LLM Tooling & Context Injection
- ✅ Persistent Conversations (PostgreSQL)
Future Roadmap:
- Agent UI / Frontend Dashboard
- Improved semantic vector memory architecture
- Multi-agent delegation workflows
MIT License