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.

Self-hosted. Your data stays yours.

• Features
• Architecture
• Quick Start
• Setup Guide — Detailed installation instructions
• Project Structure
• Packages
  • Core
  • Gateway
  • UI
  • CLI
• AI Providers
• Agent System
• Soul Agents
• Autonomous Hub
• Agent Orchestra
• Claw Agents
• Subagents
• Tool System
• MCP Integration
• Artifacts
• Voice Pipeline
• Browser Agent
• Edge Devices
• Personal Data
• Autonomy & Automation
• Database
• Security & Privacy
  • Code Execution
• API Reference
• Configuration
• Deployment
• Development
• License

• 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
• Local AI Support — Ollama, LM Studio, LocalAI, and vLLM auto-discovery on the local network
• Smart Provider Routing — Cheapest, fastest, smartest, balanced, or fallback strategies
• Anthropic Prompt Caching — Static system prompt blocks cached via cache_control to reduce input tokens on repeated requests
• Context Management — Real-time context usage tracking, detail modal with per-section token breakdown, context compaction (AI-powered message summarization), session clear
• Streaming Responses — Server-Sent Events (SSE) for real-time streaming with tool execution progress
• Configurable Agents — Custom system prompts, model preferences, tool assignments, and execution limits

• 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)
• 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
• Tool Namespaces — Qualified tool names with prefixes (core., custom., plugin., skill., mcp.) for clear origin tracking
• MCP Client — Connect to external MCP servers (Filesystem, GitHub, Brave Search, etc.) and use their tools natively
• MCP Server — Expose OwnPilot's tools as an MCP endpoint for Claude Desktop and other MCP clients
• 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
• 6 Default Extensions — Daily Briefing, Knowledge Base, Project Tracker, Smart Search, Automation Builder, Contact Enricher bundled out-of-the-box
• Extension Security Audit — LLM-powered security analysis for skills and extensions before installation
• Skills — Open standard SKILL.md format (AgentSkills.io) for instruction-based AI knowledge packages
• Custom Tools — Create new tools at runtime via LLM (sandboxed JavaScript)
• Connected Apps — 1000+ OAuth app integrations via Composio (Google, GitHub, Slack, Notion, Stripe, etc.)
• Tool Limits — Automatic parameter capping to prevent unbounded queries
• Search Tags — Natural language tool discovery with keyword matching

• Notes, Tasks, Bookmarks, Contacts, Calendar, Expenses — Full CRUD with categories, tags, and search
• Productivity — Pomodoro timer with sessions/stats, habit tracker with streaks, quick capture inbox
• Memories — Long-term persistent memory (facts, preferences, events) with importance scoring, vector search, and auto-injection
• Goals — Goal creation, decomposition into steps, progress tracking, next-action recommendations
• Custom Data Tables — Create your own structured data types with AI-determined schemas

• External AI Coding CLIs — Orchestrate Claude Code, Codex, and Gemini CLI from the web UI or via AI tool calling
• Session Management — Long-running coding sessions with real-time terminal output streaming
• Dual Execution Modes — Auto mode (headless child_process.spawn) and interactive mode (PTY terminal)
• Custom Providers — Register any CLI binary as a coding agent provider
• Result Persistence — Task output, exit codes, and duration stored in the database

• Rich Agent Identity — Agents with personality, role, mission, voice, boundaries, and emoji; full identity framework for autonomous operation
• Heartbeat Lifecycle — Cron-scheduled execution cycles with configurable checklist, self-healing, max duration, and cost tracking
• Crew System — Multi-agent crews with role assignments, delegation protocols, and ready-made crew templates
• Inter-Agent Communication — Agents can send messages to each other with subject, content, and type classification
• Evolution Tracking — Version-controlled agent evolution with core/mutable traits, learnings, and feedback log
• Autonomy Controls — Per-agent autonomy levels with allowed/blocked actions, approval requirements, and budget limits (per-cycle, per-day, per-month)
• Boot Sequences — Configurable onStart, onHeartbeat, and onMessage action sequences
• 16+ Agent Templates — Pre-built configurations for common use cases (Morning Briefer, News Monitor, Code Reviewer, Budget Tracker, etc.)

• Unified Command Center — Single tabbed dashboard consolidating all autonomous agents (soul + background), crews, messaging, and activity
• AI Agent Creator — Conversational agent creation: describe what you need in plain language, refine through chat, preview JSON config, create in one click
• Agent Cards — At-a-glance agent status with real-time indicators, mission preview, cost tracking, and quick actions (pause/resume/delete)
• Activity Feed — Unified timeline of heartbeat logs and agent messages with aggregate stats (total runs, success rate, avg duration, total cost)
• Global Status Bar — Live agent count, running/paused/error breakdown, daily cost, and WebSocket connection state
• Search & Filters — Filter agents by status, type (soul/background), and text search across name, role, and mission

