Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: rewrite README with a technical, architecture-first framing
trohitgad964252a50d
diff --git a/README.md b/README.mdindex 87a37e34..4e885bc4 100644--- a/README.md+++ b/README.md@@ -5,9 +5,9 @@<a href="https://discord.gg/c9pCJ7d8Ce" target="_blank"><img src="https://img.shields.io/discord/1455977012308086895?logo=discord&logoColor=white&label=Discord" alt="Discord"></a><a href="https://deepwiki.com/trohitg/MachinaOS" target="_blank"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>-Personal AI Assistant/Co-Employees that Perform Human Like Tasks. Connect AI Assistant to your email, calendar, messages, phone, and more.+Self-hostable workflow runtime for AI agents. Plugin-first Python backend, schema-driven React Flow frontend, Temporal-backed distributed execution, and a native-SDK LLM layer that runs against cloud providers or local servers (Ollama, LM Studio).-Mashup of N8N + Openclaw but with better visibility of what it's doing and also tighter control of what your AI Assistant can do.+Think n8n's visual builder with the agent ergonomics of an SDK — workflows are JSON, nodes are typed Python plugins, and the executor is durable.## See It In Action ↓@@ -17,137 +17,112 @@ https://github.com/user-attachments/assets/a30979e0-8066-4412-b466-cc3a70bcf3ddhttps://github.com/user-attachments/assets/9785aefb-9424-4a80-bd83-bb1205fc70af-## Prerequisites--- **Node.js 22+** - https://nodejs.org/-- **Python 3.12+** - https://python.org/-## Quick Start+**Prerequisites:** Node.js 22+, Python 3.12++```bashnpm install -g machinaosmachina start```-Open http://localhost:3000--<details>-<summary><b>One-Line Install (auto-installs dependencies)</b></summary>--**Linux/macOS:**-```bash-curl -fsSL https://raw.githubusercontent.com/trohitg/MachinaOS/main/install.sh | bash-```--**Windows (PowerShell):**-```powershell-iwr -useb https://raw.githubusercontent.com/trohitg/MachinaOS/main/install.ps1 | iex-```--</details>+Open http://localhost:3000. Backend on `:3010`, Temporal UI on `:8080`.<details>-<summary><b>Clone & Run (for developers)</b></summary>+<summary><b>Run from source</b></summary>-Development from source requires [pnpm](https://pnpm.io/) (enforced by `scripts/preinstall.js` via `pnpm-workspace.yaml`):+Source builds require [pnpm](https://pnpm.io/):```bash-npm install -g pnpm # one-time+npm install -g pnpmgit clone https://github.com/trohitg/MachinaOS.gitcd MachinaOSpnpm install-pnpm run buildpnpm run dev```+The `dev` task starts the Python backend, Vite client, WhatsApp RPC, and Temporal in parallel. See [SETUP.md](docs-internal/SETUP.md) and [SCRIPTS.md](docs-internal/SCRIPTS.md).+</details>-## What You Can Build+## Architecture-### Personal AI Assistants-Create AI agents that remember conversations, use tools, and work together. Choose from OpenAI, Claude, Gemini, DeepSeek, Kimi, Mistral, Groq, and 200+ models via OpenRouter.+```++--------------------------+ WebSocket +--------------------------++| React 19 + Vite client | <==================> | FastAPI backend |+| React Flow canvas | (typed RPC + | Plugin registry |+| TanStack Query cache | CloudEvents v1.0 | Native LLM SDK layer |+| Zustand slice stores | broadcasts) | Temporal executor |++--------------------------+ +-------------+------------++ |+ +------------------+------------------++ v v+ +---------------+ +---------------++ | Temporal | | Encrypted |+ | (durable | | credentials |+ | activities) | | store |+ +---------------+ +---------------++```-### Automate Your Google Workspace-- Send and search emails-- Create calendar events-- Upload files to Drive-- Update spreadsheets-- Manage tasks and contacts+- **Plugin-first backend.** One Python file per node. The plugin class declares metadata, typed input/output schemas, and an execute method; the framework auto-registers it on import. The backend spec is the single source of truth — the frontend renders entirely from server-served schemas.+- **Three execution modes** with automatic fallback: Temporal (distributed, durable) → Redis-backed parallel scheduling → sequential.+- **Event-driven deployment.** Each trigger event spawns an independent execution run with isolated context. Multiple runs of the same workflow can execute concurrently.+- **Dual-path LLM execution.** Chat completions go through a native-SDK layer to keep cold-start fast; agent runs use LangChain + LangGraph for tool calling and state graphs.+- **WebSocket-first RPC** with reliable reconnect, replay queue, request correlation, and CloudEvents v1.0 envelopes for typed broadcasts.-### Universal Email (IMAP/SMTP)-- Send, read, search, and manage emails via the Himalaya CLI-- Works with Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, or any custom IMAP/SMTP server-- Polling-based trigger for incoming email workflows+Full diagrams and deep-dives: **[CONTRIBUTING.md](CONTRIBUTING.md)** and [docs-internal/](docs-internal/).-### Control Your Devices-- Send WhatsApp messages automatically-- Post to Twitter/X-- Send Telegram messages via bot-- Control your Android phone (WiFi, Bluetooth, apps, camera)-- Schedule tasks and reminders+## What's In The Box-### Browse the Web-- Interactive browser automation with accessibility-tree navigation (agent-browser)-- Web scraping with BeautifulSoup or Playwright (crawlee)-- Route requests through residential proxies with geo-targeting-- Run Apify actors for social media and search engine scraping-- DuckDuckGo, Brave, Serper (Google), and Perplexity search+### Node plugins+Categories: AI agents, chat models, social (WhatsApp / Telegram / Twitter / Discord / Slack / Signal / SMS / Webchat / Email / Matrix / Teams), Google Workspace (Gmail / Calendar / Drive / Sheets / Tasks / Contacts), Android (16 service nodes via ADB + relay), browser automation, web scraping (Crawlee, Apify, HTTP), document RAG (parsers, chunkers, embeddings, vector stores), filesystem + shell (Nushell), code executors (Python / JS / TS), process manager, scheduling (cron + timer), webhooks, location (Google Maps), payments (Stripe), residential proxies.-### Plan Complex Tasks-- `writeTodos` tool lets any AI agent create and update structured task lists-- Real-time checklist rendering in the UI-- Plan-work-update loop with `pending` / `in_progress` / `completed` states+### LLM providers (11 chat-model backends)+| Provider | Path | Models |+|--------------|-------------|------------------------------------------------------------------------|+| OpenAI | Native + LC | GPT-5.x, GPT-4.1, o-series (reasoning effort), GPT-4o |+| Anthropic | Native + LC | Claude Opus 4.x, Sonnet 4.x, Haiku 4.5 (budget thinking) |+| Google | Native + LC | Gemini 3-pro/flash, 2.5-pro/flash/flash-lite (thinking budget) |+| DeepSeek | Native + LC | deepseek-chat, deepseek-reasoner |+| Kimi | Native + LC | kimi-k2.5, kimi-k2-thinking |+| Mistral | Native + LC | mistral-large, mistral-small, codestral |+| Groq | LC | Llama 3.x/4, Qwen3-32b, GPT-OSS |+| Cerebras | LC | Llama 3.1, GPT-OSS, Qwen-3-235b |+| OpenRouter | Native + LC | 200+ models via unified API |+| **Ollama** | Native | Local models — context length and capabilities probed via official SDK |+| **LM Studio**| Native | Local models — context length and capabilities probed via official SDK |-### Process Documents-- Parse PDFs and documents-- Search your files with AI+### Specialized agents+17 agent types covering Android control, web automation, coding, task management, social messaging, travel planning, productivity (Google Workspace), payments, consumer interactions, autonomous loops, and recursive language models. Team-lead agents (AI Employee, Orchestrator) accept other agents as teammates and auto-expose them as delegation tools.-### Build Agent Teams+### Skills system+Markdown-driven, editable in-UI. Skills carry their own instructions, allowed tools, and metadata; defaults live on disk as `SKILL.md` files and get seeded into the database on first load. Folder layout maps to agent specialization (assistant, android, coding, productivity, social, terminal, web, etc.).-```- +------------------+- | AI Employee |- | (Team Lead) |- +--------+---------+- | input-teammates- +-----------------+------------------+- | | |- +------v------+ +------v------+ +-------v-----+- | Coding Agent| | Web Agent | | Task Agent |- +-------------+ +-------------+ +-------------+-```+### Code execution+Sandboxed Python with curated stdlib imports, plus JavaScript and TypeScript executors. The process-manager node owns long-running children (dev servers, watchers, build tools) and streams their output to the Terminal tab.-- **AI Employee / Orchestrator** - Team lead agents for coordinating multiple specialized agents-- **Intelligent Delegation** - AI decides when to delegate based on task context-- **Delegation Tools** - Connected agents become `delegate_to_*` tools automatically-- **16 Specialized Agents** - Android, Coding, Web, Task, Social, Travel, Tool, Productivity, Payments, Consumer, Autonomous, Orchestrator, AI Employee, RLM, Claude Code, Deep Agent-- **Team Monitor** - Real-time visualization of team operations+### Filesystem isolation+Per-workflow workspace directory. Filesystem and shell nodes operate in a sandboxed virtual mode — path validation rejects traversal attempts uniformly across Windows and POSIX. Default shell is **Nushell** (same grammar everywhere), with fallback to the host's native shell when Nushell isn't installed.-### Run Code & Manage Processes-- Execute Python, JavaScript, and TypeScript code-- Persistent Node.js server for fast JS/TS execution-- **Process Manager** - Start, stop, and manage long-running processes (dev servers, watchers, build tools) with output streaming to Terminal tab-- OS-specific terminal skills (Bash, PowerShell, WSL)--## Visual Workflow Builder+## Configuration-Drag-and-drop interface to connect AI models, services, and triggers. No code required.+Credentials live in a separate encrypted SQLite database with field-level encryption (Fernet + PBKDF2-SHA256, 600k iterations per OWASP 2024). OAuth tokens and API keys use separate storage paths by design, and refresh tokens never live in process memory.-## Configuration+OAuth redirect URIs are derived at runtime from the request context — no port hardcoding, works identically in dev and behind a reverse proxy. Credential backends are pluggable: local encrypted SQLite, OS-native keyring, or AWS Secrets Manager.-Click **Credentials** in the toolbar to add your API keys for AI providers, Google, WhatsApp, and Twitter.+Click **Credentials** in the toolbar UI to connect providers.## Documentation-Full docs: https://docs.zeenie.xyz/+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — repository map, architecture diagrams, contribution recipes+- **[server/nodes/README.md](server/nodes/README.md)** — 5-minute plugin recipe + folder map + shared helpers+- **[docs-internal/](docs-internal/)** — full architecture index: execution engine, Temporal, native LLM SDK, event waiter, credentials encryption, status broadcaster, RLM, Deep Agent, Claude Code agent, performance, build pipeline+- **Hosted docs:** https://docs.zeenie.xyz/+- **DeepWiki:** https://deepwiki.com/trohitg/MachinaOS## Community-Join our [Discord](https://discord.gg/NHUEQVSC) for help, feedback, and updates.--## Contributing--Want to add a node, LLM provider, skill, or integration? See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the codebase map, architecture diagrams, development setup, and step-by-step recipes for common contributions.+[Discord](https://discord.gg/c9pCJ7d8Ce) — help, feedback, and design discussions.## License