Executor

https://executor.sh/docs
Admin
Executor is an open-source integration layer and MCP proxy for AI agents that unifies MCP servers,...
Tokens:3,608
Snippets:57
Trust Score:6.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Agent Setup Prompt

Source: https://executor.sh/docs

Use this prompt with an MCP-capable agent to automate the installation and configuration of Executor.

```text
Help me set up Executor and get my first connection working.

Executor is an open source integration layer for AI agents: one place to configure every integration (MCP servers, OpenAPI specs, GraphQL APIs) and connect to them over MCP.

Start by helping me pick the right form to run it in. Chat with me about it rather than jumping straight to a yes/no question, and recommend one. If I just want the fastest path, suggest Executor Cloud (free tier, nothing to install). All forms expose the same functionality, just packaged differently:

Local (everything stays on my machine):
- Desktop app: a native app for Mac, Windows, and Linux. Best for a regular desktop environment.
- CLI (`executor`): best for a headless or server environment.
Both run a local HTTP server as a background service that any MCP client can connect to.

Hosted (use it from multiple agents, including cloud ones, with nothing running locally):
- Executor Cloud: hosted, generous free tier, sign in and start immediately.
- Self-hosted: a Docker image or a Cloudflare Worker.

How to think about it:
- Want all your data on your own machine? Go local: the desktop app for a regular environment, the CLI for a headless one.
- Want to use it from multiple agents (including cloud agents like ChatGPT), or not run anything locally? Go hosted: Executor Cloud is the fastest start; the self-hosted Docker or Cloudflare versions give you full control.

Terms you'll come across:
- Integration: anything you add (an MCP server, an OpenAPI spec, a GraphQL API).
- Connection: one configured instance of an integration. An integration can have many connections, and a connection doesn't have to be authenticated.
- Policy: whether each tool is always allowed, requires approval, or is blocked. Policies start from a sensible default derived from the imported spec (for example, GET requests on an OpenAPI spec are allowed by default).

Once you know which form I want:
1. Walk me through installing it.
2. Connect Executor to you over MCP. Most MCP clients only load servers at startup, so after adding it I may need to restart the client or open a new chat before the Executor tools appear. Tell me if that's needed and wait for me to do it before continuing.
3. Once the tools are available, help me add my first integration and get one tool working end to end.

Docs: https://executor.sh/docs
Source (and the place to start if something breaks): https://github.com/RhysSullivan/executor
```

--------------------------------

### Install Executor CLI

Source: https://executor.sh/docs/local/cli

Global installation commands for various package managers.

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

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

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

```bash
yarn global add executor
```

--------------------------------

### Start the Executor Service

Source: https://executor.sh/docs/local/cli

Commands to register the durable background service and launch the web UI.

```bash
executor install   # install/start the durable background service
executor web        # open the web UI at http://127.0.0.1:4788
```

--------------------------------

### Run Executor via Docker Compose

Source: https://executor.sh/docs/hosted/docker

Starts the container by building from the local repository source.

```bash
docker compose up -d --build
```

--------------------------------

### Configure Docker Volume Mounts

Source: https://executor.sh/docs/hosted/docker

Examples of mounting the data directory to ensure persistence of the SQLite database and encryption keys.

```bash
-v executor-data:/data     # named volume (what compose uses)
# or a host path:
-v /srv/executor:/data
```

--------------------------------

### Run Executor via Docker CLI

Source: https://executor.sh/docs/hosted/docker

Starts the Executor container using the published image with a named volume for data persistence.

```bash
docker run -d \
  --name executor-selfhost \
  -p 4788:4788 \
  -v executor-data:/data \
  ghcr.io/rhyssullivan/executor-selfhost:latest
```

--------------------------------

### Manage Integrations and Tools

Source: https://executor.sh/docs/local/cli

Commands to verify configured integrations and search for available tools.

```bash
executor tools sources   # lists configured integrations + tool counts
```

```bash
executor tools search "send email"      # find tools by intent
executor call github issues --help      # browse a namespace
executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
```

--------------------------------

### Deploy Executor to Cloudflare

Source: https://executor.sh/docs/hosted/cloudflare

Initializes the environment and deploys the worker. This command is idempotent and handles database creation and secret management.

```bash
bunx wrangler login
bun run deploy:setup
```

--------------------------------

### Add an Integration

Source: https://executor.sh/docs/local/cli

Command to add a new source integration via 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"
}'
```

--------------------------------

### Connect a headless MCP client via Service Token

Source: https://executor.sh/docs/hosted/cloudflare

Use these configurations for machine-to-machine authentication when no interactive login is possible.

```bash
npx add-mcp https://executor-cloudflare.<your-subdomain>.workers.dev/mcp \
  --transport http --name executor \
  --header "CF-Access-Client-Id: <client-id>.access" \
  --header "CF-Access-Client-Secret: <client-secret>"
```

```json
{
  "executor": {
    "type": "http",
    "url": "https://executor-cloudflare.<your-subdomain>.workers.dev/mcp",
    "headers": {
      "CF-Access-Client-Id": "<client-id>.access",
      "CF-Access-Client-Secret": "<client-secret>"
    }
  }
}
```

--------------------------------

### Run Executor with Docker

Source: https://executor.sh/docs/hosted/docker

Deploys the Executor container with a persistent data volume and a configured public base URL.

```bash
docker run -d \
  -p 4788:4788 \
  -v executor-data:/data \
  -e EXECUTOR_WEB_BASE_URL=https://executor.example.com \
  ghcr.io/rhyssullivan/executor-selfhost:latest
```

--------------------------------

### Connect an MCP Agent

Source: https://executor.sh/docs/local/cli

Commands to register Executor with an MCP client using either HTTP or stdio transport.

```bash
npx add-mcp http://127.0.0.1:4788/mcp --transport http --name executor
```

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

--------------------------------

### Connect an interactive MCP client via Managed OAuth

Source: https://executor.sh/docs/hosted/cloudflare

Use this command to connect an MCP client when Managed OAuth is enabled in the Cloudflare Access application.

```bash
npx add-mcp https://executor-cloudflare.<your-subdomain>.workers.dev/mcp \
  --transport http --name executor
```

--------------------------------

### Configure Cloudflare Access

Source: https://executor.sh/docs/hosted/cloudflare

Deploys the worker with the required Access Audience and Team Domain variables to enforce authentication.

```bash
bunx wrangler deploy \
  --var ACCESS_AUD:<aud> \
  --var ACCESS_TEAM_DOMAIN:<your-team>.cloudflareaccess.com
```

--------------------------------

### Resume Execution

Source: https://executor.sh/docs/local/cli

Command to resume a paused execution using its ID.

```bash
executor resume --execution-id exec_123
```
Tokens:
Raw