• 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
• 4 Execution Modes — Single-shot (one task), Continuous (adaptive loop), Interval (periodic), Event-driven (reactive to EventBus events)
• 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
• 7 Chat Management Tools — Create, list, start, stop, message, and inspect claws from the main chat
• .claw/ Directive System — Persistent workspace files (INSTRUCTIONS.md, TASKS.md, MEMORY.md, LOG.md) that guide the claw across cycles
• Workspace Isolation — Each claw gets its own file workspace with file browser, inline editor, and ZIP download
• Output Delivery — Send results via Telegram, WebSocket live feed, conversation history, and artifact publishing
• Subclaw Orchestration — Spawn child claws (max depth 3) with parent control (list, stop)
• Self-Modification — Claws can update their own config, reflect on progress, and adapt strategy
• Working Memory — Persistent key-value context (claw_set_context/claw_get_context) injected into every cycle for cross-cycle state tracking
• Escalation Control — Human-in-the-loop approve/deny flow for environment upgrades with denial reason forwarding
• Inter-Claw Messaging — Direct message passing between claws via inbox system
• Audit Log — Per-tool-call tracking with 10 auto-categories (claw, cli, browser, coding-agent, web, code-exec, git, filesystem, knowledge, tool)
• Workflow Integration — clawNode (24th workflow node type) for spawning claws within workflows
• 8-Tab Management UI — Overview, Settings, Skills, Files, History, Audit, Output, Chat
• 6 Templates — Research Agent, Code Reviewer, Data Analyst, Monitor & Alert, Content Creator, Event Reactor
• Resource Limits — MAX_CONCURRENT_CLAWS=50, generous defaults (50 turns, 500 tool calls, 10min timeout, unlimited budget)

• Parallel Task Delegation — Chat agents and claw agents can spawn lightweight child agents for concurrent task execution
• Fire-and-Forget Model — Spawn returns immediately with a session ID; parent polls for results via check_subagent/get_subagent_result
• Budget Enforcement — Configurable concurrent limit (default 5), total spawn limit (default 20), and nesting depth cap (max 2 levels)
• Full Tool Access — Subagents inherit the parent's full tool pipeline; optional allowedTools restriction
• Independent Model Selection — Each subagent can use a different provider/model (e.g., expensive model for parent, cheap model for subagents)
• 5 LLM-Callable Tools — spawn_subagent, check_subagent, get_subagent_result, cancel_subagent, list_subagents

• Multi-Agent Orchestration — Fan-out/fan-in, race, pipeline, and voting strategies for concurrent multi-provider agent execution
• Real-time Progress — WebSocket events for orchestra session lifecycle (started, step completed, finished)
• 6 LLM Tools — create_orchestra, run_orchestra, list_orchestras, get_orchestra_result, cancel_orchestra, list_strategies

• Versioned Documents — Create, update, and track markdown, code, JSON, HTML, CSV, SVG, and Mermaid diagram artifacts
• Data Binding — Expression-based bindings ({{source.field}}) that auto-resolve from conversation context
• Diff Tracking — Version history with content diffs for every update
• 5 LLM Tools — create_artifact, update_artifact, list_artifacts, get_artifact, delete_artifact

• Speech-to-Text — Whisper API integration for audio transcription with configurable models
• Text-to-Speech — OpenAI TTS with multiple voices (alloy, echo, fable, onyx, nova, shimmer)
• Chat Integration — VoiceButton for recording in ChatInput, VoicePlayButton for AI response playback
• Channel Support — WhatsApp voice message transcription via channel normalizer

• Headless Automation — Playwright-powered Chromium for AI-driven web browsing
• 7 LLM Tools — Navigate, click, type, screenshot, evaluate JavaScript, extract content, fill forms
• Workflow Persistence — Browser automation workflows stored in DB for replay and audit

• Enhanced Lifecycle — Sandboxed skill execution with granular permissions (network, filesystem, database, shell, email, scheduling)
• npm Dependencies — Skills can declare and install npm packages via ownpilot skill install
• CLI Management — ownpilot skill commands for install, list, info, search, update, remove
• Permission Review — PermissionReviewModal UI for approving skill capabilities before activation

• MQTT Integration — Mosquitto broker for lightweight IoT device communication
• Device Registry — Register edge devices (Raspberry Pi, ESP32, Arduino, custom) with sensors and actuators
• Telemetry Ingestion — Real-time sensor data via MQTT topics, stored with full history
• Command Queue — Send commands to devices with acknowledgment tracking
• 6 LLM Tools — list_edge_devices, get_device_status, read_sensor, send_device_command, control_actuator, register_edge_device

