# Overview

> What Executor exposes (CLI, web UI, HTTP API, MCP, SDK), runtime forms (local, cloud, self-host), and the shortest path from install to first tool call.

- Repository: RhysSullivan/executor
- GitHub: https://github.com/RhysSullivan/executor
- Human docs: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052
- Complete Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/llms-full.txt

## Source Files

- `README.md`
- `vision.md`
- `apps/docs/index.mdx`
- `package.json`
- `AGENTS.md`

---

---
title: "Overview"
description: "What Executor exposes (CLI, web UI, HTTP API, MCP, SDK), runtime forms (local, cloud, self-host), and the shortest path from install to first tool call."
---

Executor is an open-source integration layer: one catalog for every tool, shared across every agent you use. Configure integrations once (OpenAPI specs, GraphQL endpoints, upstream MCP servers), attach credentials and per-tool policies, then reach the same catalog from a CLI, web UI, HTTP API, MCP endpoint, or embedded SDK.

Executor is not AI-specific and not code-mode specific. It is a category of source and a way to interop between them. The product ships primitives (tools, integrations, connections, policies, plugins) that hosts compose into local, cloud, or self-hosted runtimes.

## Core concepts

| Concept | What it is | Identity |
| --- | --- | --- |
| **Tool** | A callable operation with optional JSON input and output schemas | Address: `tools.<integration>.<owner>.<connection>.<tool>` |
| **Integration** | Tenant-level catalog entry for an API surface (OpenAPI, GraphQL, MCP, plugin-registered source) | `slug` (integration slug) |
| **Connection** | Owner-scoped credential bound to one integration; produces that integration's tools | `(owner, integration, name)` |
| **Policy** | Per-tool gate: allow, require approval, or block | Owner-scoped pattern + action |

Tools are produced per connection. An integration can have many connections. Policies start from sensible defaults derived from the imported spec (for example, GET operations on an OpenAPI integration are allowed by default) and can be overridden per owner.

## What Executor exposes

All runtimes share the same core HTTP API groups and the same React web console. Hosts add plugin-specific routes on top.

| Surface | Entry point | Typical use |
| --- | --- | --- |
| **CLI** | `executor` global binary | Install a background service, open the web UI, call tools, manage daemon/service lifecycle |
| **Web UI** | `executor web` or hosted origin | Add integrations, configure connections, manage policies, approve paused executions |
| **HTTP API** | `{origin}/api` | Programmatic catalog, connection, execution, and policy management |
| **MCP** | `executor mcp` (stdio) or `{origin}/mcp` (streamable HTTP) | Single MCP endpoint in front of all integrations for Cursor, Claude Code, and other MCP clients |
| **SDK** | `@executor-js/sdk` (`createExecutor`) | Embed Executor in application code with plugins and credential providers |

### CLI

The published `executor` package is the primary local entry point. Root subcommands include:

| Command | Purpose |
| --- | --- |
| `install` | Register and start the OS-supervised background service |
| `web` | Open the running web UI (or start a foreground runtime with `--foreground`) |
| `mcp` | Start an MCP server over stdio |
| `call` | Invoke a tool by path segments |
| `resume` | Resume a paused execution (auth or approval) |
| `tools` | Search, list sources, and describe tool schemas |
| `daemon` | Manage the local daemon (`run`, `status`, `stop`, `restart`) |
| `service` | Manage the OS service unit (`install`, `uninstall`, `status`, `restart`) |
| `server` | Manage CLI server connection profiles (local or remote) |
| `login` / `logout` / `whoami` | Device login against hosted Executor |

`executor call`, `executor resume`, and `executor tools` auto-start a local daemon when needed. If the default port is busy, the CLI picks an available local port and records it in the server manifest.

### HTTP API

The core API (`ExecutorApi`) is composed from these groups:

| Group | Routes (prefix) | Responsibility |
| --- | --- | --- |
| `tools` | `/tools`, `/tools/schema` | List and inspect tool metadata and schemas |
| `integrations` | `/integrations` | Tenant catalog: detect, register, list, remove integrations |
| `connections` | `/connections` | Owner-scoped credentials bound to integrations |
| `providers` | `/providers` | Credential provider discovery and item browsing |
| `executions` | `/executions` | Code-mode execute and resume (QuickJS); paused state for auth and approval |
| `oauth` | `/oauth` | OAuth client and token flows |
| `policies` | `/policies` | Owner-scoped tool policies |

Protocol plugins (OpenAPI, GraphQL, MCP, and others) register additional route groups on the same API surface.

### MCP proxy

Executor acts as a single MCP endpoint in front of OpenAPI, GraphQL, and upstream MCP integrations. Agents connect to Executor; Executor attaches connection credentials, enforces policies, and forwards calls upstream. Credentials stay in Executor, not in the agent sandbox.

Two transport options:

- **stdio**: `executor mcp` (launched by the MCP client)
- **streamable HTTP**: `{origin}/mcp` (shown on the Connect card in the web UI)

Use `npx add-mcp` to write client config. Most MCP clients load servers at startup, so restart the client after adding Executor.

### SDK

`@executor-js/sdk` exports `createExecutor`, plugin wiring, typed IDs (`IntegrationSlug`, `ToolAddress`, `Owner`, and others), connection and tool APIs, and policy helpers. A promise-mode entry point (`@executor-js/sdk/promise`) is available for scripts. See `examples/docs-sdk-quickstart` for a minimal end-to-end walkthrough.

## Runtime forms

All forms expose the same functionality, packaged for different deployment models.

