Host Applications

Relevant source files

• .gitignore
• apps/cli/package.json
• apps/cloud/package.json
• apps/cloud/src/engine/execution-stack.ts
• apps/desktop/package.json
• apps/host-cloudflare/executor.config.ts
• apps/host-cloudflare/package.json
• apps/host-cloudflare/src/execution.ts
• apps/host-cloudflare/src/plugins.ts
• apps/host-selfhost/executor.config.ts
• apps/host-selfhost/src/execution.ts
• apps/host-selfhost/src/mcp/org-path.ts
• bun.lock
• e2e/CHANGELOG.md
• e2e/cloud/mcp-execution-metering.test.ts
• e2e/package.json
• e2e/selfhost/toolkits-mcp.test.ts
• e2e/src/services.ts
• package.json
• packages/core/api/src/server/execution-stack-middleware.ts
• packages/plugins/desktop-settings/package.json
• packages/react/package.json

Host applications are the entry points of the Executor system. While the core logic resides in the shared SDK and API layers, hosts are responsible for providing the environment-specific infrastructure: database drivers, authentication providers, and runtime substrates for code execution.

Executor provides four primary host environments, each tailoring the shared @executor-js/api and @executor-js/sdk to its specific constraints.

Host Composition Model

Every host follows a standard composition pattern:

1. Define Seams: Implement environment-specific providers for DbProvider, PluginsProvider, HostConfig, and CodeExecutorProvider apps/cloud/src/engine/execution-stack.ts101-107
2. Mount API: Initialize the shared HTTP server and mount it under a host-defined prefix (e.g., /api) apps/cloud/src/engine/execution-stack.ts74-80
3. Bootstrap UI: Serve the @executor-js/react console, typically integrated via Vite apps/cloud/package.json51-55

Host Matrix

Host	Environment	Database	Auth	Primary Use Case
CLI	Node/Bun	SQLite	Device Flow	Terminal automation, local daemons.
Local	Node/Bun	SQLite	Localhost	Personal tool management, local dev.
Desktop	Electron	SQLite	Keychain/OS	Consumer application with native UI.
Cloud	Cloudflare	PostgreSQL	WorkOS/JWT	Managed multi-tenant SaaS.

---

Architecture: From Intent to Execution

The following diagram illustrates how a Host Application bridges the high-level user intent (Natural Language/UI) to the concrete code entities that perform the work.

Execution Path Overview

Sources: apps/cloud/src/engine/execution-stack.ts1-32 packages/core/api/src/server/execution-stack-middleware.ts

---

4.1 CLI Host

The CLI (apps/cli) is the primary interface for terminal-based automation. It manages a local daemon that serves the API and provides an MCP bridge for stdio-based clients.

• Daemon Lifecycle: Handles daemon election and background process management.
• Commands: Includes install, web, daemon, mcp, and call.
• OAuth: Implements the device login flow for authenticating with remote providers.

For details, see CLI Host.

Sources: apps/cli/package.json5-7 apps/cli/src/main.ts

---

4.2 Local Host

The Local host (apps/local) provides a standalone HTTP server and web UI for local environments. It is the foundation for the "Local-first" experience.

• Persistence: Uses SQLite via the FumaDB adapter for local state.
• Vite Integration: Mounts the React console via a dev server or static build.
• Migration: Handles v1-to-v2 schema transitions for local users.

For details, see Local Host.

Sources: apps/cli/package.json29 package.json37

---

4.3 Desktop Host (Electron)

The Desktop app (apps/desktop) wraps the local host in an Electron shell, providing native OS integrations.

• Sidecar: Bundles a supervised daemon process to handle heavy execution logic.
• Native Secrets: Integrates with macOS Keychain and Windows Credential Vault via @executor-js/plugin-keychain.
• Auto-Update: Manages application updates via electron-updater.

For details, see Desktop Host (Electron).

Sources: apps/desktop/package.json24-30 apps/desktop/scripts/build-sidecar.ts

---

4.4 Cloud Host (Cloudflare Workers)

The Cloud host (apps/cloud) is a highly scalable, multi-tenant implementation running on Cloudflare Workers and Durable Objects.

• Durable Objects: Manages MCP sessions and execution state to ensure consistency across the edge.
• Hyperdrive: Connects to PostgreSQL with connection pooling optimized for serverless.
• Billing: Integrates with Autumn for usage-based metering and rate limiting.

For details, see Cloud Host (Cloudflare Workers).

Sources: apps/cloud/src/engine/execution-stack.ts35-50 apps/cloud/package.json69-75

---

4.5 Self-Host and Cloudflare Host

These variants target deployment in private clouds or standard Docker environments.

• Better-Auth: Provides a multi-user authentication system for self-hosted instances.
• Isolation: Implements org-scoped access control and path-based routing for MCP.
• Docker: A unified distribution containing the API, UI, and necessary runtimes.

For details, see Self-Host and Cloudflare Host.

Sources: apps/host-cloudflare/package.json apps/host-selfhost/executor.config.ts

---

Host Entity Mapping

This diagram maps system-level host concepts to the specific code entities that implement them.

Entity Relationship Diagram

Sources: apps/cloud/src/engine/execution-stack.ts38-44 apps/cli/package.json34-36 apps/desktop/package.json8