• 40+ Discoverable Tools — Automatic PATH-based detection of installed CLI tools (linters, formatters, build tools, package managers, security scanners, databases, containers)
• Per-Tool Security Policies — allowed (auto-execute), prompt (require approval), blocked (reject) per user per tool
• Dynamic Risk Scoring — Catalog-based risk levels (low/medium/high/critical) feed into the autonomy risk engine
• Custom Tool Registration — Register any binary as a CLI tool with category and risk metadata
• Approval Integration — CLI tool policies wired into the real-time approval flow, overriding generic risk scores

• 5 Autonomy Levels — Manual, Assisted, Supervised, Autonomous, Full
• 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
• Triggers — Schedule-based (cron), event-driven, condition-based, webhook
• Heartbeats — Natural language to cron conversion for periodic tasks ("every weekday at 9am")
• Plans — Multi-step autonomous execution with checkpoints, retry logic, and timeout handling
• Risk Assessment — Automatic risk scoring for tool executions with approval workflows
• Model Routing — Per-process model selection (chat, channel, pulse, subagent) with fallback chains
• Extended Thinking — Anthropic extended thinking support for deeper reasoning in complex tasks

• Web UI — React 19 + Vite 7 + Tailwind CSS 4 with dark mode, 64 pages, 140+ components, code-split
• Telegram Bot — Full bot integration with user/chat filtering, message splitting, HTML/Markdown formatting
• 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
• Channel User Approval — Multi-step verification: approval code flow, manual admin approval, user blocking/unblocking with real-time notifications
• Channel Pairing Keys — Per-channel rotating pairing keys for ownership verification with revoke support
• EventBus — Unified event backbone with EventBusBridge translating dot-notation events to WebSocket colon-notation; Event Monitor UI for live debugging
• WebSocket — Real-time broadcasts for all data mutations, event subscriptions, session management
• REST API — 115 route modules with standardized responses, pagination, and error codes

• Zero-Dependency Crypto — AES-256-GCM encryption + PBKDF2 key derivation using only Node.js built-ins
• PII Detection & Redaction — 15+ categories (SSN, credit cards, emails, phone, etc.)
• Sandboxed Code Execution — Docker container isolation, local execution with approval, critical pattern blocking
• 4-Layer Security — Critical patterns -> permission matrix -> approval callback -> sandbox isolation
• Code Execution Approval — Real-time SSE approval dialog for sensitive operations with 120s timeout
• Authentication — None, API Key, or JWT modes
• Rate Limiting — Sliding window with burst support
• Tamper-Evident Audit — Hash chain verification for audit logs
• 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

 ┌──────────────┐ │ Web UI │ React 19 + Vite 7 │ (bundled) │ Tailwind CSS 4 └──────┬───────┘ │ HTTP + SSE + WebSocket (/ws) ┌─────────────────┼─────────────────┐ │ │ │ ┌────────┴────────┐ │ ┌─────────┴──────────┐ │ Telegram Bot │ │ │ External MCP │ │ WhatsApp │ │ │ Clients/Servers │ │ (Channels) │ │ └─────────┬──────────┘ └────────┬────────┘ │ │ └────────┬───────┘──────────────────┘ │ ┌────────▼────────┐ │ Gateway │ Hono HTTP API Server │ (Port 8080) │ 115 Route Modules ├─────────────────┤ │ MessageBus │ Middleware Pipeline │ Agent Engine │ Tool Orchestration │ Orchestra │ Multi-Agent Coordination │ Provider Router│ Smart Model Selection │ Claw Agents │ Unified Autonomous Runtime │ Background Agt │ Persistent Autonomous Agents │ Coding Agents │ External AI CLIs │ Browser Agent │ Headless Web Automation │ Voice Pipeline │ STT/TTS Integration │ Edge Manager │ MQTT + IoT Devices │ CLI Tools │ 40+ Discoverable Tools │ Pulse Engine │ Proactive Autonomy │ MCP Client │ External Tool Servers │ Plugin System │ Extensible Architecture │ EventBus │ Unified Event Backbone │ WebSocket │ Real-time Broadcasts ├─────────────────┤ │ Core │ AI Engine & Tool Framework │ 250+ Tools │ Multi-Provider Support │ Sandbox, Crypto│ Privacy, Audit └────────┬────────┘ │ ┌────────▼────────┐ ┌─────────────┐ │ PostgreSQL │ │ Mosquitto │ │ 67 Repos │ │ MQTT Broker │ │ │ └──────────────┘ └─────────────────┘ 

Request → Audit → Persistence → Post-Processing → Context-Injection → Agent-Execution → Response 

All messages (web UI chat, Telegram, trigger-initiated chats) flow through the same MessageBus middleware pipeline.

