{"id":48330008,"url":"https://github.com/ownpilot/OwnPilot","last_synced_at":"2026-04-20T14:01:11.317Z","repository":{"id":335092747,"uuid":"1144155526","full_name":"ownpilot/OwnPilot","owner":"ownpilot","description":"Privacy-first personal AI assistant platform with autonomous agents, tool orchestration, and multi-provider support.","archived":false,"fork":false,"pushed_at":"2026-04-17T22:48:23.000Z","size":26578,"stargazers_count":393,"open_issues_count":3,"forks_count":54,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-04-17T23:10:17.341Z","etag":null,"topics":["ai","artificial-intelligence","assistant","automation","autonomous","autonomous-agents","personal-assistant","workflows"],"latest_commit_sha":null,"homepage":"http://ownpilot.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ownpilot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-28T11:04:14.000Z","updated_at":"2026-04-17T22:48:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"999261a6-5155-470e-a494-f2824b86c42b","html_url":"https://github.com/ownpilot/OwnPilot","commit_stats":null,"previous_names":["ownpilot/ownpilot"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/ownpilot/OwnPilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ownpilot%2FOwnPilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ownpilot%2FOwnPilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ownpilot%2FOwnPilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ownpilot%2FOwnPilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ownpilot","download_url":"https://codeload.github.com/ownpilot/OwnPilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ownpilot%2FOwnPilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32050451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","artificial-intelligence","assistant","automation","autonomous","autonomous-agents","personal-assistant","workflows"],"created_at":"2026-04-05T01:00:29.997Z","updated_at":"2026-04-20T14:01:11.306Z","avatar_url":"https://github.com/ownpilot.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# OwnPilot\n\n\u003e Privacy-first personal AI assistant platform with Claw autonomous agents, soul agents, multi-agent orchestration, AI agent creator, tool orchestration, multi-provider support, MCP integration, voice pipeline, browser automation, IoT edge device control, and Telegram + WhatsApp connectivity.\n\u003e\n\u003e**Self-hosted. Your data stays yours.**\n\n\u003cp align=\"center\"\u003e\n \u003cimg src=\"ownpilot_.jpeg\" alt=\"OwnPilot — Privacy-First Personal AI Assistant Platform\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n \u003ca href=\"https://github.com/ownpilot/ownpilot/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/ownpilot/ownpilot/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n \u003ca href=\"https://ghcr.io/ownpilot/ownpilot\"\u003e\u003cimg src=\"https://img.shields.io/badge/ghcr.io-ownpilot-blue?logo=docker\" alt=\"Docker\" /\u003e\u003c/a\u003e\n \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Node.js-≥22-green?logo=node.js\" alt=\"Node.js\" /\u003e\u003c/a\u003e\n \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript\" alt=\"TypeScript\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Architecture](#architecture)\n- [Quick Start](#quick-start)\n- [Setup Guide](SETUP.md) — Detailed installation instructions\n- [Project Structure](#project-structure)\n- [Packages](#packages)\n - [Core](#core-ownpilotcore)\n - [Gateway](#gateway-ownpilotgateway)\n - [UI](#ui-ownpilotui)\n - [CLI](#cli-ownpilotcli)\n- [AI Providers](#ai-providers)\n- [Agent System](#agent-system)\n- [Soul Agents](#soul-agents)\n- [Autonomous Hub](#autonomous-hub)\n- [Agent Orchestra](#agent-orchestra)\n- [Claw Agents](#claw-agents)\n- [Subagents](#subagents)\n- [Tool System](#tool-system)\n- [MCP Integration](#mcp-integration)\n- [Artifacts](#artifacts)\n- [Voice Pipeline](#voice-pipeline)\n- [Browser Agent](#browser-agent)\n- [Edge Devices](#edge-devices)\n- [Personal Data](#personal-data)\n- [Autonomy \u0026 Automation](#autonomy--automation)\n- [Database](#database)\n- [Security \u0026 Privacy](#security--privacy)\n - [Code Execution](#code-execution)\n- [API Reference](#api-reference)\n- [Configuration](#configuration)\n- [Deployment](#deployment)\n- [Development](#development)\n- [License](#license)\n\n---\n\n## Features\n\n### AI \u0026 Agents\n\n- **Multi-Provider Support** — 4 native providers (OpenAI, Anthropic, Google, Zhipu) + 8 aggregator providers (Together AI, Groq, Fireworks, DeepInfra, OpenRouter, Perplexity, Cerebras, fal.ai) + any OpenAI-compatible endpoint\n- **Local AI Support** — Ollama, LM Studio, LocalAI, and vLLM auto-discovery on the local network\n- **Smart Provider Routing** — Cheapest, fastest, smartest, balanced, or fallback strategies\n- **Anthropic Prompt Caching** — Static system prompt blocks cached via `cache_control` to reduce input tokens on repeated requests\n- **Context Management** — Real-time context usage tracking, detail modal with per-section token breakdown, context compaction (AI-powered message summarization), session clear\n- **Streaming Responses** — Server-Sent Events (SSE) for real-time streaming with tool execution progress\n- **Configurable Agents** — Custom system prompts, model preferences, tool assignments, and execution limits\n\n### Tools \u0026 Extensions\n\n- **250+ Built-in Tools** across 32 categories (personal data, files, code execution, web, email, media, git, translation, weather, finance, automation, vector search, data extraction, utilities, orchestra, artifacts, browser, edge devices)\n- **Meta-tool Proxy** — Only 4 meta-tools sent to the LLM (`search_tools`, `get_tool_help`, `use_tool`, `batch_use_tool`); all tools remain available via dynamic discovery\n- **Tool Namespaces** — Qualified tool names with prefixes (`core.`, `custom.`, `plugin.`, `skill.`, `mcp.`) for clear origin tracking\n- **MCP Client** — Connect to external MCP servers (Filesystem, GitHub, Brave Search, etc.) and use their tools natively\n- **MCP Server** — Expose OwnPilot's tools as an MCP endpoint for Claude Desktop and other MCP clients\n- **User Extensions** — Installable tool bundles with custom tools, triggers, services, and configurations; Extension SDK provides `utils.callTool()` to invoke any of 250+ built-in tools\n- **6 Default Extensions** — Daily Briefing, Knowledge Base, Project Tracker, Smart Search, Automation Builder, Contact Enricher bundled out-of-the-box\n- **Extension Security Audit** — LLM-powered security analysis for skills and extensions before installation\n- **Skills** — Open standard SKILL.md format (AgentSkills.io) for instruction-based AI knowledge packages\n- **Custom Tools** — Create new tools at runtime via LLM (sandboxed JavaScript)\n- **Connected Apps** — 1000+ OAuth app integrations via Composio (Google, GitHub, Slack, Notion, Stripe, etc.)\n- **Tool Limits** — Automatic parameter capping to prevent unbounded queries\n- **Search Tags** — Natural language tool discovery with keyword matching\n\n### Personal Data\n\n- **Notes, Tasks, Bookmarks, Contacts, Calendar, Expenses** — Full CRUD with categories, tags, and search\n- **Productivity** — Pomodoro timer with sessions/stats, habit tracker with streaks, quick capture inbox\n- **Memories** — Long-term persistent memory (facts, preferences, events) with importance scoring, vector search, and auto-injection\n- **Goals** — Goal creation, decomposition into steps, progress tracking, next-action recommendations\n- **Custom Data Tables** — Create your own structured data types with AI-determined schemas\n\n### Coding Agents\n\n- **External AI Coding CLIs** — Orchestrate Claude Code, Codex, and Gemini CLI from the web UI or via AI tool calling\n- **Session Management** — Long-running coding sessions with real-time terminal output streaming\n- **Dual Execution Modes** — Auto mode (headless `child_process.spawn`) and interactive mode (PTY terminal)\n- **Custom Providers** — Register any CLI binary as a coding agent provider\n- **Result Persistence** — Task output, exit codes, and duration stored in the database\n\n### Soul Agents\n\n- **Rich Agent Identity** — Agents with personality, role, mission, voice, boundaries, and emoji; full identity framework for autonomous operation\n- **Heartbeat Lifecycle** — Cron-scheduled execution cycles with configurable checklist, self-healing, max duration, and cost tracking\n- **Crew System** — Multi-agent crews with role assignments, delegation protocols, and ready-made crew templates\n- **Inter-Agent Communication** — Agents can send messages to each other with subject, content, and type classification\n- **Evolution Tracking** — Version-controlled agent evolution with core/mutable traits, learnings, and feedback log\n- **Autonomy Controls** — Per-agent autonomy levels with allowed/blocked actions, approval requirements, and budget limits (per-cycle, per-day, per-month)\n- **Boot Sequences** — Configurable `onStart`, `onHeartbeat`, and `onMessage` action sequences\n- **16+ Agent Templates** — Pre-built configurations for common use cases (Morning Briefer, News Monitor, Code Reviewer, Budget Tracker, etc.)\n\n### Autonomous Hub\n\n- **Unified Command Center** — Single tabbed dashboard consolidating all autonomous agents (soul + background), crews, messaging, and activity\n- **AI Agent Creator** — Conversational agent creation: describe what you need in plain language, refine through chat, preview JSON config, create in one click\n- **Agent Cards** — At-a-glance agent status with real-time indicators, mission preview, cost tracking, and quick actions (pause/resume/delete)\n- **Activity Feed** — Unified timeline of heartbeat logs and agent messages with aggregate stats (total runs, success rate, avg duration, total cost)\n- **Global Status Bar** — Live agent count, running/paused/error breakdown, daily cost, and WebSocket connection state\n- **Search \u0026 Filters** — Filter agents by status, type (soul/background), and text search across name, role, and mission\n\n### Claw Agents\n\n- **Unified Autonomous Runtime** — Each Claw agent combines LLM reasoning, isolated workspace, 250+ tools, CLI access, browser automation, coding agents, and persistent directive files into a single autonomous runtime\n- **4 Execution Modes** — Single-shot (one task), Continuous (adaptive loop), Interval (periodic), Event-driven (reactive to EventBus events)\n- **16 Claw Tools** — `claw_install_package`, `claw_run_script`, `claw_create_tool`, `claw_spawn_subclaw`, `claw_publish_artifact`, `claw_request_escalation`, `claw_send_output`, `claw_complete_report`, `claw_emit_event`, `claw_update_config`, `claw_send_agent_message`, `claw_reflect`, `claw_list_subclaws`, `claw_stop_subclaw`, `claw_set_context`, `claw_get_context`\n- **7 Chat Management Tools** — Create, list, start, stop, message, and inspect claws from the main chat\n- **`.claw/` Directive System** — Persistent workspace files (INSTRUCTIONS.md, TASKS.md, MEMORY.md, LOG.md) that guide the claw across cycles\n- **Workspace Isolation** — Each claw gets its own file workspace with file browser, inline editor, and ZIP download\n- **Output Delivery** — Send results via Telegram, WebSocket live feed, conversation history, and artifact publishing\n- **Subclaw Orchestration** — Spawn child claws (max depth 3) with parent control (list, stop)\n- **Self-Modification** — Claws can update their own config, reflect on progress, and adapt strategy\n- **Working Memory** — Persistent key-value context (`claw_set_context`/`claw_get_context`) injected into every cycle for cross-cycle state tracking\n- **Escalation Control** — Human-in-the-loop approve/deny flow for environment upgrades with denial reason forwarding\n- **Inter-Claw Messaging** — Direct message passing between claws via inbox system\n- **Audit Log** — Per-tool-call tracking with 10 auto-categories (claw, cli, browser, coding-agent, web, code-exec, git, filesystem, knowledge, tool)\n- **Workflow Integration** — `clawNode` (24th workflow node type) for spawning claws within workflows\n- **8-Tab Management UI** — Overview, Settings, Skills, Files, History, Audit, Output, Chat\n- **6 Templates** — Research Agent, Code Reviewer, Data Analyst, Monitor \u0026 Alert, Content Creator, Event Reactor\n- **Resource Limits** — MAX_CONCURRENT_CLAWS=50, generous defaults (50 turns, 500 tool calls, 10min timeout, unlimited budget)\n\n### Subagents\n\n- **Parallel Task Delegation** — Chat agents and claw agents can spawn lightweight child agents for concurrent task execution\n- **Fire-and-Forget Model** — Spawn returns immediately with a session ID; parent polls for results via `check_subagent`/`get_subagent_result`\n- **Budget Enforcement** — Configurable concurrent limit (default 5), total spawn limit (default 20), and nesting depth cap (max 2 levels)\n- **Full Tool Access** — Subagents inherit the parent's full tool pipeline; optional `allowedTools` restriction\n- **Independent Model Selection** — Each subagent can use a different provider/model (e.g., expensive model for parent, cheap model for subagents)\n- **5 LLM-Callable Tools** — `spawn_subagent`, `check_subagent`, `get_subagent_result`, `cancel_subagent`, `list_subagents`\n\n### Agent Orchestra\n\n- **Multi-Agent Orchestration** — Fan-out/fan-in, race, pipeline, and voting strategies for concurrent multi-provider agent execution\n- **Real-time Progress** — WebSocket events for orchestra session lifecycle (started, step completed, finished)\n- **6 LLM Tools** — `create_orchestra`, `run_orchestra`, `list_orchestras`, `get_orchestra_result`, `cancel_orchestra`, `list_strategies`\n\n### Artifacts\n\n- **Versioned Documents** — Create, update, and track markdown, code, JSON, HTML, CSV, SVG, and Mermaid diagram artifacts\n- **Data Binding** — Expression-based bindings (`{{source.field}}`) that auto-resolve from conversation context\n- **Diff Tracking** — Version history with content diffs for every update\n- **5 LLM Tools** — `create_artifact`, `update_artifact`, `list_artifacts`, `get_artifact`, `delete_artifact`\n\n### Voice Pipeline\n\n- **Speech-to-Text** — Whisper API integration for audio transcription with configurable models\n- **Text-to-Speech** — OpenAI TTS with multiple voices (alloy, echo, fable, onyx, nova, shimmer)\n- **Chat Integration** — VoiceButton for recording in ChatInput, VoicePlayButton for AI response playback\n- **Channel Support** — WhatsApp voice message transcription via channel normalizer\n\n### Browser Agent\n\n- **Headless Automation** — Playwright-powered Chromium for AI-driven web browsing\n- **7 LLM Tools** — Navigate, click, type, screenshot, evaluate JavaScript, extract content, fill forms\n- **Workflow Persistence** — Browser automation workflows stored in DB for replay and audit\n\n### Skills Platform\n\n- **Enhanced Lifecycle** — Sandboxed skill execution with granular permissions (network, filesystem, database, shell, email, scheduling)\n- **npm Dependencies** — Skills can declare and install npm packages via `ownpilot skill install`\n- **CLI Management** — `ownpilot skill` commands for install, list, info, search, update, remove\n- **Permission Review** — PermissionReviewModal UI for approving skill capabilities before activation\n\n### Edge Devices (IoT)\n\n- **MQTT Integration** — Mosquitto broker for lightweight IoT device communication\n- **Device Registry** — Register edge devices (Raspberry Pi, ESP32, Arduino, custom) with sensors and actuators\n- **Telemetry Ingestion** — Real-time sensor data via MQTT topics, stored with full history\n- **Command Queue** — Send commands to devices with acknowledgment tracking\n- **6 LLM Tools** — `list_edge_devices`, `get_device_status`, `read_sensor`, `send_device_command`, `control_actuator`, `register_edge_device`\n\n### CLI Tools\n\n- **40+ Discoverable Tools** — Automatic PATH-based detection of installed CLI tools (linters, formatters, build tools, package managers, security scanners, databases, containers)\n- **Per-Tool Security Policies** — `allowed` (auto-execute), `prompt` (require approval), `blocked` (reject) per user per tool\n- **Dynamic Risk Scoring** — Catalog-based risk levels (low/medium/high/critical) feed into the autonomy risk engine\n- **Custom Tool Registration** — Register any binary as a CLI tool with category and risk metadata\n- **Approval Integration** — CLI tool policies wired into the real-time approval flow, overriding generic risk scores\n\n### Autonomy \u0026 Automation\n\n- **5 Autonomy Levels** — Manual, Assisted, Supervised, Autonomous, Full\n- **Pulse System** — Proactive AI engine that gathers context, evaluates signals, and executes actions on an adaptive 5-15 min timer with configurable directives and 4 preset templates\n- **Triggers** — Schedule-based (cron), event-driven, condition-based, webhook\n- **Heartbeats** — Natural language to cron conversion for periodic tasks (\"every weekday at 9am\")\n- **Plans** — Multi-step autonomous execution with checkpoints, retry logic, and timeout handling\n- **Risk Assessment** — Automatic risk scoring for tool executions with approval workflows\n- **Model Routing** — Per-process model selection (chat, channel, pulse, subagent) with fallback chains\n- **Extended Thinking** — Anthropic extended thinking support for deeper reasoning in complex tasks\n\n### Communication\n\n- **Web UI** — React 19 + Vite 7 + Tailwind CSS 4 with dark mode, 64 pages, 140+ components, code-split\n- **Telegram Bot** — Full bot integration with user/chat filtering, message splitting, HTML/Markdown formatting\n- **WhatsApp (Baileys)** — QR code authentication (no Meta Business account needed), self-chat mode with loop prevention, session persistence, group message support with passive history sync\n- **Channel User Approval** — Multi-step verification: approval code flow, manual admin approval, user blocking/unblocking with real-time notifications\n- **Channel Pairing Keys** — Per-channel rotating pairing keys for ownership verification with revoke support\n- **EventBus** — Unified event backbone with EventBusBridge translating dot-notation events to WebSocket colon-notation; Event Monitor UI for live debugging\n- **WebSocket** — Real-time broadcasts for all data mutations, event subscriptions, session management\n- **REST API** — 115 route modules with standardized responses, pagination, and error codes\n\n### Security\n\n- **Zero-Dependency Crypto** — AES-256-GCM encryption + PBKDF2 key derivation using only Node.js built-ins\n- **PII Detection \u0026 Redaction** — 15+ categories (SSN, credit cards, emails, phone, etc.)\n- **Sandboxed Code Execution** — Docker container isolation, local execution with approval, critical pattern blocking\n- **4-Layer Security** — Critical patterns -\u003e permission matrix -\u003e approval callback -\u003e sandbox isolation\n- **Code Execution Approval** — Real-time SSE approval dialog for sensitive operations with 120s timeout\n- **Authentication** — None, API Key, or JWT modes\n- **Rate Limiting** — Sliding window with burst support\n- **Tamper-Evident Audit** — Hash chain verification for audit logs\n- **SSRF Protection** — DNS rebinding detection, private IP blocking, and async URL validation with 1-min cache across browser service, fetch-url, and web-fetch executors\n\n---\n\n## Architecture\n\n```\n ┌──────────────┐\n │ Web UI │ React 19 + Vite 7\n │ (bundled) │ Tailwind CSS 4\n └──────┬───────┘\n │ HTTP + SSE + WebSocket (/ws)\n ┌─────────────────┼─────────────────┐\n │ │ │\n ┌────────┴────────┐ │ ┌─────────┴──────────┐\n │ Telegram Bot │ │ │ External MCP │\n │ WhatsApp │ │ │ Clients/Servers │\n │ (Channels) │ │ └─────────┬──────────┘\n └────────┬────────┘ │ │\n └────────┬───────┘──────────────────┘\n │\n ┌────────▼────────┐\n │ Gateway │ Hono HTTP API Server\n │ (Port 8080) │ 115 Route Modules\n ├─────────────────┤\n │ MessageBus │ Middleware Pipeline\n │ Agent Engine │ Tool Orchestration\n │ Orchestra │ Multi-Agent Coordination\n │ Provider Router│ Smart Model Selection\n │ Claw Agents │ Unified Autonomous Runtime\n │ Background Agt │ Persistent Autonomous Agents\n │ Coding Agents │ External AI CLIs\n │ Browser Agent │ Headless Web Automation\n │ Voice Pipeline │ STT/TTS Integration\n │ Edge Manager │ MQTT + IoT Devices\n │ CLI Tools │ 40+ Discoverable Tools\n │ Pulse Engine │ Proactive Autonomy\n │ MCP Client │ External Tool Servers\n │ Plugin System │ Extensible Architecture\n │ EventBus │ Unified Event Backbone\n │ WebSocket │ Real-time Broadcasts\n ├─────────────────┤\n │ Core │ AI Engine \u0026 Tool Framework\n │ 250+ Tools │ Multi-Provider Support\n │ Sandbox, Crypto│ Privacy, Audit\n └────────┬────────┘\n │\n ┌────────▼────────┐ ┌─────────────┐\n │ PostgreSQL │ │ Mosquitto │\n │ 67 Repos │ │ MQTT Broker │\n │ │ └──────────────┘\n └─────────────────┘\n```\n\n### Message Pipeline\n\n```\nRequest → Audit → Persistence → Post-Processing → Context-Injection → Agent-Execution → Response\n```\n\nAll messages (web UI chat, Telegram, trigger-initiated chats) flow through the same MessageBus middleware pipeline.\n\n---\n\n## Quick Start\n\n### Docker (Recommended)\n\n```bash\ngit clone https://github.com/ownpilot/ownpilot.git\ncd ownpilot\n\n# Start OwnPilot + PostgreSQL (uses defaults, no .env needed)\ndocker compose --profile postgres up -d\n\n# UI + API: http://localhost:8080\n```\n\nTo customize settings (auth, Telegram, etc.), copy and edit `.env` before starting:\n\n```bash\ncp .env.example .env\n# Edit .env — docker-compose.yml defaults match .env.example\ndocker compose --profile postgres up -d\n```\n\n### From Source\n\n#### Prerequisites\n\n- **Node.js** \u003e= 22.0.0\n- **pnpm** \u003e= 10.0.0\n- **PostgreSQL** 16+ (via Docker Compose or native install)\n\n#### Automated Setup (Recommended)\n\nUse the interactive setup wizard:\n\n```bash\n# Linux/macOS\n./setup.sh\n\n# Windows PowerShell\n.\\setup.ps1\n```\n\nThe wizard will guide you through:\n\n- Prerequisites check (Node.js, pnpm, Docker)\n- Server configuration (ports, host)\n- Authentication setup\n- Database configuration\n- Docker PostgreSQL startup\n- Dependency installation and build\n\n**Alternative: Non-interactive scripts**\n\n```bash\n# Linux/macOS\n./scripts/setup.sh --minimal # Skip Docker\n./scripts/setup.sh --docker-only # Only database\n\n# Windows PowerShell\n.\\scripts\\setup.ps1 -Mode Minimal\n.\\scripts\\setup.ps1 -Mode DockerOnly\n```\n\n#### Manual Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/ownpilot/ownpilot.git\ncd ownpilot\npnpm install\n\n# Configure\ncp .env.example .env\n# Edit .env if needed (defaults work with docker compose PostgreSQL)\n\n# Start PostgreSQL (if you don't have one already)\ndocker compose --profile postgres up -d\n\n# Start development (gateway on :8080 + Vite UI on :5173)\npnpm dev\n\n# Open http://localhost:5173 (Vite proxies API/WS to gateway)\n```\n\nAI provider API keys are configured via the **Config Center UI** (Settings page) after setup.\n\n### Configuration via CLI\n\n```bash\n# Initialize database\nownpilot setup\n\n# Start server\nownpilot start\n\n# Configure API keys (stored in database, not .env)\nownpilot config set openai-api-key sk-...\n```\n\nAPI keys and settings are stored in the PostgreSQL database. The web UI **Config Center** (Settings page) provides a graphical alternative to CLI configuration.\n\n---\n\n## Project Structure\n\n```\nownpilot/\n├── packages/\n│ ├── core/ # AI engine \u0026 tool framework\n│ │ ├── src/\n│ │ │ ├── agent/ # Agent engine, orchestrator, providers\n│ │ │ │ ├── providers/ # Multi-provider implementations\n│ │ │ │ ├── orchestra/ # Multi-agent orchestration engine\n│ │ │ │ └── tools/ # 250+ built-in tool definitions\n│ │ │ ├── plugins/ # Plugin system with isolation, marketplace\n│ │ │ ├── events/ # EventBus, HookBus, ScopedBus\n│ │ │ ├── services/ # Service registry (DI container)\n│ │ │ ├── memory/ # Encrypted personal memory (AES-256-GCM)\n│ │ │ ├── sandbox/ # Code execution isolation (VM, Docker, Worker)\n│ │ │ ├── crypto/ # Zero-dep encryption, vault, keychain\n│ │ │ ├── audit/ # Tamper-evident hash chain logging\n│ │ │ ├── privacy/ # PII detection \u0026 redaction\n│ │ │ ├── security/ # Critical pattern blocking, permissions\n│ │ │ ├── channels/ # Channel plugin architecture + UCP\n│ │ │ ├── edge/ # Edge device types and interfaces\n│ │ │ ├── assistant/ # Intent classifier, orchestrator\n│ │ │ ├── workspace/ # Per-user isolated environments\n│ │ │ └── types/ # Branded types, Result\u003cT,E\u003e, guards\n│ │ └── package.json\n│ │\n│ ├── gateway/ # Hono API server (~148K LOC)\n│ │ ├── src/\n│ │ │ ├── routes/ # 115 route handlers\n│ │ │ ├── services/ # 108 business logic services\n│ │ │ ├── tools/ # Tool providers (coding, CLI, edge, browser, etc.)\n│ │ │ ├── db/\n│ │ │ │ ├── repositories/ # 67 data access repositories\n│ │ │ │ ├── adapters/ # PostgreSQL adapter\n│ │ │ │ ├── migrations/ # 26 schema migrations\n│ │ │ │ └── seeds/ # Default data\n│ │ │ ├── channels/ # Telegram + WhatsApp channel plugins\n│ │ │ ├── plugins/ # Plugin initialization \u0026 registration\n│ │ │ ├── triggers/ # Proactive automation engine\n│ │ │ ├── plans/ # Plan executor with step handlers\n│ │ │ ├── autonomy/ # Risk assessment, approval manager, pulse\n│ │ │ ├── ws/ # WebSocket server \u0026 real-time broadcasts\n│ │ │ ├── middleware/ # Auth, rate limiting, CORS, audit\n│ │ │ ├── assistant/ # AI orchestration (memories, goals)\n│ │ │ ├── tracing/ # Request tracing (AsyncLocalStorage)\n│ │ │ └── audit/ # Gateway audit logging\n│ │ └── package.json\n│ │\n│ ├── ui/ # React 19 web interface (~115K LOC)\n│ │ ├── src/\n│ │ │ ├── pages/ # 64 page components\n│ │ │ ├── components/ # 140 reusable components\n│ │ │ ├── hooks/ # Custom hooks (chat store, theme, WebSocket)\n│ │ │ ├── api/ # Typed fetch wrapper + endpoint modules\n│ │ │ ├── types/ # UI type definitions\n│ │ │ └── App.tsx # Route definitions with lazy loading\n│ │ └── package.json\n│ │\n│ └── cli/ # Commander.js CLI\n│ ├── src/\n│ │ ├── commands/ # server, bot, start, config, workspace, channel\n│ │ └── index.ts # CLI entry point\n│ └── package.json\n│\n├── turbo.json # Turborepo pipeline config\n├── tsconfig.base.json # Shared TypeScript strict config\n├── eslint.config.js # ESLint 10 flat config\n├── .env.example # Environment variable template\n└── package.json # Monorepo root\n```\n\n---\n\n## Packages\n\n### Core (`@ownpilot/core`)\n\nThe foundational runtime library. Contains the AI engine, tool system, plugin architecture, security primitives, and cryptography. Minimal dependencies (only `googleapis` for Google OAuth).\n\n**~72,000 LOC** across 251 source files.\n\n| Module | Description |\n| ------------------ | ------------------------------------------------------------------------------------------------ |\n| `agent/` | Agent engine with multi-provider support, orchestrator, tool-calling loop |\n| `agent/orchestra/` | Multi-agent orchestration (fan-out, race, pipeline, voting strategies) |\n| `agent/providers/` | Provider implementations (OpenAI, Anthropic, Google, Zhipu, OpenAI-compatible, 8 aggregators) |\n| `agent/tools/` | 250+ built-in tool definitions across 31 tool files |\n| `plugins/` | Plugin system with isolation, marketplace, signing, runtime |\n| `events/` | 3-in-1 event system: EventBus (fire-and-forget), HookBus (interceptable), ScopedBus (namespaced) |\n| `services/` | Service registry (DI container) with typed tokens |\n| `memory/` | AES-256-GCM encrypted personal memory with vector search and deduplication |\n| `sandbox/` | 5 sandbox implementations: VM, Docker, Worker threads, Local, Scoped APIs |\n| `crypto/` | PBKDF2, AES-256-GCM, RSA, SHA256 — zero dependency |\n| `audit/` | Tamper-evident logging with hash chain verification |\n| `privacy/` | PII detection (15+ categories) and redaction |\n| `security/` | Critical pattern blocking (100+ patterns), permission matrix |\n| `channels/` | Channel plugin architecture, Universal Channel Protocol (UCP) |\n| `edge/` | Edge device types (sensors, actuators, telemetry, commands) |\n| `types/` | Result\u003cT,E\u003e pattern, branded types, error classes, type guards |\n\n### Gateway (`@ownpilot/gateway`)\n\nThe API server built on [Hono](https://hono.dev/). Handles HTTP/WebSocket communication, database operations, agent execution, MCP integration, plugin management, and channel connectivity.\n\n**~144,000 LOC** across 460 source files. **388 test files** with **16,294+ tests**.\n\n**Route Modules (115 handlers):**\n\n| Category | Routes |\n| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Chat \u0026 Agents** | `chat.ts`, `chat-history.ts`, `agents.ts`, `chat-streaming.ts`, `chat-persistence.ts`, `chat-state.ts`, `chat-prompt.ts` |\n| **AI Configuration** | `models.ts`, `providers.ts`, `model-configs.ts`, `local-providers.ts`, `model-routing.ts` |\n| **Personal Data** | `personal-data.ts`, `personal-data-tools.ts`, `memories.ts`, `goals.ts`, `expenses.ts`, `custom-data.ts` |\n| **Productivity** | `productivity.ts` (Pomodoro, Habits, Captures) |\n| **Automation** | `triggers.ts`, `heartbeats.ts`, `plans.ts`, `autonomy.ts`, `workflows.ts`, `workflow-copilot.ts`, `souls.ts` |\n| **Tools \u0026 Extensions** | `tools.ts`, `custom-tools.ts`, `plugins.ts`, `extensions.ts`, `skills.ts`, `mcp.ts`, `composio.ts` |\n| **Coding \u0026 CLI** | `coding-agents.ts`, `cli-tools.ts`, `cli-providers.ts` |\n| **Orchestration** | `orchestra.ts`, `artifacts.ts`, `browser.ts`, `voice.ts`, `bridges.ts` |\n| **Edge / IoT** | `edge.ts` (devices, commands, telemetry, MQTT status) |\n| **Channels** | `channels.ts`, `channel-auth.ts`, `webhooks.ts` |\n| **Configuration** | `settings.ts`, `config-services.ts`, `ui-auth.ts` |\n| **System** | `health.ts`, `dashboard.ts`, `costs.ts`, `audit.ts`, `debug.ts`, `database.ts`, `profile.ts`, `workspaces.ts`, `file-workspaces.ts`, `execution-permissions.ts`, `error-codes.ts` |\n\n**Services (108):** MessageBus, ConfigCenter, ToolExecutor, ProviderService, McpClientService, McpServerService, ExtensionService, ComposioService, EmbeddingService, HeartbeatService, AuditService, PluginService, MemoryService, GoalService, TriggerService, PlanService, WorkspaceService, DatabaseService, SessionService, LogService, ResourceService, LocalDiscovery, WorkflowService, AgentSkillsParser, CodingAgentService, CodingAgentSessions, CliToolService, CliToolsDiscovery, ModelRouting, ExecutionApproval, ClawManager, ClawRunner, ChannelVerificationService, OrchestraEngine, ArtifactService, ArtifactDataResolver, VoiceService, BrowserService, EdgeService, EdgeMqttClient, SubagentService, SubagentManager, SoulService, CrewService, AgentMessagesService, and more.\n\n**Repositories (67):** agents, conversations, messages, tasks, notes, bookmarks, calendar, contacts, memories, goals, triggers, plans, expenses, custom-data, custom-tools, plugins, channels, channel-messages, channel-users, channel-sessions, channel-verification, costs, settings, config-services, pomodoro, habits, captures, workspaces, model-configs, execution-permissions, logs, mcp-servers, extensions, local-providers, heartbeats, embedding-cache, workflows, autonomy-log, coding-agent-results, cli-providers, cli-tool-policies, claws, orchestra, artifacts, channel-bridges, browser-workflows, edge-devices, edge-commands, edge-telemetry, subagent-history, souls, crews, agent-messages.\n\n### UI (`@ownpilot/ui`)\n\nModern web interface built with React 19, Vite 7, and Tailwind CSS 4. Minimal dependencies — no Redux/Zustand, no axios, no component library.\n\n| Technology | Version |\n| -------------------- | ------- |\n| React | 19.2.4 |\n| React Router DOM | 7.1.3 |\n| Vite | 7.3.1 |\n| Tailwind CSS | 4.2.0 |\n| prism-react-renderer | 2.4.1 |\n\n**Pages (64):**\n\n| Page | Description |\n| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| **Chat** | Main AI conversation with streaming, tool execution display, context bar, approval dialogs |\n| **Dashboard** | Overview with stats, AI briefing, quick actions |\n| **Inbox** | Read-only channel messages from Telegram and WhatsApp |\n| **History** | Conversation history with search, archive, bulk operations |\n| **Tasks / Notes / Calendar / Contacts / Bookmarks** | Personal data management |\n| **Expenses** | Financial tracking with categories |\n| **Memories** | AI long-term memory browser |\n| **Goals** | Goal tracking with progress and step management |\n| **Triggers / Plans / Autonomy / Workflows** | Automation configuration |\n| **Coding Agents** | External AI coding CLI sessions (Claude Code, Codex, Gemini CLI) |\n| **Agents** | Agent selection and configuration |\n| **Tools / Custom Tools** | Tool browser and custom tool management |\n| **User Extensions** | Install and manage tool bundles with custom tools and configs |\n| **Skills** | Browse and install AgentSkills.io SKILL.md instruction packages |\n| **MCP Servers** | Manage external MCP server connections with preset quick-add |\n| **Tool Groups** | Configure tool group visibility and assignments |\n| **Connected Apps** | Composio OAuth integrations (1000+ apps) |\n| **Models / AI Models / Costs** | AI model browser, configuration, and usage tracking |\n| **Providers** | Provider management and status |\n| **Model Routing** | Per-process model selection with fallback chains |\n| **Autonomous Hub** | Unified command center for soul agents, claw agents, crews, messaging, and activity |\n| **Event Monitor** | Live EventBus event stream viewer for real-time debugging |\n| **Channels** | Channel management with connect/disconnect/logout, user approval, QR code display |\n| **Plugins / Workspaces / Wizards** | Extension management, workspace management, guided setup wizards |\n| **Artifacts** | Versioned document viewer with ArtifactCard grid and ArtifactRenderer |\n| **Edge Devices** | IoT device management with sensor readings, actuator control, MQTT status |\n| **Data Browser / Custom Data** | Universal data exploration and custom tables |\n| **Settings / Config Center / API Keys** | Service configuration, API key management |\n| **Coding Agent Settings / CLI Tools Settings** | Coding agent provider config, CLI tool policy management |\n| **Security** | UI authentication and password management |\n| **System** | Database backup/restore, sandbox status, theme, notifications |\n| **Profile / Logs / About** | User profile, request logs, system info |\n\n**Key Components (140):** Layout, ChatInput, MessageList, ContextBar, ContextDetailModal, ToolExecutionDisplay, TraceDisplay, CodeBlock, MarkdownContent, ExecutionApprovalDialog, ExecutionSecurityPanel, SuggestionChips, MemoryCards, WorkspaceSelector, ToastProvider, ConfirmDialog, DynamicConfigForm, ErrorBoundary, SetupWizard, and more.\n\n**State Management (Context + Hooks):**\n\n- `useChatStore` — Global chat state with SSE streaming, tool progress, approval flow\n- `useTheme` — Dark/light/system theme with localStorage persistence\n- `useWebSocket` — WebSocket connection with auto-reconnect and event subscriptions\n\n### CLI (`@ownpilot/cli`)\n\nCommand-line interface built with Commander.js and @inquirer/prompts.\n\n```bash\nownpilot setup # Initialize database\nownpilot start # Start server + bot\nownpilot server # Start HTTP API server only\nownpilot bot # Start Telegram bot only\n\n# Configuration (stored in PostgreSQL)\nownpilot config set \u003ckey\u003e [value] # Set credential or setting\nownpilot config get \u003ckey\u003e # Retrieve (masked for secrets)\nownpilot config delete \u003ckey\u003e # Remove\nownpilot config list # List all with status\n\n# Workspace management\nownpilot workspace list\nownpilot workspace create\nownpilot workspace delete [id]\nownpilot workspace switch [id]\n\n# Channel management\nownpilot channel list\nownpilot channel add\nownpilot channel remove [id]\nownpilot channel connect [id]\nownpilot channel disconnect [id]\n```\n\n**Configuration keys:** `\u003cprovider\u003e-api-key` (e.g., `openai-api-key`, `anthropic-api-key`), `default_ai_provider`, `default_ai_model`, `telegram_bot_token`, `gateway_api_keys`, `gateway_jwt_secret`, `gateway_auth_type`, `gateway_rate_limit_max`, `gateway_rate_limit_window_ms`.\n\n---\n\n## AI Providers\n\nAll API keys are managed via the **Config Center UI** (Settings page) or the `ownpilot config set` CLI command. They are stored in the PostgreSQL database, not in environment variables.\n\n### Supported Providers\n\n**104 providers** with auto-synced model catalogs from [models.dev](https://models.dev). Key providers:\n\n| Provider | Integration Type | Key Models |\n| ------------------ | ------------------------ | ----------------------------------------------------------------------- |\n| **OpenAI** | Native | GPT-5.3 Codex, GPT-5.2, GPT-5.1, o4-mini, o3 |\n| **Anthropic** | Native (prompt caching) | Claude Sonnet 4.6, Claude Opus 4.6, Claude Sonnet 4.5, Claude Haiku 4.5 |\n| **Google** | Native | Gemini 3.1 Pro, Gemini 3 Flash, Gemini 2.5 Flash/Pro |\n| **xAI** | Native | Grok 4.1 Fast, Grok 4, Grok 3 |\n| **DeepSeek** | Native | DeepSeek Chat, DeepSeek Reasoner |\n| **Mistral** | Native | Devstral 2, Mistral Medium 3.1, Mistral Large 3, Codestral |\n| **Zhipu AI** | Native | GLM-5, GLM-4.7, GLM-4.6 |\n| **Cohere** | Native | Command A, Command A Reasoning, Command R+ |\n| **Together AI** | Aggregator | Qwen3.5 397B, GLM-5, Kimi K2.5, DeepSeek V3.1 |\n| **Groq** | Aggregator (LPU) | Kimi K2, GPT OSS 120B, Llama 4 Scout, Qwen3 32B |\n| **Fireworks AI** | Aggregator | MiniMax-M2.5, GLM 5, Kimi K2.5, DeepSeek V3.2 |\n| **DeepInfra** | Aggregator | Kimi K2.5, GLM-4.7, DeepSeek-V3.2, Qwen3 Coder |\n| **OpenRouter** | Aggregator (161+ models) | Unified API for all providers |\n| **Perplexity** | Aggregator | Sonar Deep Research, Sonar Pro, Sonar Reasoning Pro |\n| **Cerebras** | Aggregator (fastest) | GLM-4.7, GPT OSS 120B, Qwen 3 235B |\n| **NVIDIA** | Aggregator (65+ models) | GLM5, Kimi K2.5, DeepSeek V3.2, Nemotron |\n| **Amazon Bedrock** | Cloud (96+ models) | Claude 4.6, DeepSeek-V3.2, Kimi K2.5, Nova Pro |\n| **Azure** | Cloud (85+ models) | GPT-5.2, Claude 4.6, DeepSeek-V3.2, Grok 4 |\n| **GitHub Models** | Cloud | GPT-4.1, DeepSeek-R1, Llama 4, Mistral |\n| **Hugging Face** | Aggregator | MiniMax-M2.5, GLM-5, Qwen3.5, DeepSeek-V3.2 |\n| **SiliconFlow** | Aggregator (66+ models) | GLM-5, Kimi K2.5, DeepSeek V3.2, Qwen3 VL |\n| **Novita AI** | Aggregator (80+ models) | Qwen3.5, GLM-5, Kimi K2.5, ERNIE-4.5 |\n| **Nebius** | Aggregator (45+ models) | DeepSeek-V3.2, GLM-4.7, Qwen3, FLUX |\n| **Ollama** | Local | qwen3.5, minimax-m2.5, glm-5, kimi-k2.5 |\n| **LM Studio** | Local | GPT OSS 20B, Qwen3 30B, Qwen3 Coder 30B |\n\nAny OpenAI-compatible endpoint can be added as a custom provider.\n\n### Provider Routing Strategies\n\n| Strategy | Description |\n| ---------- | --------------------------------------------- |\n| `cheapest` | Minimize API costs |\n| `fastest` | Minimize latency |\n| `smartest` | Best quality/reasoning |\n| `balanced` | Cost + quality balance (default) |\n| `fallback` | Try providers sequentially until one succeeds |\n\n### Token Efficiency\n\n- **Anthropic Prompt Caching** — Static system prompt sections (persona, tools, capabilities) marked with `cache_control: { type: 'ephemeral' }`. Dynamic sections (current context, code execution) sent without caching. Reduces input token costs on multi-turn conversations.\n- **Context Compaction** — When context grows large, old messages can be AI-summarized into a compact summary, preserving recent messages. Reduces token usage while maintaining conversation continuity.\n- **Meta-tool Proxy** — Only 4 small tool definitions sent to the LLM instead of 250+ full schemas.\n\n---\n\n## Agent System\n\nAgents are AI assistants with specific system prompts, tool assignments, model preferences, and execution limits.\n\n### Agent Configuration\n\n```typescript\n{\n name: string // Display name\n systemPrompt: string // Custom instructions\n provider: string // AI provider (or 'default')\n model: string // Model ID (or 'default')\n config: {\n maxTokens: number // Max response tokens\n temperature: number // Creativity (0-2)\n maxTurns: number // Max conversation turns\n maxToolCalls: number // Max tool calls per turn\n tools?: string[] // Specific tool names\n toolGroups?: string[] // Tool group names\n }\n}\n```\n\n### Agent Capabilities\n\n- **Tool Orchestration** — Automatic tool calling with multi-step planning via meta-tool proxy\n- **Memory Injection** — Relevant memories automatically included in system prompt (vector + full-text hybrid search)\n- **Goal Awareness** — Active goals and progress injected into context\n- **Dynamic System Prompts** — Context-aware enhancement with memories, goals, available resources\n- **Execution Context** — Code execution instructions injected into system prompt (not user message)\n- **Context Tracking** — Real-time context bar showing token usage, fill percentage, and per-section breakdown\n- **Streaming** — Real-time SSE responses with tool execution progress events\n\n---\n\n## Soul Agents\n\nSoul agents are autonomous agents with rich identity, personality, and heartbeat-driven lifecycle. They combine scheduling with a full identity framework.\n\n### Soul Configuration\n\n```typescript\n{\n agentId: string // Unique agent ID\n identity: {\n name: string // Display name\n emoji: string // Agent emoji\n role: string // Professional role\n personality: string // Personality description\n voice: { tone, language } // Communication style\n boundaries: string[] // Behavioral constraints\n }\n purpose: {\n mission: string // Core mission statement\n goals: string[] // Active goals\n expertise: string[] // Domain expertise\n toolPreferences: string[] // Preferred tools\n }\n autonomy: {\n level: 1-4 // Autonomy level\n allowedActions: string[] // Permitted actions\n blockedActions: string[] // Blocked actions\n requiresApproval: string[] // Actions needing user approval\n maxCostPerCycle: number // Budget per heartbeat cycle\n maxCostPerDay: number // Daily budget limit\n maxCostPerMonth: number // Monthly budget limit\n }\n heartbeat: {\n enabled: boolean // Enable scheduled execution\n interval: string // Cron expression\n checklist: string[] // Tasks to run each cycle\n selfHealingEnabled: boolean\n maxDurationMs: number // Cycle timeout\n }\n relationships: {\n delegates: string[] // Agents this soul can delegate to\n peers: string[] // Peer agents\n channels: string[] // Communication channels\n }\n}\n```\n\n### Crews\n\nMulti-agent crews coordinate soul agents for complex tasks:\n\n- **Role Assignment** — Each crew member has a defined role within the crew\n- **Delegation Protocol** — Automatic task delegation between crew members\n- **Crew Templates** — Pre-built crew configurations for common multi-agent workflows\n\n---\n\n## Autonomous Hub\n\nThe Autonomous Hub is a unified command center for managing all autonomous agents from a single interface.\n\n### Tabs\n\n| Tab | Description |\n| ------------ | ------------------------------------------------------------------------------------------ |\n| **Agents** | Grid of all agents (soul + background) with search, status/type filters, and quick actions |\n| **Crews** | Crew management with templates and member configuration |\n| **Messages** | Inter-agent communication panel with compose and message history |\n| **Activity** | Unified timeline of heartbeat logs and agent messages with stats |\n\n### AI Agent Creator\n\nDescribe what you want in plain English and the AI designs the agent configuration:\n\n1. Open the AI Creator modal from the hub header\n2. Describe your agent (e.g., \"Monitor my GitHub PRs daily\")\n3. The AI designs a configuration with name, mission, schedule, tools, and cost estimate\n4. Review the preview card and refine through conversation\n5. Click \"Create This Agent\" to deploy\n\nThe creator uses a dedicated agent with a specialized system prompt, ensuring it acts as an agent designer rather than a general chatbot.\n\n---\n\n## Subagents\n\nEphemeral child agents for parallel task delegation. Unlike claw agents (which are persistent and cycle-based), subagents run once to completion and are discarded.\n\n### How It Works\n\n```\nParent Agent (chat or claw agent)\n ├─ spawn_subagent(\"Research pricing\") → SubagentRunner #1\n ├─ spawn_subagent(\"Analyze competitors\") → SubagentRunner #2\n ├─ spawn_subagent(\"Draft summary\") → SubagentRunner #3\n │\n ├─ check_subagent(#1) → running...\n ├─ get_subagent_result(#1) → \"Pricing analysis: ...\"\n └─ Synthesize final answer from all results\n```\n\n### LLM Tools\n\n| Tool | Description |\n| --------------------- | ------------------------------------------------ |\n| `spawn_subagent` | Spawn an autonomous subagent for a specific task |\n| `check_subagent` | Check the status of a running subagent |\n| `get_subagent_result` | Get the final result of a completed subagent |\n| `cancel_subagent` | Cancel a running subagent |\n| `list_subagents` | List all subagents in the current session |\n\n### Session Lifecycle\n\n| State | Description |\n| ----------- | ------------------------- |\n| `pending` | Created, waiting to start |\n| `running` | Actively executing |\n| `completed` | Finished successfully |\n| `failed` | Encountered an error |\n| `cancelled` | Cancelled by parent |\n| `timeout` | Exceeded time limit |\n\n### Budget \u0026 Limits\n\n| Setting | Default | Description |\n| ---------------- | ------- | ------------------------------------------- |\n| `maxConcurrent` | 5 | Max active subagents per parent |\n| `maxTotalSpawns` | 20 | Total spawn limit per session |\n| `maxTurns` | 20 | Max LLM round-trips per subagent |\n| `maxToolCalls` | 100 | Max tool invocations per subagent |\n| `timeoutMs` | 120,000 | Per-subagent timeout (2 min) |\n| Nesting depth | 2 | Subagents can spawn sub-subagents (1 level) |\n\n---\n\n## Tool System\n\n### Overview\n\nOwnPilot has **250+ tools** organized into **32 categories**. Rather than sending all tool definitions to the LLM (which would consume too many tokens), OwnPilot uses a **meta-tool proxy pattern**:\n\n1. **`search_tools`** — Find tools by keyword with optional `include_params` for inline parameter schemas\n2. **`get_tool_help`** — Get detailed help for a specific tool (supports batch lookup)\n3. **`use_tool`** — Execute a tool with parameter validation and limit enforcement\n4. **`batch_use_tool`** — Execute multiple tools in a single call\n\n### Tool Categories\n\n| Category | Examples |\n| -------------------- | ------------------------------------------------------------------------ |\n| **Tasks** | add_task, list_tasks, complete_task, update_task, delete_task |\n| **Notes** | add_note, list_notes, update_note, delete_note |\n| **Calendar** | add_calendar_event, list_calendar_events, delete_calendar_event |\n| **Contacts** | add_contact, list_contacts, update_contact, delete_contact |\n| **Bookmarks** | add_bookmark, list_bookmarks, delete_bookmark |\n| **Custom Data** | create_custom_table, add_custom_record, search_custom_records |\n| **File System** | read_file, write_file, list_directory, search_files, copy_file |\n| **PDF** | read_pdf, create_pdf, pdf_info |\n| **Code Execution** | execute_javascript, execute_python, execute_shell, compile_code |\n| **Web \u0026 API** | http_request, fetch_web_page, search_web |\n| **Email** | send_email, list_emails, read_email, search_emails |\n| **Image** | analyze_image, resize_image |\n| **Audio** | audio_info, translate_audio |\n| **Finance** | add_expense, query_expenses, expense_summary |\n| **Memory** | remember, recall, forget, list_memories, memory_stats |\n| **Goals** | create_goal, list_goals, decompose_goal, get_next_actions, complete_step |\n| **Git** | git_status, git_log, git_diff, git_commit, git_branch |\n| **Translation** | translate_text, detect_language |\n| **Weather** | get_weather, weather_forecast |\n| **Data Extraction** | extract_structured_data, parse_document |\n| **Vector Search** | semantic_search, index_documents |\n| **Scheduler** | schedule_task, list_scheduled |\n| **Utilities (Math)** | calculate, statistics, convert_units |\n| **Utilities (Text)** | regex, word_count, text_transform |\n| **Utilities (Date)** | date_math, format_date, timezone_convert |\n| **Utilities (Data)** | json_query, csv_parse, data_transform |\n| **Utilities (Gen)** | generate_uuid, hash_text, random_number |\n| **CLI Tools** | run_cli_tool, list_cli_tools, install_cli_tool |\n| **Coding Agents** | run_coding_task, list_coding_agents, get_task_result |\n| **Orchestra** | create_orchestra, run_orchestra, get_orchestra_result |\n| **Artifacts** | create_artifact, update_artifact, list_artifacts, get_artifact |\n| **Browser** | browser_navigate, browser_click, browser_type, browser_screenshot |\n| **Edge Devices** | list_edge_devices, get_device_status, read_sensor, control_actuator |\n| **Dynamic Tools** | create_tool, list_custom_tools, delete_custom_tool |\n\n### Tool Namespaces\n\nAll tools use qualified names with dot-prefixed namespaces:\n\n| Prefix | Source | Example |\n| --------------- | --------------------- | ------------------------------ |\n| `core.` | Built-in tools | `core.add_task` |\n| `custom.` | User-created tools | `custom.my_helper` |\n| `plugin.{id}.` | Plugin tools | `plugin.telegram.send_message` |\n| `skill.{id}.` | Extension/skill tools | `skill.web-scraper.scrape` |\n| `mcp.{server}.` | MCP server tools | `mcp.filesystem.read_file` |\n\nThe LLM can use base names (without prefix) for backward compatibility — the registry resolves them automatically.\n\n### Tool Trust Levels\n\n| Level | Source | Behavior |\n| -------------- | -------------------- | ------------------------------------- |\n| `trusted` | Core tools | Full access |\n| `semi-trusted` | Plugin tools | Require explicit permission |\n| `sandboxed` | Custom/dynamic tools | Strict validation + sandbox execution |\n\n### Custom Tools (LLM-Created)\n\nThe AI can create new tools at runtime:\n\n1. LLM calls `create_tool` with name, description, parameters, and JavaScript code\n2. Tool is validated, sandboxed, and stored in the database\n3. Tool is available to all agents via `use_tool`\n4. Tools can be enabled/disabled and have permission controls\n\n---\n\n## MCP Integration\n\nOwnPilot supports the [Model Context Protocol](https://modelcontextprotocol.io/) in both directions:\n\n### MCP Client (connect to external servers)\n\nConnect to any MCP server to extend OwnPilot's capabilities:\n\n```\nSettings → MCP Servers → Add (or use Quick Add presets)\n```\n\n**Pre-configured presets:**\n\n- **Filesystem** — Read, write, and manage local files\n- **GitHub** — Manage repos, issues, PRs, and branches\n- **Brave Search** — Web and local search\n- **Fetch** — Extract content from web pages\n- **Memory** — Persistent knowledge graph\n- **Sequential Thinking** — Structured problem-solving\n\nTools from connected MCP servers appear in the AI's catalog with `mcp.{servername}.` prefix and are available via `search_tools` / `use_tool`.\n\n### MCP Server (expose tools to external clients)\n\nOwnPilot exposes its full tool registry as an MCP endpoint:\n\n```\nPOST /mcp/serve — Streamable HTTP transport\n```\n\nExternal MCP clients (Claude Desktop, other agents) can connect and use OwnPilot's 250+ tools.\n\n---\n\n## Artifacts\n\nVersioned document management for AI-created content — markdown, code, JSON, HTML, CSV, SVG, and Mermaid diagrams.\n\n### Features\n\n- **Version Tracking** — Every update creates a new version with content diffs\n- **Data Binding** — Expressions like `{{conversation.summary}}` that auto-resolve from context\n- **Rendering Pipeline** — ArtifactRenderer component renders each content type natively (syntax highlighting for code, Mermaid→SVG for diagrams)\n- **Dashboard Widget** — Recent artifacts shown on the Dashboard page\n\n### LLM Tools\n\n| Tool | Description |\n| ----------------- | ------------------------------- |\n| `create_artifact` | Create a new versioned document |\n| `update_artifact` | Update content (creates diff) |\n| `list_artifacts` | List all artifacts |\n| `get_artifact` | Get artifact with version info |\n| `delete_artifact` | Delete an artifact |\n\n---\n\n## Voice Pipeline\n\nSpeech-to-text and text-to-speech integration for voice-powered AI interactions.\n\n- **STT (Whisper)** — Transcribe audio files or microphone input via OpenAI Whisper API\n- **TTS (OpenAI)** — Generate speech from AI responses with 6 voice options (alloy, echo, fable, onyx, nova, shimmer)\n- **VoiceButton** — Microphone recording UI in the ChatInput component\n- **VoicePlayButton** — Inline playback button on AI responses\n- **Channel Support** — WhatsApp voice messages auto-transcribed via channel normalizer\n\n---\n\n## Browser Agent\n\nHeadless Chromium automation via Playwright for AI-driven web browsing and data extraction.\n\n### LLM Tools\n\n| Tool | Description |\n| -------------------- | ---------------------------------------- |\n| `browser_navigate` | Navigate to a URL |\n| `browser_click` | Click an element by selector |\n| `browser_type` | Type text into an input |\n| `browser_screenshot` | Capture a screenshot of the current page |\n| `browser_evaluate` | Execute JavaScript in the page context |\n| `browser_extract` | Extract structured content from the page |\n| `browser_fill_form` | Fill out a form with multiple fields |\n\n### Features\n\n- **Workflow Persistence** — Browser workflows stored in DB for replay and audit\n- **Session Management** — Isolated browser contexts per session\n- **REST API** — Full CRUD at `/api/v1/browser` plus workflow execution\n\n---\n\n## Edge Devices\n\nMQTT-based IoT/edge device management. OwnPilot acts as the brain; cheap edge hardware (ESP32, Raspberry Pi) acts as the hands.\n\n### Architecture\n\n```\nEdge Device (ESP32/RPi/Arduino)\n │\n │ MQTT (lightweight pub/sub)\n │\n ├── ownpilot/{userId}/devices/{deviceId}/telemetry → Server\n ├── ownpilot/{userId}/devices/{deviceId}/commands ← Server\n └── ownpilot/{userId}/devices/{deviceId}/status → Server (LWT)\n │\nMosquitto Broker ←→ OwnPilot Gateway (EdgeMqttClient)\n```\n\n### Device Types\n\n| Type | Hardware |\n| -------------- | ------------------------- |\n| `raspberry-pi` | Raspberry Pi (any model) |\n| `esp32` | Espressif ESP32 boards |\n| `arduino` | Arduino-compatible boards |\n| `custom` | Any custom hardware |\n\n### Sensor \u0026 Actuator Types\n\n**Sensors:** temperature, humidity, motion, light, pressure, camera, door, custom\n**Actuators:** relay, servo, LED, buzzer, display, motor, custom\n\n### LLM Tools\n\n| Tool | Description |\n| ---------------------- | ----------------------------------------- |\n| `list_edge_devices` | List all registered IoT devices |\n| `get_device_status` | Get device status, sensors, and actuators |\n| `read_sensor` | Read latest value from a sensor |\n| `send_device_command` | Send a command to a device via MQTT |\n| `control_actuator` | Set state on an actuator |\n| `register_edge_device` | Register a new edge device |\n\n### REST API\n\n10 endpoints at `/api/v1/edge` — device CRUD, commands, telemetry, MQTT status.\n\n---\n\n## Personal Data\n\n### Entity Types\n\n| Entity | Key Features |\n| ------------------- | ------------------------------------------------------------------------------------ |\n| **Tasks** | Priority (1-5), due date, category, status (pending/in_progress/completed/cancelled) |\n| **Notes** | Title, content (markdown), tags, category |\n| **Bookmarks** | URL, title, description, category, tags, favicon |\n| **Calendar Events** | Title, start/end time, location, attendees, RSVP status |\n| **Contacts** | Name, email, phone, address, organization, notes |\n| **Expenses** | Amount, category, description, date, tags |\n| **Custom Data** | User-defined tables with AI-determined schemas |\n\n### Memory System\n\nPersistent long-term memory for the AI assistant with AES-256-GCM encryption:\n\n| Memory Type | Description |\n| -------------- | ---------------------------------- |\n| `fact` | Factual information about the user |\n| `preference` | User preferences and settings |\n| `conversation` | Key conversation takeaways |\n| `context` | Contextual information |\n| `task` | Task-related memory |\n| `relationship` | People and contacts |\n| `temporal` | Time-based reminders |\n\nMemories have **importance scoring**, are **automatically injected** into agent system prompts via hybrid search (vector + full-text + RRF ranking), support **deduplication** via content hash, and have optional **TTL expiration**.\n\n### Goals System\n\nHierarchical goal tracking with decomposition:\n\n- **Create goals** with title, description, due date\n- **Decompose** into actionable steps (pending, in_progress, completed, skipped)\n- **Track progress** (0-100%) with status (active/completed/abandoned)\n- **Get next actions** — AI recommends what to do next\n- **Complete steps** — Auto-update parent goal progress\n\n---\n\n## Autonomy \u0026 Automation\n\n### Autonomy Levels\n\n| Level | Name | Description |\n| ----- | -------------- | -------------------------------------------- |\n| 0 | **Manual** | Always ask before any action |\n| 1 | **Assisted** | Suggest actions, wait for approval (default) |\n| 2 | **Supervised** | Auto-execute low-risk, ask for high-risk |\n| 3 | **Autonomous** | Execute all actions, notify user |\n| 4 | **Full** | Fully autonomous, minimal notifications |\n\n### Triggers\n\nProactive automation with 4 trigger types:\n\n| Type | Description | Example |\n| ----------- | ---------------------- | ------------------------------------------ |\n| `schedule` | Cron-based timing | \"Every Monday at 9am, summarize my week\" |\n| `event` | Fired on data changes | \"When a new task is added, notify me\" |\n| `condition` | IF-THEN rules | \"If expenses \u003e $500/day, alert me\" |\n| `webhook` | External HTTP triggers | \"When GitHub webhook fires, create a task\" |\n\n### Heartbeats\n\nNatural language periodic scheduling:\n\n```\n\"every weekday at 9am\" → 0 9 * * 1-5\n\"twice a day\" → 0 9,18 * * *\n\"every 30 minutes\" → */30 * * * *\n```\n\nThe AI parses natural language into cron expressions for trigger scheduling.\n\n### Plans\n\nMulti-step autonomous execution:\n\n- **Step types**: tool, parallel, loop, conditional, wait, pause\n- **Status tracking**: draft, running, paused, completed, failed, cancelled\n- **Timeout and retry** logic with configurable backoff\n- **Step dependencies** for execution ordering\n\n### Workflows\n\nVisual multi-step automation with a workflow editor:\n\n- **Drag-and-drop** workflow builder in the web UI\n- **Step types**: prompt, tool, conditional, loop\n- **Workflow Copilot** — AI-assisted workflow creation and editing\n- **Execution logs** with per-step status tracking\n\n---\n\n## Database\n\nPostgreSQL with 85+ repositories via the `pg` adapter.\n\n### Key Tables\n\n**Core:** `conversations`, `messages`, `agents`, `settings`, `costs`, `request_logs`\n\n**Personal Data:** `tasks`, `notes`, `bookmarks`, `calendar_events`, `contacts`, `expenses`\n\n**Productivity:** `pomodoro_sessions`, `habits`, `captures`\n\n**Autonomous AI:** `memories`, `goals`, `triggers`, `plans`, `heartbeats`, `workflows`, `autonomy_log`, `souls`, `crews`, `agent_messages`, `claws`, `claw_sessions`, `claw_history`, `claw_audit_log`\n\n**Channels:** `channel_messages`, `channel_users`, `channel_sessions`, `channel_verification`\n\n**Extensions:** `plugins`, `custom_tools`, `user_extensions`, `mcp_servers`, `embedding_cache`\n\n**Coding \u0026 CLI:** `coding_agent_results`, `cli_providers`, `cli_tool_policies`\n\n**System:** `custom_data_tables`, `config_services`, `execution_permissions`, `workspaces`, `model_configs`, `local_providers`\n\n### Migration\n\nSchema migrations are auto-applied on startup via `autoMigrateIfNeeded()`. Migration files are in `packages/gateway/src/db/migrations/`.\n\n### Backup \u0026 Restore\n\n```\nSystem → Database → Backup / Restore\n```\n\nFull PostgreSQL backup and restore through the web UI or API.\n\n---\n\n## Security \u0026 Privacy\n\n### 4-Layer Security Model\n\n| Layer | Purpose |\n| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| **Critical Patterns** | 100+ regex patterns unconditionally blocked (rm -rf /, fork bombs, registry deletion, etc.) |\n| **Permission Matrix** | Per-category modes: blocked, prompt, allowed (execute_javascript, execute_python, execute_shell, compile_code, package_manager) |\n| **Approval Callback** | Real-time user approval for sensitive operations via SSE (2-minute timeout) |\n| **Sandbox Isolation** | VM, Docker, Worker threads, or Local execution with resource limits |\n\n### Credential Management\n\nAPI keys and settings are stored in the PostgreSQL database via the Config Center system. The web UI settings page and `ownpilot config` CLI both write to the same database.\n\nKeys are loaded into `process.env` at server startup for provider SDK compatibility.\n\n### PII Detection\n\n- 15+ detection categories: SSN, credit cards, emails, phone numbers, IP addresses, passport, etc.\n- Configurable redaction modes: mask, label, remove\n- Severity-based filtering\n\n### Code Execution\n\nOwnPilot can execute code on behalf of the AI through 5 execution tools:\n\n| Tool | Description |\n| -------------------- | -------------------------------------- |\n| `execute_javascript` | Run JavaScript/TypeScript via Node.js |\n| `execute_python` | Run Python scripts |\n| `execute_shell` | Run shell commands (bash/PowerShell) |\n| `compile_code` | Compile and run C, C++, Rust, Go, Java |\n| `package_manager` | Install packages via npm/pip |\n\n#### Execution Modes\n\n| Mode | Behavior |\n| ---------- | ------------------------------------------------------------------------------------- |\n| **docker** | All code runs inside isolated Docker containers (most secure) |\n| **local** | Code runs directly on the host machine (requires approval for non-allowed categories) |\n| **auto** | Tries Docker first, falls back to local if Docker is unavailable |\n\n#### Docker Sandbox Security\n\nWhen using Docker mode, each execution runs in a container with strict isolation:\n\n- `--read-only` filesystem (writable `/tmp` only)\n- `--network=none` (no network access)\n- `--user=65534:65534` (nobody user)\n- `--no-new-privileges`\n- `--cap-drop=ALL` (no Linux capabilities)\n- `--memory=256m` limit\n- `--cpus=1` limit\n- `--pids-limit=100`\n- Configurable timeout with automatic cleanup\n\n#### Local Executor Security\n\nWhen running locally (without Docker), the local executor applies:\n\n- **Environment sanitization** — strips API keys and sensitive variables from the child process\n- **Timeout enforcement** — SIGKILL after configured timeout\n- **Output truncation** — 1MB output limit to prevent memory exhaustion\n\n#### Permission System\n\nCode execution is governed by a per-category permission matrix:\n\n| Permission | Behavior |\n| ---------- | ---------------------------------------------------------------- |\n| `blocked` | Execution is denied |\n| `prompt` | User must approve via real-time dialog before execution proceeds |\n| `allowed` | Execution proceeds without approval |\n\nCategories: `execute_javascript`, `execute_python`, `execute_shell`, `compile_code`, `package_manager`\n\nA **master switch** (`enabled` boolean) can disable all code execution globally.\n\n#### Approval Flow\n\nWhen a tool's permission is set to `prompt`:\n\n1. Gateway sends an SSE `approval_required` event to the web UI\n2. UI shows an approval dialog with the code to be executed\n3. User approves or rejects via `POST /api/v1/execution-permissions/approvals/{id}/resolve`\n4. Execution proceeds or is cancelled (120-second timeout, auto-reject on expiry)\n\n#### Critical Pattern Blocking\n\nRegardless of permission settings, 100+ regex patterns are **unconditionally blocked**:\n\n- Filesystem destruction (`rm -rf /`, `format C:`, `del /f /s`)\n- Fork bombs and system control\n- Registry/credential access (Windows registry, `/etc/shadow`)\n- Remote code execution (`curl | bash`, `eval(fetch(...))`)\n- Package manager abuse (`npm publish`, `pip install` to system)\n\n### Authentication\n\n| Mode | Description |\n| ----------- | ---------------------------------------------------------- |\n| **None** | No authentication (default, development only) |\n| **API Key** | Bearer token or `X-API-Key` header, timing-safe comparison |\n| **JWT** | HS256/HS384/HS512 via `jose`, requires `sub` claim |\n\n### Rate Limiting\n\nSliding window algorithm with configurable window (default 60s), max requests (default 500), and burst limit (default 750). Per-IP tracking with `X-RateLimit-*` response headers.\n\n---\n\n## API Reference\n\n### Chat\n\n| Method | Endpoint | Description |\n| -------- | ----------------------------------- | ------------------------------------------- |\n| `POST` | `/api/v1/chat` | Send message (supports SSE streaming) |\n| `POST` | `/api/v1/chat/reset-context` | Reset conversation context |\n| `GET` | `/api/v1/chat/context-detail` | Get detailed context token breakdown |\n| `POST` | `/api/v1/chat/compact` | Compact context by summarizing old messages |\n| `GET` | `/api/v1/chat/history` | List conversations |\n| `GET` | `/api/v1/chat/history/:id` | Get conversation with messages |\n| `DELETE` | `/api/v1/chat/history/:id` | Delete conversation |\n| `PATCH` | `/api/v1/chat/history/:id/archive` | Archive/unarchive conversation |\n| `POST` | `/api/v1/chat/history/bulk-delete` | Bulk delete conversations |\n| `POST` | `/api/v1/chat/history/bulk-archive` | Bulk archive conversations |\n\n### Agents\n\n| Method | Endpoint | Description |\n| -------- | ------------------------- | ------------------------------ |\n| `GET` | `/api/v1/agents` | List all agents |\n| `POST` | `/api/v1/agents` | Create new agent |\n| `GET` | `/api/v1/agents/:id` | Get agent details |\n| `PUT` | `/api/v1/agents/:id` | Update agent |\n| `DELETE` | `/api/v1/agents/:id` | Delete agent |\n| `POST` | `/api/v1/agents/:id/chat` | Send message to specific agent |\n\n### AI Configuration\n\n| Method | Endpoint | Description |\n| ------ | ------------------------- | ------------------------------------------ |\n| `GET` | `/api/v1/models` | List available models across all providers |\n| `GET` | `/api/v1/providers` | List providers with status |\n| `GET` | `/api/v1/model-configs` | List model configurations |\n| `GET` | `/api/v1/local-providers` | List discovered local providers |\n| `GET` | `/api/v1/tools` | List all registered tools |\n| `GET` | `/api/v1/costs` | Cost tracking and usage stats |\n\n### Personal Data\n\n| Method | Endpoint | Description |\n| ---------- | --------------------- | ----------------------- |\n| `GET/POST` | `/api/v1/tasks` | Tasks CRUD |\n| `GET/POST` | `/api/v1/notes` | Notes CRUD |\n| `GET/POST` | `/api/v1/bookmarks` | Bookmarks CRUD |\n| `GET/POST` | `/api/v1/calendar` | Calendar events CRUD |\n| `GET/POST` | `/api/v1/contacts` | Contacts CRUD |\n| `GET/POST` | `/api/v1/expenses` | Expenses CRUD |\n| `GET/POST` | `/api/v1/memories` | Memories CRUD |\n| `GET/POST` | `/api/v1/goals` | Goals CRUD |\n| `GET/POST` | `/api/v1/custom-data` | Custom data tables CRUD |\n\n### Automation\n\n| Method | Endpoint | Description |\n| ---------- | -------------------- | -------------------- |\n| `GET/POST` | `/api/v1/triggers` | Trigger management |\n| `GET/POST` | `/api/v1/heartbeats` | Heartbeat scheduling |\n| `GET/POST` | `/api/v1/plans` | Plan management |\n| `GET/POST` | `/api/v1/workflows` | Workflow management |\n| `GET/PUT` | `/api/v1/autonomy` | Autonomy settings |\n\n### Extensions\n\n| Method | Endpoint | Description |\n| ---------- | ---------------------- | ------------------------------------- |\n| `GET/POST` | `/api/v1/mcp` | MCP server management |\n| `POST` | `/mcp/serve` | MCP server endpoint (Streamable HTTP) |\n| `GET/POST` | `/api/v1/extensions` | User extension and skill management |\n| `GET/POST` | `/api/v1/plugins` | Plugin management |\n| `GET/POST` | `/api/v1/custom-tools` | Custom tool management |\n| `GET/POST` | `/api/v1/composio` | Connected apps (Composio) |\n\n### Coding Agents\n\n| Method | Endpoint | Description |\n| -------- | ------------------------------------ | -------------------------------- |\n| `GET` | `/api/v1/coding-agents/providers` | List available coding agent CLIs |\n| `POST` | `/api/v1/coding-agents/execute` | Execute a coding agent task |\n| `GET` | `/api/v1/coding-agents/sessions` | List active sessions |\n| `DELETE` | `/api/v1/coding-agents/sessions/:id` | Stop a running session |\n| `GET` | `/api/v1/coding-agents/results` | List past execution results |\n\n### Soul Agents\n\n| Method | Endpoint | Description |\n| -------- | ------------------------------------ | ---------------------------------- |\n| `GET` | `/api/v1/souls` | List all soul agents |\n| `POST` | `/api/v1/souls` | Create a new soul agent |\n| `GET` | `/api/v1/souls/:id` | Get soul agent details |\n| `PUT` | `/api/v1/souls/:id` | Update soul agent config |\n| `DELETE` | `/api/v1/souls/:id` | Delete soul agent |\n| `GET` | `/api/v1/souls/crews` | List all crews |\n| `GET` | `/api/v1/souls/crews/templates` | List crew templates |\n| `GET` | `/api/v1/souls/heartbeat-logs` | Paginated heartbeat execution logs |\n| `GET` | `/api/v1/souls/heartbeat-logs/stats` | Heartbeat statistics |\n| `GET` | `/api/v1/souls/messages` | List inter-agent messages |\n| `POST` | `/api/v1/souls/messages` | Send a message between agents |\n\n### Claw Agents\n\n| Method | Endpoint | Description |\n| -------- | -------------------------------------- | ----------------------------------- |\n| `GET` | `/api/v1/claws` | List all claws with session status |\n| `POST` | `/api/v1/claws` | Create a new claw agent |\n| `GET` | `/api/v1/claws/stats` | Aggregate claw statistics |\n| `GET` | `/api/v1/claws/:id` | Get claw details + session |\n| `PUT` | `/api/v1/claws/:id` | Update claw configuration |\n| `DELETE` | `/api/v1/claws/:id` | Delete claw (auto-stops if running) |\n| `POST` | `/api/v1/claws/:id/start` | Start claw execution |\n| `POST` | `/api/v1/claws/:id/pause` | Pause running claw |\n| `POST` | `/api/v1/claws/:id/resume` | Resume paused claw |\n| `POST` | `/api/v1/claws/:id/stop` | Stop claw |\n| `POST` | `/api/v1/claws/:id/execute` | Run one cycle immediately |\n| `POST` | `/api/v1/claws/:id/message` | Send message to claw inbox |\n| `GET` | `/api/v1/claws/:id/history` | Paginated cycle history |\n| `GET` | `/api/v1/claws/:id/audit` | Per-tool-call audit log |\n| `POST` | `/api/v1/claws/:id/approve-escalation` | Approve pending escalation |\n\n### Subagents\n\n| Method | Endpoint | Description |\n| -------- | --------------------------- | --------------------------- |\n| `GET` | `/api/v1/subagents` | List active subagents |\n| `POST` | `/api/v1/subagents` | Spawn a new subagent |\n| `GET` | `/api/v1/subagents/:id` | Get subagent session/result |\n| `DELETE` | `/api/v1/subagents/:id` | Cancel a running subagent |\n| `GET` | `/api/v1/subagents/history` | Paginated execution history |\n\n### CLI Tools\n\n| Method | Endpoint | Description |\n| -------- | -------------------------------- | ------------------------------ |\n| `GET` | `/api/v1/cli-tools` | Discover installed CLI tools |\n| `GET` | `/api/v1/cli-tools/policies` | Get per-tool security policies |\n| `PUT` | `/api/v1/cli-tools/policies` | Update tool policies (batch) |\n| `POST` | `/api/v1/cli-tools/execute` | Execute a CLI tool |\n| `POST` | `/api/v1/cli-tools/custom` | Register a custom CLI tool |\n| `DELETE` | `/api/v1/cli-tools/custom/:name` | Remove a custom CLI tool |\n\n### CLI Providers\n\n| Method | Endpoint | Description |\n| -------- | --------------------------- | --------------------------- |\n| `GET` | `/api/v1/cli-providers` | List coding agent providers |\n| `POST` | `/api/v1/cli-providers` | Register a custom provider |\n| `PUT` | `/api/v1/cli-providers/:id` | Update provider config |\n| `DELETE` | `/api/v1/cli-providers/:id` | Remove a custom provider |\n\n### Model Routing\n\n| Method | Endpoint | Description |\n| ------ | ------------------------------- | --------------------------------- |\n| `GET` | `/api/v1/model-routing` | Get model routing configuration |\n| `PUT` | `/api/v1/model-routing` | Update model routing rules |\n| `GET` | `/api/v1/model-routing/resolve` | Resolve model for a given process |\n\n### System\n\n| Method | Endpoint | Description |\n| ---------- | ------------------------------- | -------------------------- |\n| `GET` | `/health` | Health check |\n| `GET` | `/api/v1/dashboard` | Dashboard data |\n| `GET` | `/api/v1/audit/logs` | Audit trail |\n| `GET/POST` | `/api/v1/database` | Database backup/restore |\n| `GET/PUT` | `/api/v1/settings` | System settings |\n| `GET/PUT` | `/api/v1/config-services` | Config Center entries |\n| `GET/PUT` | `/api/v1/execution-permissions` | Code execution permissions |\n\n### WebSocket Events\n\nReal-time broadcasts via WebSocket at `ws://localhost:8080/ws` (attached to the HTTP server, same port):\n\n| Event | Description |\n| ------------------------- | ------------------------------------------------- |\n| `data:changed` | CRUD mutation on any entity (tasks, notes, etc.) |\n| `chat:stream:*` | Streaming response chunks |\n| `tool:start/progress/end` | Tool execution lifecycle |\n| `channel:message` | Incoming channel message (Telegram, WhatsApp) |\n| `channel:status` | Channel connection/disconnection status change |\n| `channel:user:*` | User events (first_seen, pending, blocked, etc.) |\n| `trigger:executed` | Trigger execution result |\n| `coding-agent:session:*` | Coding agent session lifecycle and output |\n| `subagent:*` | Subagent spawned, progress, and completion |\n| `pulse:activity` | Pulse system proactive activity |\n| `claw:*` | Claw lifecycle, cycle results, output, escalation |\n\n### Response Format\n\nAll API responses use a standardized envelope:\n\n```json\n{\n \"success\": true,\n \"data\": {},\n \"meta\": {\n \"requestId\": \"uuid\",\n \"timestamp\": \"ISO-8601\"\n }\n}\n```\n\nError responses include error codes from a standardized `ERROR_CODES` enum.\n\n---\n\n## Configuration\n\n### Environment Variables\n\n\u003e **Note:** AI provider API keys (OpenAI, Anthropic, etc.) and channel tokens (Telegram) are **not** configured via environment variables. Use the Config Center UI or `ownpilot config set` CLI after setup.\n\n```bash\n# ─── Server ────────────────────────────────────────\nPORT=8080 # Gateway port\nUI_PORT=5173 # UI dev server port\nHOST=127.0.0.1\nNODE_ENV=development\n# CORS_ORIGINS= # Additional origins (localhost:UI_PORT auto-included)\n# BODY_SIZE_LIMIT=1048576 # Max request body size in bytes (default: 1MB)\n\n# ─── Database (PostgreSQL) ─────────────────────────\n# Option 1: Full connection URL\n# DATABASE_URL=postgresql://user:pass@host:port/db\n# Option 2: Individual settings\nPOSTGRES_HOST=localhost\nPOSTGRES_PORT=25432\nPOSTGRES_USER=ownpilot\nPOSTGRES_PASSWORD=ownpilot_secret # Change in production\nPOSTGRES_DB=ownpilot\n# POSTGRES_POOL_SIZE=10\n# DB_VERBOSE=false\n\n# ─── Authentication (DB primary, ENV fallback) ─────\n# AUTH_TYPE=none # none | api-key | jwt\n# API_KEYS= # Comma-separated keys for api-key auth\n# JWT_SECRET= # For jwt auth (min 32 chars)\n\n# ─── Rate Limiting (DB primary, ENV fallback) ──────\n# RATE_LIMIT_DISABLED=false\n# RATE_LIMIT_WINDOW_MS=60000\n# RATE_LIMIT_MAX=500\n\n# ─── Security \u0026 Encryption ────────────────────────\n# ENCRYPTION_KEY= # 32 bytes hex (for OAuth token encryption)\n# ADMIN_API_KEY= # Admin key for debug endpoints (production)\n\n# ─── Data Storage ─────────────────────────────────\n# OWNPILOT_DATA_DIR= # Override platform-specific data directory\n\n# ─── Logging ──────────────────────────────────────\nLOG_LEVEL=info\n\n# ─── Debug (development only) ─────────────────────\n# DEBUG_AI_REQUESTS=false\n# DEBUG_AGENT=false\n# DEBUG_LLM=false\n# DEBUG_RAW_RESPONSE=false\n# DEBUG_EXEC_SECURITY=false\n\n# ─── Sandbox (advanced) ──────────────────────────\n# ALLOW_HOME_DIR_ACCESS=false\n# DOCKER_SANDBOX_RELAXED_SECURITY=false\n# MEMORY_SALT=change-this-in-production\n```\n\n### Configuration Priority\n\n1. **CLI options** (highest) - `-p`, `-h`, `--no-auth`\n2. **PostgreSQL database** - settings table\n3. **Environment variables** - `.env` file\n4. **Hardcoded defaults** (lowest) - `config/defaults.ts`\n\n---\n\n## Deployment\n\n### Ports \u0026 Services\n\n| Service | Port | Protocol | Description |\n| -------------- | ------- | -------- | -------------------------------------------- |\n| **Gateway** | `8080` | HTTP | REST API + bundled UI (Vite static assets) |\n| **WebSocket** | `8080` | WS | Real-time events at `/ws` (shares HTTP port) |\n| **PostgreSQL** | `25432` | TCP | Database (mapped from container's `5432`) |\n| **MQTT** | `1883` | TCP | Mosquitto broker (optional, for edge/IoT) |\n| **MQTT WS** | `9001` | WS | MQTT WebSocket transport (optional) |\n\n\u003e **Note:** In production (Docker), a single port `8080` serves everything — REST API, WebSocket, and the pre-built UI. No separate frontend deployment needed.\n\n### Docker Compose\n\n```bash\ncp .env.example .env\n# Edit .env with your settings\n\n# Start OwnPilot + PostgreSQL\ndocker compose --profile postgres up -d\n\n# With MQTT broker for edge/IoT devices\ndocker compose --profile postgres --profile mqtt up -d\n```\n\nOpen **http://localhost:8080** — the gateway serves the bundled React UI, REST API, and WebSocket on the same port.\n\n### Pre-built Image\n\nA multi-arch image (amd64 + arm64) is published to GitHub Container Registry on every release:\n\n```bash\ndocker pull ghcr.io/ownpilot/ownpilot:latest\n\ndocker run -d \\\n --name ownpilot \\\n -p 8080:8080 \\\n -e DATABASE_URL=postgresql://user:pass@host:5432/ownpilot \\\n -e NODE_ENV=production \\\n ghcr.io/ownpilot/ownpilot:latest\n```\n\nHealth check: `GET http://localhost:8080/health`\n\n### Development Mode\n\nIn development, Vite runs a separate dev server with hot reload:\n\n| Service | Port | Description |\n| ------------------- | ------- | ------------------------------------------------------- |\n| **Vite Dev Server** | `5173` | React UI with HMR (proxies `/api` and `/ws` to gateway) |\n| **Gateway** | `8080` | REST API + WebSocket |\n| **PostgreSQL** | `25432` | Database |\n\n```bash\npnpm dev # Starts gateway (8080) + Vite UI (5173)\n```\n\nOpen **http://localhost:5173** for development. Vite automatically proxies API calls (`/api/*`) and WebSocket (`/ws`) to the gateway on port 8080.\n\n### Manual Production\n\n```bash\npnpm build # Build all packages (includes UI static assets)\nownpilot start # Start production server on port 8080\n```\n\n---\n\n## Development\n\n### Scripts\n\n```bash\n# Setup wizard (interactive)\n./setup.sh # Linux/macOS\n.\\setup.ps1 # Windows PowerShell\n\n# Start scripts\n./start.sh # Linux/macOS\n.\\start.ps1 # Windows PowerShell\n\n# Start options:\n# --dev Development mode with hot reload (default)\n# --prod Production mode (build \u0026 serve)\n# --docker Start with Docker Compose\n# --no-ui Gateway only, without UI\n\n# Package scripts\npnpm dev # Watch mode for all packages\npnpm build # Build all packages\npnpm test # Run all tests\npnpm test:watch # Watch test mode\npnpm test:coverage # Coverage reports\npnpm lint # ESLint check\npnpm lint:fix # Auto-fix lint issues\npnpm typecheck # TypeScript type checking\npnpm format # Prettier formatting\npnpm format:check # Check formatting\npnpm clean # Clear all build artifacts\n```\n\n### Tech Stack\n\n| Layer | Technology |\n| -------------- | --------------------------------------------- |\n| **Monorepo** | pnpm 10+ workspaces + Turborepo 2.x |\n| **Language** | TypeScript 5.9 (strict, ES2023, NodeNext) |\n| **Runtime** | Node.js 22+ |\n| **API Server** | Hono 4.12 |\n| **Web UI** | React 19 + Vite 7 + Tailwind CSS 4 |\n| **Database** | PostgreSQL (with pgvector) |\n| **Telegram** | Grammy 1.41 |\n| **CLI** | Commander.js 14 |\n| **MCP** | @modelcontextprotocol/sdk |\n| **Testing** | Vitest 4.x (549 test files, 26,500+ tests) |\n| **Linting** | ESLint 10 (flat config) |\n| **Formatting** | Prettier 3.8 |\n| **Container** | Docker multi-arch (ghcr.io/ownpilot/ownpilot) |\n| **Git Hooks** | Husky (pre-commit: lint + typecheck) |\n| **CI** | GitHub Actions (Node 22, Ubuntu) |\n\n### Architecture Patterns\n\n| Pattern | Usage |\n| ------------------------ | ----------------------------------------------------------------- |\n| **Result\u003cT, E\u003e** | Functional error handling throughout core |\n| **Branded Types** | Compile-time distinct types (UserId, SessionId, PluginId) |\n| **Service Registry** | Typed DI container for runtime service composition |\n| **Middleware Pipeline** | Tools, MessageBus, providers all use middleware chains |\n| **Builder Pattern** | Plugin and Channel construction |\n| **EventBus + HookBus** | Event-driven state + interceptable hooks |\n| **Repository** | Data access abstraction with BaseRepository |\n| **Meta-tool Proxy** | Token-efficient tool discovery and execution |\n| **Tool Namespaces** | Qualified names (`core.`, `mcp.`, `plugin.`, `custom.`, `skill.`) |\n| **Context + Hooks** | React state management (no Redux/Zustand) |\n| **WebSocket Broadcasts** | Real-time data synchronization across all mutation endpoints |\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fownpilot%2FOwnPilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fownpilot%2FOwnPilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fownpilot%2FOwnPilot/lists"}