Overview

Relevant source files

• .gitignore
• apps/cli/package.json
• apps/cloud/package.json
• apps/desktop/package.json
• apps/host-selfhost/package.json
• bun.lock
• e2e/CHANGELOG.md
• e2e/package.json
• package.json
• packages/core/config/package.json
• packages/core/execution/package.json
• packages/core/sdk/package.json
• packages/hosts/cloudflare/package.json
• packages/kernel/core/package.json
• packages/kernel/runtime-quickjs/package.json
• packages/plugins/desktop-settings/package.json
• packages/plugins/file-secrets/package.json
• packages/plugins/graphql/package.json
• packages/plugins/keychain/package.json
• packages/plugins/mcp/package.json
• packages/plugins/onepassword/package.json
• packages/plugins/openapi/package.json
• packages/react/package.json
• patches/@modelcontextprotocol%2Fclient@2.0.0.patch
• scripts/bootstrap.ts
• scripts/check-patched-deps.ts

Executor is an open-source integration layer designed to connect AI agents to any tool or API. It provides a unified catalog for MCP servers, OpenAPI specs, and GraphQL endpoints, allowing developers to configure authentication and execution policies once and share them across any MCP-compatible agent (e.g., Claude Code, Cursor, or ChatGPT). package.json5-13

The project is built as a monorepo using Bun and Turbo, emphasizing a "run it your way" philosophy with deployment targets ranging from a local CLI and Desktop app to a hosted Cloudflare Worker environment. bun.lock5-30 bun.lock27 package.json93-97

Core Concepts

The Executor domain model is built on three foundational pillars that govern how tools are discovered, authenticated, and executed.

Concept	Description	Code Entity
Integration	A blueprint or definition of a service (e.g., a specific MCP server, an OpenAPI spec URL, or a GraphQL API).	Integration packages/core/sdk/src/integration.ts99-105
Connection	A configured instance of an Integration. This holds specific configuration and authentication state (e.g., a user's GitHub OAuth token).	Connection packages/core/sdk/src/connection.ts22-29
Policy	Governance rules that determine if a tool is allowed, requires manual approval, or is blocked.	ToolPolicy packages/core/sdk/src/policies.ts114-125

For details, see Core Concepts: Integrations, Connections, and Policies.

Concept to Code Mapping

The following diagram bridges the high-level concepts to their primary implementations within the SDK and persistence layer.

Diagram: Domain Mapping

Sources: packages/core/sdk/src/core-schema.ts34-44 packages/core/sdk/src/executor.ts1-10

Monorepo Organization

Executor is organized as a Bun-powered monorepo bun.lock5-6 using turbo for task orchestration bun.lock27 It separates the execution logic from plugins and various host implementations.

• apps/: Contains the product composition roots, such as the CLI (apps/cli), Cloud (apps/cloud), and Desktop (apps/desktop) applications. bun.lock32 bun.lock61 bun.lock134
• packages/core/: Houses core contracts, the SDK, and API definitions. apps/cli/package.json27-31
• packages/plugins/: Implements various protocol integrations (e.g., plugin-openapi, plugin-mcp, plugin-graphql). apps/cloud/package.json48-52
• packages/kernel/ (referenced via runtimes): Provides execution runtimes like runtime-quickjs and runtime-dynamic-worker. apps/cloud/package.json54-55 apps/cli/package.json30
• packages/hosts/: Contains shared logic for specific hosting environments, such as host-mcp and host-cloudflare. apps/cloud/package.json43-47

For details, see Monorepo Structure and Development Setup.

Diagram: System Architecture

Sources: bun.lock32-50 bun.lock61-110 bun.lock134-171 apps/cli/package.json25-37 packages/plugins/openapi/package.json1-2 packages/plugins/mcp/package.json1-2 packages/plugins/graphql/package.json1-2 packages/plugins/keychain/package.json1-2 packages/kernel/runtime-quickjs/package.json1-2 packages/kernel/runtime-dynamic-worker/package.json1-2

Getting Started

There are several primary ways to run Executor, all sharing the same core logic and functionality, just packaged differently.

1. Executor Cloud: The fastest path, accessible via https://executor.sh, requiring no local installation.
2. CLI: A command-line interface that runs a local background service. It can be installed globally via npm install -g executor. apps/cli/package.json5-7
3. Desktop App: A native application for Mac, Windows, and Linux, providing the same runtime in a graphical interface. apps/desktop/package.json58
4. Self-Hosted: Options for deploying on your own infrastructure using Docker or as a Cloudflare Worker. apps/cloud/package.json25

For practical onboarding and code examples, see Getting Started: Quick Start and Examples.

Key Developer Commands

The monorepo leverages turbo for efficient task execution across packages and bun as the package manager and runtime. bun.lock27 package.json32-71

Command	Description	File Reference
bun run bootstrap	Bootstraps the workspace and patches dependencies.	package.json33
bun run build	Builds the application or package (e.g., binary for CLI).	apps/cli/package.json13
bun run dev	Starts development servers with proxying and live reload.	package.json35
bun run test	Executes Vitest unit and integration tests.	package.json38
bun run typecheck	Performs static type analysis using tsgo.	package.json42
bun run deploy	Deploys the application to production (e.g., Cloudflare).	apps/cloud/package.json25

Sources: package.json32-71 apps/cli/package.json12-23 apps/cloud/package.json6-36