git clone https://github.com/ownpilot/ownpilot.git cd ownpilot # Start OwnPilot + PostgreSQL (uses defaults, no .env needed) docker compose --profile postgres up -d # UI + API: http://localhost:8080

To customize settings (auth, Telegram, etc.), copy and edit .env before starting:

cp .env.example .env # Edit .env — docker-compose.yml defaults match .env.example docker compose --profile postgres up -d

• Node.js >= 22.0.0
• pnpm >= 10.0.0
• PostgreSQL 16+ (via Docker Compose or native install)

Use the interactive setup wizard:

# Linux/macOS ./setup.sh # Windows PowerShell .\setup.ps1

The wizard will guide you through:

• Prerequisites check (Node.js, pnpm, Docker)
• Server configuration (ports, host)
• Authentication setup
• Database configuration
• Docker PostgreSQL startup
• Dependency installation and build

Alternative: Non-interactive scripts

# Linux/macOS ./scripts/setup.sh --minimal # Skip Docker ./scripts/setup.sh --docker-only # Only database # Windows PowerShell .\scripts\setup.ps1 -Mode Minimal .\scripts\setup.ps1 -Mode DockerOnly

# Clone and install git clone https://github.com/ownpilot/ownpilot.git cd ownpilot pnpm install # Configure cp .env.example .env # Edit .env if needed (defaults work with docker compose PostgreSQL) # Start PostgreSQL (if you don't have one already) docker compose --profile postgres up -d # Start development (gateway on :8080 + Vite UI on :5173) pnpm dev # Open http://localhost:5173 (Vite proxies API/WS to gateway)

AI provider API keys are configured via the Config Center UI (Settings page) after setup.

# Initialize database ownpilot setup # Start server ownpilot start # Configure API keys (stored in database, not .env) ownpilot config set openai-api-key sk-...

API keys and settings are stored in the PostgreSQL database. The web UI Config Center (Settings page) provides a graphical alternative to CLI configuration.

ownpilot/ ├── packages/ │ ├── core/ # AI engine & tool framework │ │ ├── src/ │ │ │ ├── agent/ # Agent engine, orchestrator, providers │ │ │ │ ├── providers/ # Multi-provider implementations │ │ │ │ ├── orchestra/ # Multi-agent orchestration engine │ │ │ │ └── tools/ # 250+ built-in tool definitions │ │ │ ├── plugins/ # Plugin system with isolation, marketplace │ │ │ ├── events/ # EventBus, HookBus, ScopedBus │ │ │ ├── services/ # Service registry (DI container) │ │ │ ├── memory/ # Encrypted personal memory (AES-256-GCM) │ │ │ ├── sandbox/ # Code execution isolation (VM, Docker, Worker) │ │ │ ├── crypto/ # Zero-dep encryption, vault, keychain │ │ │ ├── audit/ # Tamper-evident hash chain logging │ │ │ ├── privacy/ # PII detection & redaction │ │ │ ├── security/ # Critical pattern blocking, permissions │ │ │ ├── channels/ # Channel plugin architecture + UCP │ │ │ ├── edge/ # Edge device types and interfaces │ │ │ ├── assistant/ # Intent classifier, orchestrator │ │ │ ├── workspace/ # Per-user isolated environments │ │ │ └── types/ # Branded types, Result<T,E>, guards │ │ └── package.json │ │ │ ├── gateway/ # Hono API server (~148K LOC) │ │ ├── src/ │ │ │ ├── routes/ # 115 route handlers │ │ │ ├── services/ # 108 business logic services │ │ │ ├── tools/ # Tool providers (coding, CLI, edge, browser, etc.) │ │ │ ├── db/ │ │ │ │ ├── repositories/ # 67 data access repositories │ │ │ │ ├── adapters/ # PostgreSQL adapter │ │ │ │ ├── migrations/ # 26 schema migrations │ │ │ │ └── seeds/ # Default data │ │ │ ├── channels/ # Telegram + WhatsApp channel plugins │ │ │ ├── plugins/ # Plugin initialization & registration │ │ │ ├── triggers/ # Proactive automation engine │ │ │ ├── plans/ # Plan executor with step handlers │ │ │ ├── autonomy/ # Risk assessment, approval manager, pulse │ │ │ ├── ws/ # WebSocket server & real-time broadcasts │ │ │ ├── middleware/ # Auth, rate limiting, CORS, audit │ │ │ ├── assistant/ # AI orchestration (memories, goals) │ │ │ ├── tracing/ # Request tracing (AsyncLocalStorage) │ │ │ └── audit/ # Gateway audit logging │ │ └── package.json │ │ │ ├── ui/ # React 19 web interface (~115K LOC) │ │ ├── src/ │ │ │ ├── pages/ # 64 page components │ │ │ ├── components/ # 140 reusable components │ │ │ ├── hooks/ # Custom hooks (chat store, theme, WebSocket) │ │ │ ├── api/ # Typed fetch wrapper + endpoint modules │ │ │ ├── types/ # UI type definitions │ │ │ └── App.tsx # Route definitions with lazy loading │ │ └── package.json │ │ │ └── cli/ # Commander.js CLI │ ├── src/ │ │ ├── commands/ # server, bot, start, config, workspace, channel │ │ └── index.ts # CLI entry point │ └── package.json │ ├── turbo.json # Turborepo pipeline config ├── tsconfig.base.json # Shared TypeScript strict config ├── eslint.config.js # ESLint 10 flat config ├── .env.example # Environment variable template └── package.json # Monorepo root 

