Privacy-first personal AI assistant platform with autonomous agents, tool orchestration, multi-provider support, and Telegram integration.

Self-hosted. Your data stays yours.

• Features
• Architecture
• Quick Start
• Project Structure
• Packages
  • Core
  • Gateway
  • UI
  • Channels
  • CLI
• AI Providers
• Agent System
• Tool System
• 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) + 7 OpenAI-compatible providers + any custom endpoint
• Local AI Support - Ollama and LM Studio auto-discovery on the local network
• Smart Provider Routing - Cheapest, fastest, smartest, balanced, or fallback strategies
• 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

• 100+ Built-in Tools across 20+ categories (personal data, files, code execution, web, email, media, finance, automation, utilities)
• 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
• Custom Tools - Create new tools at runtime via LLM (sandboxed JavaScript)
• 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 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

• 5 Autonomy Levels - Manual, Assisted, Supervised, Autonomous, Full
• Triggers - Schedule-based (cron), event-driven, condition-based, webhook
• Plans - Multi-step autonomous execution with checkpoints, retry logic, and timeout handling
• Risk Assessment - Automatic risk scoring for tool executions with approval workflows

• Web UI - React 19 + Vite 6 + Tailwind CSS 4 with dark mode, ~40 routes, code-split
• Telegram Bot - Full bot integration with user/chat filtering, message splitting, HTML/Markdown formatting
• WebSocket - Real-time updates, event subscriptions, session management
• REST API - 40 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

                         ┌──────────────┐
                         │   Web UI     │  React 19 + Vite 6
                         │  (Port 5173) │  Tailwind CSS 4
                         └──────┬───────┘
                                │ HTTP + SSE
              ┌─────────────────┼─────────────────┐
              │                 │                  │
     ┌────────┴────────┐       │        ┌─────────┴──────────┐
     │  Telegram Bot   │       │        │     WebSocket      │
     │   (Channels)    │       │        │    (Port 18789)    │
     └────────┬────────┘       │        └─────────┬──────────┘
              │                │                   │
              └────────┬───────┘───────────────────┘
                       │
              ┌────────▼────────┐
              │    Gateway      │  Hono HTTP API Server
              │  (Port 8080)    │  40 Route Modules
              ├─────────────────┤
              │  MessageBus     │  Middleware Pipeline
              │  Agent Engine   │  Tool Orchestration
              │  Provider Router│  Smart Model Selection
              │  Plugin System  │  Extensible Architecture
              │  EventBus       │  Typed Event System
              ├─────────────────┤
              │     Core        │  AI Engine & Tool Framework
              │  100+ Tools     │  Multi-Provider Support
              │  Sandbox, Crypto│  Privacy, Audit
              └────────┬────────┘
                       │
              ┌────────▼────────┐
              │   PostgreSQL    │  40+ Repositories
              │                 │  Conversations, Personal Data,
              │                 │  Memories, Goals, Triggers, Plans
              └─────────────────┘

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

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

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

# Clone and install
git clone https://github.com/ownpilot/ownpilot.git
cd ownpilot
pnpm install

# Configure
cp .env.example .env
# Edit .env with database connection details
# AI provider API keys are configured via the Config Center UI after setup

# Start development (gateway + ui)
pnpm dev

# UI: http://localhost:5173
# API: http://localhost:8080

# Initialize database
ownpilot setup

# Start server + channels
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
│   │   │   │   └── tools/       # 100+ 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
│   │   │   ├── assistant/       # Intent classifier, orchestrator
│   │   │   ├── workspace/       # Per-user isolated environments
│   │   │   └── types/           # Branded types, Result<T,E>, guards
│   │   └── package.json
│   │
│   ├── gateway/                 # Hono API server (~60K LOC)
│   │   ├── src/
│   │   │   ├── routes/          # 38 route modules
│   │   │   ├── services/        # 32 business logic services
│   │   │   ├── db/
│   │   │   │   ├── repositories/  # 40+ data access repositories
│   │   │   │   ├── adapters/      # PostgreSQL adapter
│   │   │   │   ├── migrations/    # Schema migrations
│   │   │   │   └── seeds/         # Default data
│   │   │   ├── channels/        # Telegram channel plugin
│   │   │   ├── plugins/         # Plugin initialization & registration
│   │   │   ├── triggers/        # Proactive automation engine
│   │   │   ├── plans/           # Plan executor with step handlers
│   │   │   ├── autonomy/        # Risk assessment, approval manager
│   │   │   ├── ws/              # WebSocket server & session management
│   │   │   ├── 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
│   │   ├── src/
│   │   │   ├── pages/           # ~40 page components
│   │   │   ├── components/      # 30+ reusable components
│   │   │   ├── hooks/           # Custom hooks (chat store, theme, WebSocket)
│   │   │   ├── api/             # Typed fetch wrapper + 18 endpoint modules
│   │   │   ├── types/           # UI type definitions
│   │   │   └── App.tsx          # Route definitions with lazy loading
│   │   └── package.json
│   │
│   ├── channels/                # Telegram bot (Grammy)
│   │   ├── src/
│   │   │   ├── telegram/        # Telegram Bot API wrapper
│   │   │   ├── manager.ts       # Channel orchestration
│   │   │   └── types/           # Channel type definitions
│   │   └── 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 9 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).

~67,000 LOC across 156 source files.

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

~60,000 LOC across 179 source files. 120 test files with 4,524 tests.

Route Modules (40):

Services (32): MessageBus, ConfigCenter, ToolExecutor, ProviderService, AuditService, PluginService, MemoryService, GoalService, TriggerService, PlanService, WorkspaceService, DatabaseService, SessionService, LogService, ResourceService, LocalDiscovery, and more.

Repositories (40+): 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, costs, settings, config-services, pomodoro, habits, captures, workspaces, model-configs, execution-permissions, logs, and more.

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

Pages (~40):

Key Components: Layout (sidebar nav), ChatInput, MessageList, ToolExecutionDisplay, TraceDisplay, CodeBlock, MarkdownContent, ExecutionApprovalDialog, SuggestionChips, ToastProvider, 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

Telegram bot built on Grammy. Implements the ChannelHandler interface with start(), stop(), sendMessage(), and onMessage().

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

ownpilot setup                    # Initialize database
ownpilot start                    # Start server + channels
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.

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

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
• 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)
• Streaming - Real-time SSE responses with tool execution progress events

OwnPilot has 100+ tools organized into 20+ 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

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

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

Memories have importance scoring, are automatically injected into agent system prompts, 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:

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

PostgreSQL with 40+ 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

Channels: channel_messages, channel_users, channel_sessions

System: plugins, custom_tools, custom_data_tables, config_services, execution_permissions, workspaces, model_configs

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

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.

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=0.0.0.0
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
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

# Build and run production image
docker build -t ownpilot .
docker run -p 8080:8080 --env-file .env ownpilot

# Build all packages
pnpm build

# Start production server
ownpilot start

# Or start individually
pnpm --filter @ownpilot/gateway start
pnpm --filter @ownpilot/ui preview

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