| Form | Package / entry | Data location | Best for |
| --- | --- | --- | --- |
| **Local CLI** | `executor` + `@executor-js/local` | `~/.executor` (or `EXECUTOR_DATA_DIR`) | Headless or server environments; durable background service |
| **Desktop app** | `@executor-js/desktop` | Same `~/.executor` path as CLI | Native Mac, Windows, Linux with a GUI |
| **Executor Cloud** | `@executor-js/cloud` (Cloudflare Workers) | Hosted Postgres + blob storage | Fastest start; share catalog across cloud and local agents |
| **Self-host (Docker)** | `@executor-js/host-selfhost` | SQLite under `EXECUTOR_DATA_DIR` | Full control on your infrastructure |
| **Self-host (Cloudflare)** | `@executor-js/host-cloudflare` | Cloudflare Durable Objects / storage | Edge-deployed multi-tenant hosting |

Local CLI and desktop share state on the same machine via the same data directory, so integrations, connections, and policies configured in one are visible in the other.

The supervised background service binds loopback by default (port `4789` unless overridden). Clients discover the live origin and bearer token from `server.json` under the data directory.

## Architecture

```mermaid
flowchart TB
  subgraph clients [Clients]
    CLI[CLI]
    Web[Web UI]
    MCP[MCP clients]
    App[Embedded SDK app]
  end

  subgraph executor [Executor runtime]
    API[HTTP API /api]
    MCPsrv[MCP /mcp]
    Core[createExecutor + plugins]
    Exec[QuickJS executions]
  end

  subgraph upstream [Upstream integrations]
    OAS[OpenAPI APIs]
    GQL[GraphQL endpoints]
    UMCP[Upstream MCP servers]
  end

  CLI --> API
  Web --> API
  MCP --> MCPsrv
  App --> Core
  API --> Core
  MCPsrv --> Core
  Core --> Exec
  Core --> OAS
  Core --> GQL
  Core --> UMCP
```

Monorepo package roles:

- `packages/core/sdk`: contracts, plugin wiring, scopes, secrets, policies
- `packages/core/api`: HTTP API definition and server composition
- `packages/plugins/*`: protocol and credential provider plugins
- `packages/hosts/mcp`: MCP serving envelope (`/mcp`)
- `packages/kernel/*`: execution runtimes (QuickJS, dynamic worker)
- `apps/local`, `apps/cloud`, `apps/cli`, `apps/desktop`: product entry points

Published plugins include OpenAPI, GraphQL, MCP, file-secrets, keychain, 1Password, Google, Microsoft, encrypted-secrets, and WorkOS Vault (cloud).

## Shortest path to a first tool call

<Steps>
  <Step title="Install the CLI">

Requires Node.js 20 or newer.

<CodeGroup>

```bash npm
npm install -g executor
```

```bash pnpm
pnpm add -g executor
```

```bash bun
bun add -g executor
```

</CodeGroup>

  </Step>
  <Step title="Start the background service">

```bash
executor install
```

This registers Executor with the OS service manager (launchd, systemd, or Task Scheduler) so the HTTP runtime survives restarts. For a temporary foreground server instead:

```bash
executor web --foreground
```

  </Step>
  <Step title="Open the web UI">

```bash
executor web
```

The CLI prints a signed-in URL (with `?_token=` when bearer auth is enabled) and opens your browser.

  </Step>
  <Step title="Add an integration">

In the web UI, go to **Add Source** and paste an OpenAPI, GraphQL, or MCP URL. Executor detects the type, indexes tools, and surfaces auth method descriptors.

Or from the CLI:

```bash
executor call executor openapi addSource '{
  "spec": "https://petstore3.swagger.io/api/v3/openapi.json",
  "namespace": "petstore",
  "baseUrl": "https://petstore3.swagger.io/api/v3"
}'
```

  </Step>
  <Step title="Call a tool">

Verify tools are indexed:

```bash
executor tools sources
executor tools search "list pets"
```

Invoke by path:

```bash
executor call petstore findPetsByStatus '{"status":"available"}'
```

If execution pauses for auth or approval:

```bash
executor resume --execution-id <id>
```

  </Step>
  <Step title="Optional: connect an MCP client">

```bash
npx add-mcp "executor mcp" --name executor
```

Or use the streamable HTTP endpoint from the Connect card:

```bash
npx add-mcp http://127.0.0.1:<port>/mcp --transport http --name executor
```

Restart the MCP client so Executor tools appear.

  </Step>
</Steps>

## Configuration essentials

| Variable / path | Default | Purpose |
| --- | --- | --- |
| `EXECUTOR_DATA_DIR` | `~/.executor` | Runtime data, SQLite DB, `auth.json`, `server.json` |
| `EXECUTOR_WEB_BASE_URL` | `http://localhost:<port>` | Public origin for OAuth redirects and absolute links |
| `PORT` | `4788` (daemon), `4789` (supervised service) | HTTP listen port |

See the configuration reference for bootstrap admin env vars, secret keys, scope directories, and client-specific overrides.

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    Install the published CLI globally, bootstrap a development checkout, and verify the background service starts.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    End-to-end walkthrough: install, open the web UI, add an integration, call a tool, and resume a paused execution.
  </Card>
  <Card title="MCP proxy" href="/mcp-proxy">
    How Executor fronts OpenAPI, GraphQL, and upstream MCP with shared auth and per-tool policies.
  </Card>
  <Card title="Connect MCP clients" href="/connect-mcp-clients">
    Wire Cursor, Claude Code, and other clients via stdio or streamable HTTP.
  </Card>
  <Card title="Embed with the SDK" href="/embed-sdk">
    Compose `createExecutor` with plugins and credential providers in application code.
  </Card>
  <Card title="Hosted cloud" href="/hosted-cloud">
    Sign in to Executor Cloud and use the shared hosted MCP endpoint.
  </Card>
</CardGroup>