The foundational runtime library. Contains the AI engine, tool system, plugin architecture, security primitives, and cryptography. Minimal dependencies (only googleapis for Google OAuth).

~72,000 LOC across 251 source files.

The API server built on Hono. Handles HTTP/WebSocket communication, database operations, agent execution, MCP integration, plugin management, and channel connectivity.

~144,000 LOC across 460 source files. 388 test files with 16,294+ tests.

Route Modules (115 handlers):

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.

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.

Modern web interface built with React 19, Vite 7, and Tailwind CSS 4. Minimal dependencies — no Redux/Zustand, no axios, no component library.

Pages (64):

Key Components (140): Layout, ChatInput, MessageList, ContextBar, ContextDetailModal, ToolExecutionDisplay, TraceDisplay, CodeBlock, MarkdownContent, ExecutionApprovalDialog, ExecutionSecurityPanel, SuggestionChips, MemoryCards, WorkspaceSelector, ToastProvider, ConfirmDialog, DynamicConfigForm, ErrorBoundary, SetupWizard, and more.

State Management (Context + Hooks):

• useChatStore — Global chat state with SSE streaming, tool progress, approval flow
• useTheme — Dark/light/system theme with localStorage persistence
• useWebSocket — WebSocket connection with auto-reconnect and event subscriptions

Command-line interface built with Commander.js and @inquirer/prompts.

ownpilot setup # Initialize database ownpilot start # Start server + bot ownpilot server # Start HTTP API server only ownpilot bot # Start Telegram bot only # Configuration (stored in PostgreSQL) ownpilot config set <key> [value] # Set credential or setting ownpilot config get <key> # Retrieve (masked for secrets) ownpilot config delete <key> # Remove ownpilot config list # List all with status # Workspace management ownpilot workspace list ownpilot workspace create ownpilot workspace delete [id] ownpilot workspace switch [id] # Channel management ownpilot channel list ownpilot channel add ownpilot channel remove [id] ownpilot channel connect [id] ownpilot channel disconnect [id]

Configuration keys: <provider>-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.

All 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.

104 providers with auto-synced model catalogs from models.dev. Key providers:

Any OpenAI-compatible endpoint can be added as a custom provider.

• 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.
• 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.
• Meta-tool Proxy — Only 4 small tool definitions sent to the LLM instead of 250+ full schemas.

Agents are AI assistants with specific system prompts, tool assignments, model preferences, and execution limits.

