Local Host

Relevant source files

• apps/cloud/src/app-paths.test.ts
• apps/desktop/electron.vite.config.ts
• apps/local/executor.config.ts
• apps/local/src/db/data-dir-ownership.test.ts
• apps/local/src/db/data-dir-ownership.ts
• apps/local/src/db/data-migrations.ts
• apps/local/src/db/owned-database.test.ts
• apps/local/src/db/v1-v2-boot-drive.test.ts
• apps/local/src/db/v1-v2-ledger.test.ts
• apps/local/src/db/v1-v2-migration.test.ts
• apps/local/src/db/v1-v2-migration.ts
• apps/local/src/executor.ts
• apps/local/src/main.ts
• apps/local/src/mcp.ts
• apps/local/src/serve-shared.test.ts
• apps/local/src/serve-shared.ts
• apps/local/src/serve.test.ts
• apps/local/src/serve.ts
• apps/local/vite.config.ts
• e2e/cloud/sources-api.test.ts
• e2e/local/toolkits-mcp.test.ts
• e2e/scenarios/toolkits-mcp.test.ts
• packages/core/api/src/server.ts
• packages/core/api/src/server/executor-app.ts
• packages/core/api/src/server/oauth-client-metadata.test.ts
• packages/core/api/src/server/oauth-client-metadata.ts
• packages/core/sdk/src/connections.test.ts
• packages/core/sdk/src/errors.ts
• packages/core/sdk/src/ids.ts
• packages/core/sdk/src/migration-oauth-metadata.ts
• packages/core/sdk/src/migration-spec.test.ts
• packages/core/sdk/src/migration-spec.ts
• packages/core/sdk/src/plugin-storage.test.ts
• packages/core/sdk/src/plugin-storage.ts
• packages/plugins/google/src/sdk/openapi-ownership-migration.test.ts
• packages/plugins/google/src/sdk/openapi-ownership-migration.ts

The Local Host (apps/local) is the primary distribution of Executor for local development and CLI usage. It provides a production-grade Bun server that hosts the React-based console, a local SQLite database, and a specialized MCP (Model Context Protocol) endpoint for local tool execution.

System Architecture

The Local Host is built on top of the Effect runtime and Bun. It orchestrates the lifecycle of the Executor instance, the SQLite storage layer, and the HTTP server.

Key Components and Data Flow

Title: Local Host Request Flow

Sources: apps/local/src/serve.ts18-27 apps/local/src/executor.ts189-210 apps/local/src/mcp.ts167-177

HTTP Server and Routing

The server is implemented in serve.ts using Bun.serve. It handles three distinct types of traffic:

1. Static Assets: Serves the Vite-built SPA. In production, these are collected from the filesystem or embedded via Bun's file system routing apps/local/src/serve.ts57-80
2. API Routes: Proxies /api/* requests to the ServerHandlers provided by the core API package apps/local/src/main.ts18-25
3. MCP Endpoint: Specialized /mcp and /mcp/toolkits/:slug routes for the Model Context Protocol apps/local/src/mcp.ts107-113

Authentication and Security

Local Host uses a Bearer Token for all non-public routes.

• Token Management: The server mints a local token stored in ~/.executor/server-control/auth.json with 0600 permissions apps/local/src/serve.test.ts134-142
• Authorization Gate: The makeIsAuthorized function validates the Authorization header against this local token apps/local/src/serve-shared.ts127-133
• Exemptions: Public routes include /api/health and the OAuth callback /api/oauth/callback (which is state-gated instead of bearer-gated) apps/local/src/serve.ts23-25

SQLite Database Setup

The Local Host uses LibSQL (a SQLite fork) for persistence.

Ownership and Locking

To prevent data corruption from multiple concurrent processes, the host implements a locking mechanism:

• Data Directory Ownership: Before opening the database, the host acquires a lock file (data.db.owner-lock) apps/local/src/db/data-dir-ownership.ts6-10
• Automatic Release: The lock is released when the server process shuts down or if the database fails to initialize apps/local/src/serve.test.ts88-100

Data Migrations

The host manages two types of migrations:

1. Schema Migrations: Handled by Drizzle ORM to keep the SQLite tables in sync with the codebase.
2. Data Migrations: Logic-heavy migrations (e.g., reformatting JSON blobs) defined in localDataMigrations and tracked in the data_migration table apps/local/src/executor.ts169-180

v1-to-v2 Database Migration

A significant part of the Local Host is the migration engine that converts legacy "v1" Executor databases to the modern "v2" FumaDB schema.

Title: v1-to-v2 Migration Logic

Sources: apps/local/src/db/v1-v2-migration.ts155-163 apps/local/src/db/v1-v2-migration.ts174-183 apps/local/src/db/v1-v2-migration.ts191-195

The migration includes:

• Auth File Migration: Moving keys from the legacy auth.json into the new Credential Providers apps/local/src/db/v1-v2-migration.ts111-113
• Schema Mapping: Converting source rows to integration rows and connection rows apps/local/src/db/v1-v2-migration.ts34-35

Vite Dev Server Integration

During development (EXECUTOR_DEV=1), the Local Host provides a seamless developer experience by integrating with Vite.

• Proxying: The Bun server spawns a Vite child process and proxies non-API requests (HTML/JS/CSS) to it apps/local/src/serve.ts126-158
• HMR Support: The host passes EXECUTOR_DEV_VITE_PORT to the child process so the Vite HMR client can connect directly to the Vite port, bypassing the Bun proxy which does not support WebSockets apps/local/src/serve.ts151-154
• API Forwarding: The executorApiPlugin in vite.config.ts allows the Vite dev server to handle /api and /mcp requests by invoking the Effect handlers in-process apps/local/vite.config.ts66-72

Executor Configuration

The local host configuration is defined in apps/local/executor.config.ts. It acts as the single source of truth for the plugins loaded into the local environment.

Plugin Category	Specific Plugins
API Protocols	openApiHttpPlugin, graphqlHttpPlugin, mcpHttpPlugin
SaaS Presets	googleHttpPlugin, microsoftHttpPlugin
Secret Storage	keychainPlugin, fileSecretsPlugin, onepasswordHttpPlugin
Host Specific	desktopSettingsPlugin, toolkitsPlugin

Sources: apps/local/executor.config.ts26-43

MCP Endpoint Implementation

The local MCP implementation (mcp.ts) bridges the Model Context Protocol to the Executor's ExecutionEngine.

• Transport: Supports WebStandardStreamableHTTPServerTransport for long-running HTTP connections apps/local/src/mcp.ts126-130
• Session Management: Maps mcp-session-id headers to specific ExecutionEngine instances and McpServer states apps/local/src/mcp.ts170-174
• Toolkit Scoping: Routes requests to /mcp/toolkits/:slug to filter the available tool catalog based on a specific toolkit definition apps/local/src/mcp.ts107-113
• Approval Lifecycle: Handles paused executions by serving a detail view to the console and accepting resume/reject decisions via handleApprovalRequest apps/local/src/mcp.ts40-42

Sources: apps/local/src/mcp.ts37-44 apps/local/src/mcp.ts105-113