{ name: string // Display name systemPrompt: string // Custom instructions provider: string // AI provider (or 'default') model: string // Model ID (or 'default') config: { maxTokens: number // Max response tokens temperature: number // Creativity (0-2) maxTurns: number // Max conversation turns maxToolCalls: number // Max tool calls per turn tools?: string[] // Specific tool names toolGroups?: string[] // Tool group names } }

• Tool Orchestration — Automatic tool calling with multi-step planning via meta-tool proxy
• Memory Injection — Relevant memories automatically included in system prompt (vector + full-text hybrid search)
• Goal Awareness — Active goals and progress injected into context
• Dynamic System Prompts — Context-aware enhancement with memories, goals, available resources
• Execution Context — Code execution instructions injected into system prompt (not user message)
• Context Tracking — Real-time context bar showing token usage, fill percentage, and per-section breakdown
• Streaming — Real-time SSE responses with tool execution progress events

Soul agents are autonomous agents with rich identity, personality, and heartbeat-driven lifecycle. They combine scheduling with a full identity framework.

{ agentId: string // Unique agent ID identity: { name: string // Display name emoji: string // Agent emoji role: string // Professional role personality: string // Personality description voice: { tone, language } // Communication style boundaries: string[] // Behavioral constraints } purpose: { mission: string // Core mission statement goals: string[] // Active goals expertise: string[] // Domain expertise toolPreferences: string[] // Preferred tools } autonomy: { level: 1-4 // Autonomy level allowedActions: string[] // Permitted actions blockedActions: string[] // Blocked actions requiresApproval: string[] // Actions needing user approval maxCostPerCycle: number // Budget per heartbeat cycle maxCostPerDay: number // Daily budget limit maxCostPerMonth: number // Monthly budget limit } heartbeat: { enabled: boolean // Enable scheduled execution interval: string // Cron expression checklist: string[] // Tasks to run each cycle selfHealingEnabled: boolean maxDurationMs: number // Cycle timeout } relationships: { delegates: string[] // Agents this soul can delegate to peers: string[] // Peer agents channels: string[] // Communication channels } }

Multi-agent crews coordinate soul agents for complex tasks:

• Role Assignment — Each crew member has a defined role within the crew
• Delegation Protocol — Automatic task delegation between crew members
• Crew Templates — Pre-built crew configurations for common multi-agent workflows

The Autonomous Hub is a unified command center for managing all autonomous agents from a single interface.

Describe what you want in plain English and the AI designs the agent configuration:

1. Open the AI Creator modal from the hub header
2. Describe your agent (e.g., "Monitor my GitHub PRs daily")
3. The AI designs a configuration with name, mission, schedule, tools, and cost estimate
4. Review the preview card and refine through conversation
5. Click "Create This Agent" to deploy

The creator uses a dedicated agent with a specialized system prompt, ensuring it acts as an agent designer rather than a general chatbot.

Ephemeral child agents for parallel task delegation. Unlike claw agents (which are persistent and cycle-based), subagents run once to completion and are discarded.

Parent Agent (chat or claw agent) ├─ spawn_subagent("Research pricing") → SubagentRunner #1 ├─ spawn_subagent("Analyze competitors") → SubagentRunner #2 ├─ spawn_subagent("Draft summary") → SubagentRunner #3 │ ├─ check_subagent(#1) → running... ├─ get_subagent_result(#1) → "Pricing analysis: ..." └─ Synthesize final answer from all results 

OwnPilot 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:

1. search_tools — Find tools by keyword with optional include_params for inline parameter schemas
2. get_tool_help — Get detailed help for a specific tool (supports batch lookup)
3. use_tool — Execute a tool with parameter validation and limit enforcement
4. batch_use_tool — Execute multiple tools in a single call

All tools use qualified names with dot-prefixed namespaces:

The LLM can use base names (without prefix) for backward compatibility — the registry resolves them automatically.

The AI can create new tools at runtime:

1. LLM calls create_tool with name, description, parameters, and JavaScript code
2. Tool is validated, sandboxed, and stored in the database
3. Tool is available to all agents via use_tool
4. Tools can be enabled/disabled and have permission controls

OwnPilot supports the Model Context Protocol in both directions:

Connect to any MCP server to extend OwnPilot's capabilities:

Settings → MCP Servers → Add (or use Quick Add presets) 

Pre-configured presets:

• Filesystem — Read, write, and manage local files
• GitHub — Manage repos, issues, PRs, and branches
• Brave Search — Web and local search
• Fetch — Extract content from web pages
• Memory — Persistent knowledge graph
• Sequential Thinking — Structured problem-solving

Tools from connected MCP servers appear in the AI's catalog with mcp.{servername}. prefix and are available via search_tools / use_tool.

OwnPilot exposes its full tool registry as an MCP endpoint:

POST /mcp/serve — Streamable HTTP transport 

External MCP clients (Claude Desktop, other agents) can connect and use OwnPilot's 250+ tools.

Versioned document management for AI-created content — markdown, code, JSON, HTML, CSV, SVG, and Mermaid diagrams.

• Version Tracking — Every update creates a new version with content diffs
• Data Binding — Expressions like {{conversation.summary}} that auto-resolve from context
• Rendering Pipeline — ArtifactRenderer component renders each content type natively (syntax highlighting for code, Mermaid→SVG for diagrams)
• Dashboard Widget — Recent artifacts shown on the Dashboard page

Speech-to-text and text-to-speech integration for voice-powered AI interactions.

• STT (Whisper) — Transcribe audio files or microphone input via OpenAI Whisper API
• TTS (OpenAI) — Generate speech from AI responses with 6 voice options (alloy, echo, fable, onyx, nova, shimmer)
• VoiceButton — Microphone recording UI in the ChatInput component
• VoicePlayButton — Inline playback button on AI responses
• Channel Support — WhatsApp voice messages auto-transcribed via channel normalizer

Headless Chromium automation via Playwright for AI-driven web browsing and data extraction.

• Workflow Persistence — Browser workflows stored in DB for replay and audit
• Session Management — Isolated browser contexts per session
• REST API — Full CRUD at /api/v1/browser plus workflow execution

MQTT-based IoT/edge device management. OwnPilot acts as the brain; cheap edge hardware (ESP32, Raspberry Pi) acts as the hands.

Edge Device (ESP32/RPi/Arduino) │ │ MQTT (lightweight pub/sub) │ ├── ownpilot/{userId}/devices/{deviceId}/telemetry → Server ├── ownpilot/{userId}/devices/{deviceId}/commands ← Server └── ownpilot/{userId}/devices/{deviceId}/status → Server (LWT) │ Mosquitto Broker ←→ OwnPilot Gateway (EdgeMqttClient) 

Sensors: temperature, humidity, motion, light, pressure, camera, door, custom Actuators: relay, servo, LED, buzzer, display, motor, custom

10 endpoints at /api/v1/edge — device CRUD, commands, telemetry, MQTT status.

Persistent long-term memory for the AI assistant with AES-256-GCM encryption:

Memories 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.

Hierarchical goal tracking with decomposition:

• Create goals with title, description, due date
• Decompose into actionable steps (pending, in_progress, completed, skipped)
• Track progress (0-100%) with status (active/completed/abandoned)
• Get next actions — AI recommends what to do next
• Complete steps — Auto-update parent goal progress

Proactive automation with 4 trigger types:

Natural language periodic scheduling:

"every weekday at 9am" → 0 9 * * 1-5 "twice a day" → 0 9,18 * * * "every 30 minutes" → */30 * * * * 

The AI parses natural language into cron expressions for trigger scheduling.

Multi-step autonomous execution:

• Step types: tool, parallel, loop, conditional, wait, pause
• Status tracking: draft, running, paused, completed, failed, cancelled
• Timeout and retry logic with configurable backoff
• Step dependencies for execution ordering

Visual multi-step automation with a workflow editor:

• Drag-and-drop workflow builder in the web UI
• Step types: prompt, tool, conditional, loop
• Workflow Copilot — AI-assisted workflow creation and editing
• Execution logs with per-step status tracking

PostgreSQL with 85+ repositories via the pg adapter.

Core: conversations, messages, agents, settings, costs, request_logs

Personal Data: tasks, notes, bookmarks, calendar_events, contacts, expenses

Productivity: pomodoro_sessions, habits, captures

Autonomous AI: memories, goals, triggers, plans, heartbeats, workflows, autonomy_log, souls, crews, agent_messages, claws, claw_sessions, claw_history, claw_audit_log

Channels: channel_messages, channel_users, channel_sessions, channel_verification

Extensions: plugins, custom_tools, user_extensions, mcp_servers, embedding_cache

Coding & CLI: coding_agent_results, cli_providers, cli_tool_policies

System: custom_data_tables, config_services, execution_permissions, workspaces, model_configs, local_providers

Schema migrations are auto-applied on startup via autoMigrateIfNeeded(). Migration files are in packages/gateway/src/db/migrations/.

System → Database → Backup / Restore 

Full PostgreSQL backup and restore through the web UI or API.

API 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.

Keys are loaded into process.env at server startup for provider SDK compatibility.

• 15+ detection categories: SSN, credit cards, emails, phone numbers, IP addresses, passport, etc.
• Configurable redaction modes: mask, label, remove
• Severity-based filtering

OwnPilot can execute code on behalf of the AI through 5 execution tools:

When using Docker mode, each execution runs in a container with strict isolation:

• --read-only filesystem (writable /tmp only)
• --network=none (no network access)
• --user=65534:65534 (nobody user)
• --no-new-privileges
• --cap-drop=ALL (no Linux capabilities)
• --memory=256m limit
• --cpus=1 limit
• --pids-limit=100
• Configurable timeout with automatic cleanup

When running locally (without Docker), the local executor applies:

• Environment sanitization — strips API keys and sensitive variables from the child process
• Timeout enforcement — SIGKILL after configured timeout
• Output truncation — 1MB output limit to prevent memory exhaustion

Code execution is governed by a per-category permission matrix:

Categories: execute_javascript, execute_python, execute_shell, compile_code, package_manager

A master switch (enabled boolean) can disable all code execution globally.

When a tool's permission is set to prompt:

1. Gateway sends an SSE approval_required event to the web UI
2. UI shows an approval dialog with the code to be executed
3. User approves or rejects via POST /api/v1/execution-permissions/approvals/{id}/resolve
4. Execution proceeds or is cancelled (120-second timeout, auto-reject on expiry)

Regardless of permission settings, 100+ regex patterns are unconditionally blocked:

• Filesystem destruction (rm -rf /, format C:, del /f /s)
• Fork bombs and system control
• Registry/credential access (Windows registry, /etc/shadow)
• Remote code execution (curl | bash, eval(fetch(...)))
• Package manager abuse (npm publish, pip install to system)

Sliding window algorithm with configurable window (default 60s), max requests (default 500), and burst limit (default 750). Per-IP tracking with X-RateLimit-* response headers.

Real-time broadcasts via WebSocket at ws://localhost:8080/ws (attached to the HTTP server, same port):

All API responses use a standardized envelope:

{ "success": true, "data": {}, "meta": { "requestId": "uuid", "timestamp": "ISO-8601" } }

Error responses include error codes from a standardized ERROR_CODES enum.

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.

# ─── Server ──────────────────────────────────────── PORT=8080 # Gateway port UI_PORT=5173 # UI dev server port HOST=127.0.0.1 NODE_ENV=development # CORS_ORIGINS= # Additional origins (localhost:UI_PORT auto-included) # BODY_SIZE_LIMIT=1048576 # Max request body size in bytes (default: 1MB) # ─── Database (PostgreSQL) ───────────────────────── # Option 1: Full connection URL # DATABASE_URL=postgresql://user:pass@host:port/db # Option 2: Individual settings POSTGRES_HOST=localhost POSTGRES_PORT=25432 POSTGRES_USER=ownpilot POSTGRES_PASSWORD=ownpilot_secret # Change in production POSTGRES_DB=ownpilot # POSTGRES_POOL_SIZE=10 # DB_VERBOSE=false # ─── Authentication (DB primary, ENV fallback) ───── # AUTH_TYPE=none # none | api-key | jwt # API_KEYS= # Comma-separated keys for api-key auth # JWT_SECRET= # For jwt auth (min 32 chars) # ─── Rate Limiting (DB primary, ENV fallback) ────── # RATE_LIMIT_DISABLED=false # RATE_LIMIT_WINDOW_MS=60000 # RATE_LIMIT_MAX=500 # ─── Security & Encryption ──────────────────────── # ENCRYPTION_KEY= # 32 bytes hex (for OAuth token encryption) # ADMIN_API_KEY= # Admin key for debug endpoints (production) # ─── Data Storage ───────────────────────────────── # OWNPILOT_DATA_DIR= # Override platform-specific data directory # ─── Logging ────────────────────────────────────── LOG_LEVEL=info # ─── Debug (development only) ───────────────────── # DEBUG_AI_REQUESTS=false # DEBUG_AGENT=false # DEBUG_LLM=false # DEBUG_RAW_RESPONSE=false # DEBUG_EXEC_SECURITY=false # ─── Sandbox (advanced) ────────────────────────── # ALLOW_HOME_DIR_ACCESS=false # DOCKER_SANDBOX_RELAXED_SECURITY=false # MEMORY_SALT=change-this-in-production

1. CLI options (highest) - -p, -h, --no-auth
2. PostgreSQL database - settings table
3. Environment variables - .env file
4. Hardcoded defaults (lowest) - config/defaults.ts

Note: In production (Docker), a single port 8080 serves everything — REST API, WebSocket, and the pre-built UI. No separate frontend deployment needed.

cp .env.example .env # Edit .env with your settings # Start OwnPilot + PostgreSQL docker compose --profile postgres up -d # With MQTT broker for edge/IoT devices docker compose --profile postgres --profile mqtt up -d

Open http://localhost:8080 — the gateway serves the bundled React UI, REST API, and WebSocket on the same port.

A multi-arch image (amd64 + arm64) is published to GitHub Container Registry on every release:

docker pull ghcr.io/ownpilot/ownpilot:latest docker run -d \ --name ownpilot \ -p 8080:8080 \ -e DATABASE_URL=postgresql://user:pass@host:5432/ownpilot \ -e NODE_ENV=production \ ghcr.io/ownpilot/ownpilot:latest

Health check: GET http://localhost:8080/health

In development, Vite runs a separate dev server with hot reload:

pnpm dev # Starts gateway (8080) + Vite UI (5173)

Open http://localhost:5173 for development. Vite automatically proxies API calls (/api/*) and WebSocket (/ws) to the gateway on port 8080.

pnpm build # Build all packages (includes UI static assets) ownpilot start # Start production server on port 8080

# Setup wizard (interactive) ./setup.sh # Linux/macOS .\setup.ps1 # Windows PowerShell # Start scripts ./start.sh # Linux/macOS .\start.ps1 # Windows PowerShell # Start options: # --dev Development mode with hot reload (default) # --prod Production mode (build & serve) # --docker Start with Docker Compose # --no-ui Gateway only, without UI # Package scripts pnpm dev # Watch mode for all packages pnpm build # Build all packages pnpm test # Run all tests pnpm test:watch # Watch test mode pnpm test:coverage # Coverage reports pnpm lint # ESLint check pnpm lint:fix # Auto-fix lint issues pnpm typecheck # TypeScript type checking pnpm format # Prettier formatting pnpm format:check # Check formatting pnpm clean # Clear all build artifacts

MIT