# Executor Documentation > Reference for Executor, the open-source integration layer that exposes one tool catalog across CLI, HTTP API, MCP, and TypeScript SDK runtimes. Covers local daemon, hosted cloud, self-host deployments, credentials, policies, and code execution. ## Context Links - [Agent index](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/llms.txt) - [Human interactive docs](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052) - [GitHub repository](https://github.com/RhysSullivan/executor) ## Repository Metadata - Repository: RhysSullivan/executor - Generated: 2026-06-23T19:29:14.099Z - Updated: 2026-06-23T19:30:14.094Z - Runtime: Grok CLI - Format: Documentation - Pages: 24 ## Page Index - 01. [Overview](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/01-overview.md) - 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. - 02. [Installation](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/02-installation.md) - Install the published CLI globally, bootstrap a development checkout, and verify the background service starts with expected ports and data directories. - 03. [Quickstart](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/03-quickstart.md) - Run `executor install`, open the web UI, add a first integration, search and call a tool, and resume a paused execution. - 04. [MCP proxy](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/04-mcp-proxy.md) - How Executor acts as a single MCP endpoint in front of OpenAPI, GraphQL, and upstream MCP integrations with shared auth and per-tool policies. - 05. [Tools](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/05-tools.md) - Tool addresses, discovery, schema inspection, invocation paths, and how tools are produced per connection across CLI, HTTP API, and MCP surfaces. - 06. [Integrations](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/06-integrations.md) - Tenant-level catalog identities for OpenAPI specs, GraphQL endpoints, MCP servers, and plugin-registered sources; detection, registration, and auth method descriptors. - 07. [Connections](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/07-connections.md) - Owner-scoped credentials bound to integrations, credential provider resolution, OAuth minting, and the `(owner, integration, name)` identity model. - 08. [Policies](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/08-policies.md) - Per-tool allow, require-approval, and block actions; pattern matching, effective policy resolution, and default annotations derived from integration specs. - 09. [Executions](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/09-executions.md) - Code-mode execution via QuickJS, paused states for auth and approval, `execute` and `resume` HTTP routes, and MCP elicitation handling. - 10. [Add integrations](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/10-add-integrations.md) - Add OpenAPI, GraphQL, and MCP sources from the web UI or CLI, including spec URLs, namespaces, base URLs, and post-add verification with `tools sources`. - 11. [Connect MCP clients](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/11-connect-mcp-clients.md) - Wire Cursor, Claude Code, OpenCode, and other MCP clients via stdio (`executor mcp`) or streamable HTTP, including `add-mcp` setup and client restart requirements. - 12. [Configure credentials](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/12-configure-credentials.md) - Credential providers (file secrets, keychain, 1Password, encrypted stores), connection creation payloads, OAuth flows, and placement-based auth templates. - 13. [Manage policies](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/13-manage-policies.md) - Create and update owner-scoped tool policies, interpret effective policy precedence, and handle approval pauses from the web UI, MCP, and CLI resume flow. - 14. [Embed with the SDK](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/14-embed-with-the-sdk.md) - Compose `createExecutor` with plugins and credential providers, register integrations, create connections, list and invoke tools, and shut down cleanly in application code. - 15. [Deploy self-hosted](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/15-deploy-self-hosted.md) - Run Executor in Docker or on Cloudflare Workers: image defaults, volume mounts, bootstrap admin env vars, TLS/public-origin requirements, and sandbox network constraints. - 16. [Executor Cloud](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/16-executor-cloud.md) - Hosted Executor Cloud entry points, sign-in flow, shared MCP endpoint usage, and how cloud deployments differ from local daemon and self-host runtimes. - 17. [CLI reference](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/17-cli-reference.md) - All `executor` subcommands and flags: `install`, `web`, `daemon`, `service`, `mcp`, `call`, `resume`, `tools`, `server`, `login`, and auto-start behavior. - 18. [HTTP API reference](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/18-http-api-reference.md) - Core Executor HTTP API groups: `tools`, `integrations`, `connections`, `providers`, `executions`, `oauth`, and `policies` routes, payloads, and error shapes. - 19. [SDK reference](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/19-sdk-reference.md) - `@executor-js/sdk` exports: `createExecutor`, plugin wiring, tool listing and invocation, connection APIs, policy helpers, typed IDs, and promise-mode entry points. - 20. [Configuration reference](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/20-configuration-reference.md) - Environment variables and runtime paths: `EXECUTOR_DATA_DIR`, `EXECUTOR_SCOPE_DIR`, `EXECUTOR_WEB_BASE_URL`, secret keys, bootstrap admin, ports, and client-specific overrides. - 21. [SDK quickstart example](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/21-sdk-quickstart-example.md) - Walkthrough of `examples/docs-sdk-quickstart`: in-memory credential provider, OpenAPI `addSpec`, connection creation, tool listing, schema inspection, and shutdown. - 22. [Plugin catalog](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/22-plugin-catalog.md) - Published protocol and provider plugins (OpenAPI, GraphQL, MCP, file-secrets, keychain, 1Password, Google, WorkOS Vault) and how `examples/all-plugins` wires them together. - 23. [Develop locally](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/23-develop-locally.md) - Monorepo bootstrap, turbo dev servers, package boundaries, targeted Vitest runs, e2e boot recipes, and release-check scripts for contributors. - 24. [Troubleshooting](https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/24-troubleshooting.md) - Common failure modes: daemon port conflicts, unreachable local server, OAuth login state behind proxies, stale Vite caches, missing bootstrap builds, and recovery commands. ## Source File Index - `AGENTS.md` - `apps/cli/bin/executor.ts` - `apps/cli/package.json` - `apps/cli/src/daemon-state.ts` - `apps/cli/src/daemon.ts` - `apps/cli/src/installation.ts` - `apps/cli/src/integrations.ts` - `apps/cli/src/local-server-manifest.ts` - `apps/cli/src/main.ts` - `apps/cli/src/server-connection.ts` - `apps/cli/src/server-profile.ts` - `apps/cli/src/service.ts` - `apps/cloud/executor.config.ts` - `apps/cloud/package.json` - `apps/docs/concepts/connections.mdx` - `apps/docs/concepts/integrations.mdx` - `apps/docs/concepts/policies.mdx` - `apps/docs/hosted/cloud.mdx` - `apps/docs/hosted/cloudflare.mdx` - `apps/docs/hosted/docker.mdx` - `apps/docs/index.mdx` - `apps/docs/local/cli.mdx` - `apps/docs/mcp-proxy.mdx` - `apps/host-cloudflare/executor.config.ts` - `apps/host-cloudflare/wrangler.jsonc` - `apps/host-selfhost/.env.example` - `apps/host-selfhost/docker-compose.yml` - `apps/host-selfhost/Dockerfile` - `apps/host-selfhost/executor.config.ts` - `apps/local/package.json` - `e2e/AGENTS.md` - `e2e/setup/cloud.globalsetup.ts` - `e2e/src/ports.ts` - `examples/all-plugins/package.json` - `examples/all-plugins/src/main.ts` - `examples/docs-sdk-quickstart/package.json` - `examples/docs-sdk-quickstart/src/main.ts` - `package.json` - `packages/core/api/src/api.ts` - `packages/core/api/src/connections/api.ts` - `packages/core/api/src/executions/api.ts` - `packages/core/api/src/handlers/connections.ts` - `packages/core/api/src/handlers/executions.ts` - `packages/core/api/src/handlers/integrations.ts` - `packages/core/api/src/handlers/oauth.ts` - `packages/core/api/src/handlers/policies.ts` - `packages/core/api/src/handlers/tools.ts` - `packages/core/api/src/integrations/api.ts` - `packages/core/api/src/oauth/api.ts` - `packages/core/api/src/policies/api.ts` - `packages/core/api/src/server/mcp-build.ts` - `packages/core/api/src/tools/api.ts` - `packages/core/execution/src/engine.ts` - `packages/core/integrations-registry/package.json` - `packages/core/sdk/package.json` - `packages/core/sdk/src/connection.ts` - `packages/core/sdk/src/elicitation.ts` - `packages/core/sdk/src/errors.ts` - `packages/core/sdk/src/executor.ts` - `packages/core/sdk/src/http-auth.ts` - `packages/core/sdk/src/ids.ts` - `packages/core/sdk/src/integration.ts` - `packages/core/sdk/src/oauth-service.ts` - `packages/core/sdk/src/policies.ts` - `packages/core/sdk/src/promise.ts` - `packages/core/sdk/src/public-origin.ts` - `packages/hosts/mcp/src/browser-approval-store.ts` - `packages/hosts/mcp/src/browser-approval.ts` - `packages/hosts/mcp/src/index.ts` - `packages/hosts/mcp/src/tool-server.ts` - `packages/kernel/runtime-quickjs/src/index.ts` - `packages/plugins/file-secrets/package.json` - `packages/plugins/file-secrets/src/sdk/plugin.ts` - `packages/plugins/graphql/package.json` - `packages/plugins/graphql/src/sdk/plugin.ts` - `packages/plugins/keychain/src/sdk/plugin.ts` - `packages/plugins/mcp/package.json` - `packages/plugins/mcp/src/sdk/plugin.ts` - `packages/plugins/onepassword/src/sdk/plugin.ts` - `packages/plugins/openapi/package.json` - `packages/plugins/openapi/README.md` - `packages/plugins/openapi/src/promise.ts` - `packages/plugins/openapi/src/sdk/plugin.ts` - `README.md` - `RELEASING.md` - `RUNNING.md` - `scripts/bootstrap.ts` - `scripts/generate-doc-snippets.ts` - `scripts/reap-dev-servers.ts` - `turbo.json` - `vision.md` - `vitest.config.ts` --- ## 01. 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. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/01-overview.md - Generated: 2026-06-23T19:21:51.500Z ### 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** | 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 Requires Node.js 20 or newer. ```bash npm npm install -g executor ``` ```bash pnpm pnpm add -g executor ``` ```bash bun bun add -g executor ``` ```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 ``` ```bash executor web ``` The CLI prints a signed-in URL (with `?_token=` when bearer auth is enabled) and opens your browser. 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" }' ``` 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 ``` ```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:/mcp --transport http --name executor ``` Restart the MCP client so Executor tools appear. ## Configuration essentials | Variable / path | Default | Purpose | | --- | --- | --- | | `EXECUTOR_DATA_DIR` | `~/.executor` | Runtime data, SQLite DB, `auth.json`, `server.json` | | `EXECUTOR_WEB_BASE_URL` | `http://localhost:` | 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 Install the published CLI globally, bootstrap a development checkout, and verify the background service starts. End-to-end walkthrough: install, open the web UI, add an integration, call a tool, and resume a paused execution. How Executor fronts OpenAPI, GraphQL, and upstream MCP with shared auth and per-tool policies. Wire Cursor, Claude Code, and other clients via stdio or streamable HTTP. Compose `createExecutor` with plugins and credential providers in application code. Sign in to Executor Cloud and use the shared hosted MCP endpoint. --- ## 02. Installation > Install the published CLI globally, bootstrap a development checkout, and verify the background service starts with expected ports and data directories. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/02-installation.md - Generated: 2026-06-23T19:21:43.625Z ### Source Files - `apps/docs/local/cli.mdx` - `apps/cli/package.json` - `apps/cli/bin/executor.ts` - `apps/cli/src/installation.ts` - `scripts/bootstrap.ts` - `RUNNING.md` --- title: "Installation" description: "Install the published CLI globally, bootstrap a development checkout, and verify the background service starts with expected ports and data directories." --- The published `executor` npm package ships a Node.js launcher plus a per-platform compiled binary. `executor install` registers an OS-supervised background daemon that binds loopback, writes a `server.json` manifest under the data directory, and survives reboots. Development checkouts use `bun run bootstrap` and run the CLI from source instead of the global binary. ## Prerequisites | Audience | Requirement | | --- | --- | | CLI users | Node.js 20 or newer (`engines.node` on the published package) | | Contributors | [Bun](https://bun.sh) 1.3.x (repo `packageManager`: `bun@1.3.11`) | The global CLI resolves a platform binary from npm `optionalDependencies`. Supported targets are `darwin`/`linux`/`win32` on `x64` and `arm64` (Linux also publishes `musl` variants). If install reports it cannot locate a platform binary, your OS/CPU combination is not in the published matrix. ## Install the published CLI ```bash npm install -g executor ``` ```bash pnpm add -g executor ``` ```bash bun add -g executor ``` ```bash yarn global add executor ``` Confirm the launcher resolves: ```bash executor --help ``` A successful install prints subcommand help without `could not locate a platform binary` or `ENOENT`. ## Start the background service `executor install` is an alias for `executor service install`. Both register the supervised daemon and wait up to 45 seconds for a reachable `server.json` manifest. ```bash executor install ``` On success, output includes the service manager name, web UI origin, data directory, and log path. The command is idempotent: if the service is already running at the requested port with the current binary version, it prints the running origin and exits. On Windows, run `executor install` from an **Administrator** PowerShell. Task Scheduler registration requires elevation. ```bash executor web ``` This reads the active `server.json` manifest and opens the browser to the running origin, including a `?_token=` query when a bearer token is available. For a throwaway foreground server instead of the supervised service, use `executor web --foreground`. ```bash executor service status ``` Expect `Registered: yes`, `Running: yes`, and a `Serving:` line with the live origin. Probe liveness without credentials: ```bash curl -s http://127.0.0.1:4789/api/health ``` ```text ok ``` If the supervised daemon uses a non-default port, substitute that port in the URL. Clients discover the live port from `server.json`, not from a fixed default. ## Ports and service managers | Surface | Default port | Bind address | Notes | | --- | --- | --- | --- | | `executor install` / `executor service install` | `4789` | `127.0.0.1` | OS-supervised daemon (`sh.executor.daemon`) | | `executor daemon run` (auto-start, foreground) | `4788` | `127.0.0.1` | Ephemeral or detached daemon, not OS-supervised | | `executor web --foreground` | `4788` | `127.0.0.1` | Temporary in-terminal server | Override the supervised port: ```bash executor install --port 4790 ``` Port the supervised daemon binds. Defaults to `4789`. Loopback only. | Platform | Service manager | Service label / task | | --- | --- | --- | | macOS | launchd LaunchAgent | `sh.executor.daemon` | | Linux | systemd `--user` + linger | `sh.executor.daemon.service` | | Windows | Task Scheduler (S4U / AtStartup) | `ExecutorDaemon` | On Linux, `executor service status` warns when user lingering is off. Without linger, the daemon starts on login but not at boot. Run `loginctl enable-linger $USER` to fix it. ## Data directory layout By default, local state lives in `~/.executor`. Override with `EXECUTOR_DATA_DIR`. :::files ~/.executor/ ├── data.db # SQLite integrations, connections, policies ├── server-control/ │ ├── auth.json # Stable bearer token (mode 0600) │ ├── server.json # Active server manifest (origin, auth, pid) │ └── startup.lock # In-flight startup guard ├── logs/ │ ├── daemon.log │ └── daemon.error.log ├── daemon-localhost-.json └── daemon-active-localhost-.json ::: Root directory for database, auth, manifests, and logs. Default: `~/.executor`. Scope directory for tool execution context. The supervised service sets this to `EXECUTOR_DATA_DIR` when unset. Foreground daemons default to the current working directory. The supervised unit never embeds secrets. The daemon mints or loads the bearer token from `server-control/auth.json` on boot; `server.json` carries a copy for clients. ## Bootstrap a development checkout Contributors clone the monorepo and run bootstrap before dev servers or tests. ```bash git clone https://github.com/RhysSullivan/executor.git cd executor bun run bootstrap ``` Bootstrap is idempotent. It runs `bun install` (whose `prepare` hook builds `@executor-js/vite-plugin` and `packages/react`, artifacts Vite dev servers require) and installs Playwright Chromium for e2e. ```bash bun run dev:cli -- --help ``` This sets `EXECUTOR_DEV=1` and `EXECUTOR_DATA_DIR=apps/local/.executor-dev` by default. `executor install` and `executor service install` require the **compiled** binary. In a dev checkout they fail with a message to use `bun run apps/cli/src/main.ts daemon run --foreground` instead. ```bash bun run dev:cli -- daemon run --foreground ``` Default port is `4788`. Open the UI against the running manifest: ```bash bun run dev:cli -- web ``` ```bash bun run dev ``` Starts turbo dev servers for apps and packages (excluding desktop and cloud by default). See the develop-locally page for package boundaries, targeted tests, and e2e boot recipes. ## Verification checklist | Signal | Expected result | | --- | --- | | `executor --help` | Exit 0, subcommand list | | `executor install` | Prints origin like `http://127.0.0.1:4789`, data dir, logs path | | `executor service status` | `Registered: yes`, `Running: yes`, `Serving:` with origin | | `GET /api/health` on the serving origin | Body exactly `ok`, no auth header | | `~/.executor/server-control/server.json` | Exists after first successful boot | | `~/.executor/logs/daemon.error.log` | Empty or only startup lines on clean boot | If install times out after 45 seconds, check `~/.executor/logs/daemon.error.log` and re-run `executor service status`. Version drift (running binary older than CLI) is flagged in status output; re-run `executor install` to repoint the unit and restart. ## Common failure modes Another process may hold the default port. Pick a free port with `executor install --port `, or stop the conflicting listener and reinstall. On Windows, orphaned `executor.exe` listeners can survive a stopped scheduled task; `executor service uninstall` attempts cleanup. Expected. OS service managers need the compiled binary path (`process.execPath`). Use `daemon run --foreground` from the dev CLI, or build a local binary with `bun run --cwd apps/cli build` and install from `apps/cli/dist/executor`. Run `bun run bootstrap` from the repo root. Skipping bootstrap leaves dev servers without the prepare-built artifacts. Enable lingering: `loginctl enable-linger $USER`. Without it, the user systemd manager (and the daemon) stops when you log out. Self-hosted Docker uses port `17888` and a different runtime (`apps/host-selfhost`). That path is not the local CLI daemon described here. ## Next Run `executor install`, open the web UI, add a first integration, and call a tool. All `executor` subcommands, flags, and auto-start behavior. Environment variables, paths, ports, and client overrides. Monorepo bootstrap, turbo dev, Vitest, and e2e for contributors. Port conflicts, stale manifests, OAuth behind proxies, and recovery commands. --- ## 03. Quickstart > Run `executor install`, open the web UI, add a first integration, search and call a tool, and resume a paused execution. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/03-quickstart.md - Generated: 2026-06-23T19:22:06.165Z ### Source Files - `README.md` - `apps/docs/local/cli.mdx` - `apps/cli/src/main.ts` - `apps/local/package.json` - `packages/core/api/src/tools/api.ts` - `packages/core/api/src/executions/api.ts` --- title: "Quickstart" description: "Run `executor install`, open the web UI, add a first integration, search and call a tool, and resume a paused execution." --- `executor install` registers a loopback HTTP runtime as an OS-supervised background service (launchd on macOS, systemd user unit on Linux, Task Scheduler on Windows). The supervised daemon binds `127.0.0.1` on port `4789` by default, persists state under `~/.executor`, and publishes a `server.json` manifest that CLI commands and `executor web` read for the live origin and bearer token. Requires Node.js 20 or newer and the published `executor` npm package. `executor install` needs the compiled binary; in a dev checkout, run `executor daemon run --foreground` instead. ## What you will set up | Step | Command or surface | Outcome | | --- | --- | --- | | Install | `executor install` | Durable local daemon with web UI and HTTP API | | Browse | `executor web` | Signed-in browser session at `{origin}/?_token=…` | | Integrate | Web **Connect** dialog or `executor call … addSource` | First OpenAPI, GraphQL, or MCP integration indexed | | Invoke | `executor tools search`, `executor call` | Tool discovery and execution via QuickJS sandbox | | Resume | Web `/resume/{id}` or `executor resume` | Continue a paused auth or approval execution | ## Install the background service ```bash npm install -g executor executor install ``` ```bash pnpm add -g executor executor install ``` ```bash bun add -g executor executor install ``` ```bash executor install ``` Optional: pick a different loopback port. ```bash executor install --port 4790 ``` Port the supervised daemon binds on loopback. Clients discover the live port from `~/.executor/server-control/server.json` when it differs. Expected output includes the service manager name, web UI origin, data directory, and log path: ```text Installing Executor as a background service... Service manager: launchd Web UI: http://127.0.0.1:4789 Data directory: /Users/you/.executor Logs: /Users/you/.executor/logs ... Executor is now running as a background service at http://127.0.0.1:4789. Open it in your browser, already signed in, with: executor web ``` ```bash executor service status ``` A healthy install reports `Registered: yes`, `Running: yes`, and a `Serving:` line with the manifest origin. The unauthenticated liveness probe is `GET /api/health` returning `ok`. If the default port is taken during auto-started daemon boot (for example when `executor call` spawns a foreground daemon), the CLI selects the next available port and prints a notice. Always read the origin from `server.json` or `executor service status` when ports may differ. ## Open the web UI ```bash executor web ``` By default, `executor web` does not start a new server. It reads the active local `server.json` manifest and opens `{origin}/?_token={bearer}` in your default browser so you arrive already authenticated. | Command | Behavior | | --- | --- | | `executor web` | Open the installed background service | | `executor open` | Same as `executor web` | | `executor web --foreground` | Start a temporary server in the current terminal (default port `4788`) | If nothing is running, `executor web` prints install instructions. For a one-off session without OS registration, use `executor web --foreground`. From the web UI you can browse **Integrations**, inspect **Tools**, configure policies, and use the **Connect** card to wire MCP clients. ## Add a first integration Executor registers tenant-scoped integrations (OpenAPI specs, GraphQL endpoints, MCP servers) and indexes their tools per connection. Add one from the web UI or CLI. 1. Open the **Integrations** page. 2. Click **Connect** (or use the command palette: **Add integration**). 3. In the **Connect an integration** dialog, paste a spec or endpoint URL, or pick a preset. 4. Executor auto-detects the type (OpenAPI, GraphQL, MCP, Google Discovery) and routes you to the plugin add form with the URL prefilled. 5. Submit the form. On success you land on the integration detail page with indexed tools. Supported detection kinds map to plugins: `openapi`, `graphql`, `mcp`, and `googleDiscovery`. Register the Swagger Petstore OpenAPI spec: ```bash executor call executor openapi addSource '{ "spec": "https://petstore3.swagger.io/api/v3/openapi.json", "namespace": "petstore", "baseUrl": "https://petstore3.swagger.io/api/v3" }' ``` Use `baseUrl` when the OpenAPI document declares relative `servers` entries (for example `"/api/v3"`). Confirm the integration is live: ```bash executor tools sources ``` Expected output lists configured sources with tool counts for each integration slug. Integrations are catalog identities; connections bind owner-scoped credentials to them. The Petstore demo needs no auth template. Integrations that require OAuth or API keys need a connection before tools can run. See [Configure credentials](/configure-credentials). ## Search and call a tool CLI tool commands compile TypeScript snippets and run them through `POST /executions`. `executor call`, `executor resume`, and `executor tools …` auto-start a localhost daemon when no supervised service is reachable and no explicit remote credential is configured. ### Search by intent ```bash executor tools search "list pets" ``` Optional filters: Restrict search to one integration slug (for example `petstore`). Maximum matches returned. ### Browse namespaces ```bash executor call petstore --help executor tools describe petstore.org.main.pets.listPets ``` `executor call --help` walks the tool tree. Add `--match ""` and `--limit ` to narrow large namespaces. ### Invoke a tool ```bash executor call petstore org main pets listPets '{}' ``` Path segments map to the sandbox `tools` proxy (`tools.petstore.org.main.pets.listPets`). Pass a JSON object as the final argument. ```bash executor call petstore org main pets listPets '{}' ``` ```json [ { "id": 1, "name": "doggie", "status": "available" } ] ``` ### Tool addresses Persisted tools use connection-aware addresses: ```text tools.... ``` Example: `tools.petstore.org.main.pets.listPets`. The HTTP catalog exposes these via `GET /tools` and `GET /tools/schema?address=…`. ## Resume a paused execution Tool calls that need user auth, form input, or policy approval suspend inside the QuickJS sandbox. The executions API returns `status: "paused"` with an `executionId` and interaction metadata. Resume through the web UI or CLI. ```mermaid stateDiagram-v2 [*] --> Running: POST /executions Running --> Paused: tool elicitation or approval Paused --> Running: POST /executions/:id/resume Running --> Completed: sandbox finishes Paused --> Completed: decline or cancel Completed --> [*] ``` ### When a call pauses A paused CLI invocation prints the pause reason, a browser approval URL, and CLI fallback commands: ```text Approval required for tools.petstore.org.main.pets.addPet. Approve in browser: http://127.0.0.1:4789/resume/exec_abc123 CLI fallback: executor resume --execution-id exec_abc123 --action accept executor resume --execution-id exec_abc123 --action decline executor resume --execution-id exec_abc123 --action cancel ``` Form elicitation also prints a `--content` JSON template when the interaction carries a `requestedSchema`. ### Resume in the browser Open `/resume/{executionId}` on your Executor origin. The approval page loads the paused execution via `GET /executions/:executionId` and submits `POST /executions/:executionId/resume` when you approve, decline, or cancel. ### Resume from the CLI ```bash executor resume --execution-id exec_abc123 --action accept ``` Execution ID from the paused response. Interaction response sent to the executions resume endpoint. JSON object for `action=accept` when the pause requested structured input. :::endpoint POST /executions/:executionId/resume Resume a paused sandbox execution. **Payload** | Field | Type | Description | | --- | --- | --- | | `action` | `"accept"` \| `"decline"` \| `"cancel"` | User decision | | `content` | object (optional) | Structured input when accepting a form elicitation | **Response**: Same union as execute: `completed` with `text`, `structured`, `isError`, or another `paused` result if a subsequent approval is required. ::: After resume completes, the CLI prints the final tool output and exits `0`. If another approval gate appears, it prints the next `/resume/{id}` URL. ## Quick reference | Task | Command | | --- | --- | | Install service | `executor install` | | Open UI | `executor web` | | List integrations | `executor tools sources` | | Search tools | `executor tools search ""` | | Call tool | `executor call ''` | | Resume pause | `executor resume --execution-id ` | | Service health | `executor service status` | | Foreground dev server | `executor web --foreground` | Run `executor install`, then `executor web` again. For a throwaway session, use `executor web --foreground`. `executor install` requires the compiled binary. From source, run `executor daemon run --foreground` and open the printed origin manually. Paused executions are session-scoped. The pause may have already been resolved, or the daemon restarted. Re-run the original tool call to generate a fresh execution ID. Set `EXECUTOR_DATA_DIR` before install to relocate `~/.executor`. Remote targets accept `EXECUTOR_API_KEY` or `EXECUTOR_AUTH_TOKEN`. See [Configuration reference](/configuration-reference). ## Next Global install paths, dev bootstrap, ports, and data directory layout. OpenAPI, GraphQL, and MCP registration from the UI and CLI with post-add verification. Tool addresses, discovery, schema inspection, and invocation across surfaces. Code-mode execution, pause reasons, HTTP routes, and MCP elicitation handling. Full `executor` subcommands, flags, and auto-start behavior. Port conflicts, unreachable servers, OAuth behind proxies, and recovery commands. --- ## 04. MCP proxy > How Executor acts as a single MCP endpoint in front of OpenAPI, GraphQL, and upstream MCP integrations with shared auth and per-tool policies. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/04-mcp-proxy.md - Generated: 2026-06-23T19:21:30.023Z ### Source Files - `apps/docs/mcp-proxy.mdx` - `packages/hosts/mcp/src/tool-server.ts` - `packages/hosts/mcp/src/index.ts` - `apps/cli/src/main.ts` - `packages/core/api/src/server/mcp-build.ts` - `apps/docs/concepts/integrations.mdx` --- title: "MCP proxy" description: "How Executor acts as a single MCP endpoint in front of OpenAPI, GraphQL, and upstream MCP integrations with shared auth and per-tool policies." --- Executor exposes one MCP endpoint (`execute` and `resume`) that fronts every configured integration. Agents connect once; upstream OpenAPI APIs, GraphQL endpoints, and MCP servers are reached through the execution engine inside a QuickJS sandbox, with connection credentials and per-tool policies applied on each call. ## Architecture ```mermaid flowchart TB subgraph clients["MCP clients"] A[Cursor / Claude Code / OpenCode / SDK] end subgraph executor["Executor MCP host"] E["/mcp or executor mcp"] TS["createExecutorMcpServer"] ENG["ExecutionEngine"] POL["Policy resolution"] CONN["Connections + credentials"] end subgraph upstream["Integrations"] M[MCP servers] O[OpenAPI APIs] G[GraphQL endpoints] end A -->|MCP stdio or streamable HTTP| E E --> TS TS -->|execute / resume| ENG ENG --> POL ENG --> CONN ENG -->|HTTP or MCP wire| M ENG -->|HTTP| O ENG -->|HTTP| G ``` The MCP surface does not mirror every upstream tool as a separate MCP tool. Clients call `execute` with TypeScript that invokes tools through the `tools.*` namespace (for example `tools.github.org.main.getRepo(...)`). The `execute` tool description is built dynamically from saved [connections](/connections) and [integrations](/integrations). | Layer | Package / path | Role | | --- | --- | --- | | Serving envelope | `@executor-js/host-mcp` (`McpServingRoutes`) | Auth, CORS, session dispatch on `/mcp` | | Tool factory | `@executor-js/host-mcp/tool-server` (`createExecutorMcpServer`) | Registers `execute` and `resume`, elicitation bridge | | Session store | `McpSessionStore` seam | Per-session transport, ownership, browser approval | | Local runtime | `apps/local/src/mcp.ts` | In-process streamable HTTP + stdio | | Multi-user hosts | `packages/core/api/src/server/mcp-build.ts` | Per-principal engine via `makeMcpBuildServer` | ## MCP tools exposed to clients Executor registers two MCP tools (three when elicitation mode is `native`): | Tool | Input | Behavior | | --- | --- | --- | | `execute` | `code` (non-empty string) | Runs TypeScript in QuickJS with `tools.*` access to all connections | | `resume` | `executionId`, `action`, `content?` | Resumes a paused execution (`model` mode only) | | `resume` | `executionId` | Waits for browser approval (`browser` mode only) | In `native` mode, elicitation is handled through MCP SDK `elicitInput` during `execute`; the separate `resume` tool is not registered. The dynamic `execute` description lists connection prefixes, search/describe workflow, and sandbox rules. It is assembled from `executor.connections.list()` and `executor.integrations.list()` at session creation time. ## How integrations are proxied An [integration](/integrations) defines the tool catalog (OpenAPI spec, GraphQL endpoint, or upstream MCP server). A [connection](/connections) binds owner-scoped credentials to that integration. Callable addresses follow: ``` tools.... ``` On each sandbox tool call, `makeExecutorToolInvoker` maps `tools.(args)` to `executor.execute(address, args)` with credentials attached from the connection. Upstream MCP servers are registered through the MCP plugin (`packages/plugins/mcp`); their tools join the same catalog and are invoked through `execute`, not as additional MCP tools on Executor's endpoint. Credentials never reach the agent. The sandbox calls Executor's tool layer; Executor resolves the connection and attaches auth to the upstream request. ## Policy enforcement [Policies](/policies) apply per tool address during execution: | Action | Effect at call time | | --- | --- | | `block` | Tool hidden from list; `ToolBlockedError` if invoked | | `require_approval` | Execution pauses for elicitation; user or model must approve | | `approve` | Call proceeds without an approval prompt | | (none) | Falls through to integration default annotations | Blocked tools surface in the sandbox as `{ ok: false, error: { code: "tool_blocked", ... } }`. Approval pauses return structured content with `executionId` and interaction metadata for `resume`. ## Transport and endpoints Executor serves MCP at `/mcp` on the local daemon (default port from install; the web UI Connect card shows the exact URL). Required on `GET` for SSE. Omitted on the initial `POST` that opens a session. Allowed methods: `GET`, `POST`, `DELETE`, `OPTIONS`. Other methods return JSON-RPC `405`. Cloud deployments may scope the path to `//mcp` (legacy `//mcp` also accepted). ```bash curl -X POST http://127.0.0.1:17888/mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' ``` Local `/api` and `/mcp` require a bearer token minted at server start. OAuth discovery routes are provider-specific and served outside the envelope. `executor mcp` starts an MCP server over stdio. It boots a local HTTP server in the background (for the web UI and browser approval URLs), then connects `StdioServerTransport` to `createExecutorMcpServer`. ```bash title="Default (model resume)" executor mcp ``` ```bash title="Browser approval" executor mcp --elicitation-mode browser ``` ```bash title="Scoped workspace" executor mcp --scope /path/to/workspace ``` Stdio mode redirects `stdout` to `stderr` so JSON-RPC on stdout stays clean for MCP clients. ## Elicitation modes Control how paused executions (OAuth, approval gates) are resumed: | Mode | How to set | `resume` behavior | | --- | --- | --- | | `model` (default) | Omit query param or `--elicitation-mode model` | Model calls `resume` with `action` and optional `content` | | `browser` | `?elicitation_mode=browser` or `--elicitation-mode browser` | `execute` returns `approvalUrl`; user approves in browser; model calls `resume` to poll | | `native` | `?elicitation_mode=native` | MCP SDK `elicitInput` during `execute`; no `resume` tool | HTTP mode reads `?elicitation_mode=` from the session-open request. Legacy `?allow_model_resume=true` maps to `model`. Browser approval URLs point at `/resume/?mcp_session_id=`. The console posts the decision to `/api/mcp-sessions//executions//resume`. ## Authentication | Runtime | MCP auth | | --- | --- | | Local daemon | Bearer token on every `/mcp` and `/api` request (except OAuth callbacks and `/api/health`) | | Self-host / Cloud | `McpAuthProvider` seam: OAuth bearer, RFC 9728 `WWW-Authenticate` on `401`, per-request principal resolution | | Stdio (`executor mcp`) | No MCP-level auth; local server uses its own bearer internally | The authenticated `Principal` (`accountId`, `organizationId`, roles) scopes connections, policies, and engine construction in multi-user hosts. ## Connect an MCP client Use `npx add-mcp` to register Executor in Cursor, Claude Code, or OpenCode: ```bash title="HTTP (local)" npx add-mcp http://127.0.0.1:17888/mcp --transport http --name executor ``` ```bash title="HTTP with bearer" npx add-mcp http://127.0.0.1:17888/mcp --transport http --name executor \ --header 'Authorization: Bearer ' ``` ```bash title="Stdio" npx add-mcp "executor mcp" --name executor ``` ```bash title="Browser approval (HTTP)" npx add-mcp 'http://127.0.0.1:17888/mcp?elicitation_mode=browser' --transport http --name executor ``` The web UI Connect card generates these commands with the correct origin, token, and org slug. Restart the MCP client after adding Executor. Adding or removing integrations does not require reconfiguring the MCP client. New tools appear in the `execute` description on the next session. An existing MCP session may need reconnecting to pick up an updated description. ## Proxy an upstream MCP server Register the upstream MCP server URL as an integration from the web UI or CLI. See [Add integrations](/add-integrations). Bind credentials (API key, OAuth, or upstream bearer) to the integration. See [Configure credentials](/configure-credentials). Confirm tools appear under the connection prefix: ```bash executor tools sources ``` From an MCP client, use `execute` with sandbox code that calls `tools....(args)`. Upstream MCP tool annotations are preserved in persisted metadata and flow through invocation unchanged where the plugin supports them. ## Session lifecycle (HTTP) ```mermaid sequenceDiagram participant C as MCP client participant E as /mcp envelope participant S as McpSessionStore participant T as Transport + McpServer C->>E: POST /mcp (no mcp-session-id) E->>E: authenticate E->>S: dispatch (create) S->>T: createExecutorMcpServer + connect T-->>C: Response + mcp-session-id C->>E: POST /mcp (mcp-session-id) E->>S: dispatch (forward) S->>T: handleRequest T-->>C: JSON-RPC result C->>E: DELETE /mcp (mcp-session-id) E->>S: dispatch (close) S->>T: dispose session ``` Cross-bearer reuse of a session id returns `403` (`MCP session does not belong to the current bearer`). Unknown session ids return `404`. ## Debugging and errors Set to `1` or `true` to enable verbose MCP capability and elicitation logging on stderr. Infrastructure defects during `execute` return opaque `Internal tool error []` with cause logged server-side. JSON-RPC errors use a canonical body: `{ "jsonrpc": "2.0", "error": { "code", "message" }, "id": null }`. Common JSON-RPC codes from the envelope: | HTTP | Code | Meaning | | --- | --- | --- | | 401 | -32001 | Unauthorized (missing or invalid bearer) | | 403 | -32001 / -32003 | Forbidden or session ownership mismatch | | 404 | -32001 | Session not found | | 405 | -32001 | Method not allowed on `/mcp` | | 500 | -32603 | Internal server error | Paused executions expire after a few minutes or when the session runtime restarts. `resume` with a stale `executionId` returns `execution_not_found` with recovery guidance to re-run `execute`. ## Runtime differences | Runtime | MCP entry | Session backend | | --- | --- | --- | | Local daemon | `http://127.0.0.1:/mcp` | In-process (`createMcpRequestHandler`) | | `executor mcp` | stdio | Shared engine across stdio session | | Self-host | `/mcp` via `McpServingRoutes` | In-process `McpSessionStore` | | Executor Cloud | `//mcp` | Durable Object per session | All variants build the per-session `McpServer` through `createExecutorMcpServer` and the execution stack (`makeMcpBuildServer` in multi-user hosts). ## Related pages Wire Cursor, Claude Code, and OpenCode via stdio or streamable HTTP, including `add-mcp` setup. Tool addresses, discovery, schema inspection, and how tools are produced per connection. Code-mode execution, paused states, and MCP elicitation handling. Per-tool allow, require-approval, and block actions with effective policy resolution. Shared MCP endpoint usage on Executor Cloud and how it differs from local. --- ## 05. Tools > Tool addresses, discovery, schema inspection, invocation paths, and how tools are produced per connection across CLI, HTTP API, and MCP surfaces. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/05-tools.md - Generated: 2026-06-23T19:23:05.061Z ### Source Files - `packages/core/api/src/tools/api.ts` - `packages/core/api/src/handlers/tools.ts` - `packages/core/sdk/src/executor.ts` - `packages/core/sdk/src/ids.ts` - `apps/cli/src/main.ts` - `packages/hosts/mcp/src/tool-server.ts` --- title: "Tools" description: "Tool addresses, discovery, schema inspection, invocation paths, and how tools are produced per connection across CLI, HTTP API, and MCP surfaces." --- Executor exposes a per-connection tool catalog: each saved [connection](/connections) produces a persisted set of callable tools, keyed by a dotted address. Discovery surfaces (`tools.list`, sandbox `tools.search`, CLI `tools`) return metadata; `tools.schema` returns full JSON Schema and TypeScript previews; invocation routes through `executor.execute` (SDK) or code-mode `POST /executions` (HTTP, CLI, MCP). ## Tool addresses Every dynamic tool has a branded `ToolAddress` with five logical segments: ``` tools.... ``` | Segment | Type | Meaning | | --- | --- | --- | | `tools` | prefix | Fixed namespace root for connection-scoped API tools | | `` | `IntegrationSlug` | Catalog slug (e.g. `github`, `vercel`) | | `` | `Owner` | `org` (tenant-shared) or `user` (acting member) | | `` | `ConnectionName` | Connection name under that integration and owner | | `` | `ToolName` | Tool name; may itself contain dots | The `` segment is everything after the fourth dot. OpenAPI operations with dotted paths (e.g. `aliases.deleteAlias`) address naturally as `tools.github.org.main.aliases.deleteAlias`. Connection handles omit the final segment: ``` tools... ``` Static tools contributed by plugins use a fully qualified id (`fqid`) instead of the five-segment form. Core configuration tools mount under `executor`, for example `executor.coreTools.connections.list`. Sandbox code strips the leading `tools.` prefix. A call like `tools.github.org.main.getRepo(args)` maps back to the full address `tools.github.org.main.getRepo` at invoke time. ## How tools are produced Tools are **persisted per connection**, not resolved live on every list. Production follows this lifecycle: ```mermaid flowchart TD subgraph triggers [Production triggers] A[connections.create] B[connections.refresh] C[oauth.complete] D[Stale catalog sync on tools.list] end subgraph plugin [Plugin layer] E[resolveTools] end subgraph storage [Storage] F[(tool rows)] G[(definition rows)] end A --> E B --> E C --> E D --> E E --> F E --> G ``` When a plugin implements `resolveTools`, the executor: 1. Calls the plugin with the integration config, connection ref, and credential resolvers. 2. Receives `ToolDef` entries (name, description, schemas, annotations) plus shared `$defs`. 3. Deletes prior rows for that connection, writes new `tool` and `definition` rows, and stamps `tools_synced_at`. OpenAPI plugins derive tools from the integration spec. MCP plugins dial the connection's upstream server. Connections without bound credentials (non-OAuth, non-`none` template, empty `item_ids`) produce zero tools. Plugins without `resolveTools` clear any existing rows and return an empty catalog. Static tools register at executor startup via each plugin's `staticSources` and live in an in-memory map keyed by `fqid`. They have no backing connection row but carry owner/connection metadata for UI grouping. ## Discovery surfaces Executor separates lightweight catalog reads from schema-heavy inspection. | Surface | Path | Returns | Schema bytes | | --- | --- | --- | --- | | `tools.list` | SDK / `GET /tools` | Metadata per tool | Omitted (projected columns) | | `tools.schema` | SDK / `GET /tools/schema` | Full `ToolSchemaView` | Included | | `tools.search` | Sandbox builtin | Ranked, paginated paths | Via `describe.tool` | | `tools.describe.tool` | Sandbox builtin | Compact TypeScript shapes | Preview strings | | `tools.executor.sources.list` | Sandbox builtin | Integrations with `toolCount` | No | ### `tools.list` filters Filter to one integration slug. Filter to `org` or `user`. Omit to merge both owner partitions. Filter to one connection name. Case-insensitive substring match against `name` or `description`. Pass `"true"` to resolve plugin-derived annotations. HTTP query param; handler coerces from string. Pass `"false"` to omit blocked tools. Defaults to including blocked tools on the HTTP surface; SDK defaults to `false`. Full callable address. `org` or `user`. Integration slug. Connection name. Final tool name segment. Owning plugin id. Human-readable description. Plugin annotation: tool may trigger elicitation during invoke. Plugin-derived default approval annotation. Surfaces as the default policy when no user `tool_policy` rule matches. Custom approval prompt text from the plugin. True for plugin-contributed static tools (e.g. core configuration tools). On each list read, the executor also runs a best-effort stale-catalog sync: connections whose `tools_synced_at` predates the integration's `config_revised_at` are re-produced. ### `tools.schema` Returns a `ToolSchemaView` for one address: JSON Schema root for tool input. JSON Schema root for tool output. Shared `$defs` referenced by the tool's schemas. Compact TypeScript type string for input. Compact TypeScript type string for output. Named TypeScript definitions referenced by the preview strings. Returns `null` (HTTP 404 `ToolNotFoundError`) when the address does not resolve. ## HTTP API :::endpoint GET /tools List persisted tool metadata. Mirrors `executor.tools.list`. Query params carry the branded address as plain strings because dotted addresses are not path segments. ::: :::endpoint GET /tools/schema Return the full schema view for one tool. Requires `address` query param (`ToolAddress`). ::: Tool invocation has no direct HTTP route. Callers post JavaScript/TypeScript to the executions group: :::endpoint POST /executions Execute code in the QuickJS sandbox. Payload: `{ "code": "..." }`. Returns `completed` or `paused` status with text and structured fields. ::: :::endpoint POST /executions/:executionId/resume Resume a paused execution. Payload: `{ "action": "accept" | "decline" | "cancel", "content?: unknown }`. ::: :::endpoint GET /executions/:executionId Fetch paused execution info for browser approval flows. ::: ```bash title="List GitHub org tools" curl "$EXECUTOR_ORIGIN/tools?integration=github&owner=org" ``` ```bash title="Inspect schema" curl "$EXECUTOR_ORIGIN/tools/schema?address=tools.github.org.main.getRepo" ``` ## Invocation paths All surfaces converge on `executor.execute(address, args)` inside the SDK. External clients reach it through code-mode execution. ```mermaid sequenceDiagram participant Client as CLI / HTTP / MCP participant Exec as Execution engine participant SDK as executor.execute participant Plugin as plugin.invokeTool participant Upstream as Upstream API Client->>Exec: POST /executions { code } Exec->>Exec: QuickJS sandbox Exec->>SDK: tools.(args) SDK->>SDK: Policy + approval gate SDK->>Plugin: invokeTool(toolRow, credential, args) Plugin->>Upstream: Authenticated request Upstream-->>Plugin: Response Plugin-->>SDK: ToolResult SDK-->>Exec: Result envelope Exec-->>Client: completed / paused ``` ### SDK ```typescript title="Direct invoke" const result = await executor.execute( ToolAddress.make("tools.github.org.main.getRepo"), { owner: "octocat", repo: "hello-world" }, ); ``` ```typescript title="List and inspect" const tools = await executor.tools.list({ integration: "github", owner: "org" }); const schema = await executor.tools.schema(tools[0].address); ``` The `Executor` surface exposes `tools.list` and `tools.schema` as read methods. Invoke uses top-level `execute`. ### CLI | Command | Behavior | | --- | --- | | `executor call [args]` | Builds sandbox code calling `tools.(args)`, posts to `/executions` | | `executor call --help ` | Browse namespace children and print schema help | | `executor tools search ` | Runs `tools.search({ query, limit })` in the sandbox | | `executor tools describe ` | Runs `tools.describe.tool({ path })` | | `executor tools sources` | Runs `tools.executor.sources.list({})` with optional query filter | | `executor resume --execution-id ` | Posts to `/executions/:id/resume` | ```bash title="Invoke a tool" executor call github.org.main.getRepo '{"owner":"octocat","repo":"hello-world"}' ``` ```bash title="Search the catalog" executor tools search "github issues" --namespace github --limit 12 ``` ```bash title="Describe schema" executor tools describe github.org.main.getRepo ``` ### MCP The MCP host (`executor mcp`) registers two protocol tools: | MCP tool | Purpose | | --- | --- | | `execute` | Run sandbox code with access to the `tools` proxy | | `resume` | Resume paused executions (model-managed or browser-approval mode) | Upstream integration tools are **not** registered as individual MCP tools. Agents discover and call them through code inside `execute`, using the lazy `tools` proxy (`tools.search`, `tools.describe.tool`, then `tools.(args)`). The `execute` tool description is built dynamically from the connection inventory. MCP elicitation modes (`model`, `browser`, `native`) control how approval pauses surface to the client. See [Executions](/executions) and [MCP proxy](/mcp-proxy) for the full pause/resume flow. ### Sandbox builtins Built-in discovery tools live outside the per-connection catalog: | Path | Input | Output | | --- | --- | --- | | `search` | `{ query, namespace?, limit?, offset? }` | `{ items, total, hasMore, nextOffset }` | | `describe.tool` | `{ path }` | TypeScript shapes, or `error: { code: "tool_not_found", suggestions }` | | `executor.sources.list` | `{ query?, limit?, offset? }` | Integrations with `toolCount` | | `executor.coreTools.*` | Varies | Configuration operations (connections, integrations, policies, OAuth) | The `tools` object is a lazy proxy. `Object.keys(tools)` does not enumerate the catalog; use `tools.search()` or `tools.executor.coreTools.connections.list({})`. ## Policy effects Before invoke, the executor resolves the effective [policy](/policies) for the tool: 1. Match owner-scoped `tool_policy` rows by pattern (`...`). 2. Fall back to plugin `requiresApproval` annotation as the default. | Policy action | List behavior | Invoke behavior | | --- | --- | --- | | `allow` | Visible (unless `includeBlocked: false` and overridden) | Proceeds | | `require_approval` | Visible | Pauses for approval elicitation | | `block` | Omitted by default (`includeBlocked: false`) | `ToolBlockedError` | Agent-facing surfaces (MCP, default `tools.list`) omit blocked tools silently. ## Invoke result shape Sandbox tool calls return a uniform envelope: ```typescript { ok: true; data: T; http?: { status: number; headers: Record } } | { ok: false; error: { code: string; message: string; status?: number; details?: unknown; retryable?: boolean } } ``` HTTP-backed OpenAPI tools attach transport metadata in `http` beside `data`. File outputs use `ToolFile` values (`{ _tag: "ToolFile", name?, mimeType, encoding: "base64", data, byteLength }`). ## End-to-end workflow Register an [integration](/integrations), then create a [connection](/connections) with credentials. Tool production runs automatically on create. ```bash executor tools sources executor tools search "your intent" --limit 12 ``` Confirm the integration appears with a non-zero `toolCount` and search returns ranked paths. ```bash executor tools describe ... ``` Or `GET /tools/schema?address=tools....`. ```bash executor call ... '{"key":"value"}' ``` If execution pauses for approval or OAuth, use `executor resume --execution-id `. A `ToolNotFoundError` includes up to five suggestions from the same connection. Use the suggested path rather than retrying a guessed address. ## Related pages Owner-scoped credentials that produce per-connection tool catalogs. Tenant-level catalog identities and plugin `resolveTools` sources. Per-tool allow, require-approval, and block rules that gate list and invoke. Code-mode sandbox, pause/resume states, and elicitation handling. Single MCP endpoint exposing the unified catalog through `execute`. Full route groups including `tools` and `executions`. `call`, `tools`, `resume`, and server profile flags. `createExecutor`, `tools.list`, `tools.schema`, and `execute`. --- ## 06. Integrations > Tenant-level catalog identities for OpenAPI specs, GraphQL endpoints, MCP servers, and plugin-registered sources; detection, registration, and auth method descriptors. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/06-integrations.md - Generated: 2026-06-23T19:23:03.790Z ### Source Files - `apps/docs/concepts/integrations.mdx` - `packages/core/api/src/integrations/api.ts` - `packages/core/api/src/handlers/integrations.ts` - `packages/core/sdk/src/integration.ts` - `packages/plugins/openapi/src/sdk/plugin.ts` - `packages/plugins/mcp/src/sdk/plugin.ts` --- title: "Integrations" description: "Tenant-level catalog identities for OpenAPI specs, GraphQL endpoints, MCP servers, and plugin-registered sources; detection, registration, and auth method descriptors." --- An **integration** is a tenant-level catalog row keyed by `slug` that names an API surface (OpenAPI spec, GraphQL endpoint, MCP server, or plugin-registered source). Core stores only catalog identity (`slug`, `name`, `description`, owning `kind`) plus an opaque `config` blob the owning plugin writes and reads. Integrations do not carry credentials; owner-scoped [connections](/connections) bind auth templates to credential providers and materialize per-connection tools. ## Integration vs connection | Concern | Integration | Connection | | --- | --- | --- | | Scope | Tenant catalog (shared) | Owner-scoped (`org` or `user`) | | Identity | `slug` | `(owner, integration, name)` | | Holds secrets | No | Yes (via credential provider) | | Produces tools | Declares the surface; tool timing depends on plugin | Creates or refreshes tool rows for that owner | | Auth selection | Declares `authMethods` (derived from config) | Binds one `template` slug from those methods | The built-in `executor` integration (`kind: "built-in"`, `canRemove: false`) ships in every workspace and exposes core control tools (for example `executor.integrations.list`) without connection setup. ## Catalog model Persisted integrations live in the `integration` table. The HTTP and SDK surfaces project a public `Integration` type with no credentials and no plugin-internal config. Stable catalog identifier within the tenant. Branded string; used as the `` segment in tool addresses. Display name. Falls back to `description` then `slug` on legacy rows. Agent-visible context: what the API is and when to use it. Editable via `PATCH /integrations/:slug` without touching plugin config. Owning plugin id (for example `openapi`, `graphql`, `mcp`, `built-in`). `false` for static or built-in integrations registered at plugin boot. `true` for user-added catalog entries. `true` when the owning plugin supports `connections.refresh` (re-resolve tools for existing connections). Derived projection of the plugin's `authenticationTemplate`. Always present, possibly empty. Not stored as a DB column. Non-secret URL for catalog UI (favicons). Projected by the plugin's `describeIntegrationDisplay` hook. Plugin-owned config (`IntegrationConfig`) is opaque to core: auth templates, spec references, MCP endpoints, static headers, and similar fields. Only the owning plugin decodes it at register, configure, and execute time. ```text Tenant catalog Owner partition +---------------------------+ +---------------------------+ | integration (slug) | | connection | | plugin_id -> kind | 1..n | (owner, integration, | | config (opaque JSON) | <------> | name) | | can_remove, can_refresh | | template -> auth method | +---------------------------+ | provider -> credential | +---------------------------+ | v tool rows (per connection) ``` ## Integration kinds | `kind` | Registration entrypoint | Tool production timing | Typical `config` contents | | --- | --- | --- | --- | | `openapi` | `executor.openapi.addSpec` / `openapi.addSpec` tool | At add (`putOperations`); `updateSpec` rebuilds all connections | `specHash`, `sourceUrl`, `authenticationTemplate`, optional `baseUrl` / headers | | `graphql` | `executor.graphql.addIntegration` / `graphql.addIntegration` tool | At connection create or refresh (introspection deferred) | `endpoint`, `authenticationTemplate`, optional `introspectionJson` | | `mcp` | `executor.mcp.addServer` / `mcp.addServer` tool | At connection create or refresh (live discovery) | `transport` (`remote` or `stdio`), `endpoint` or `command`, `authenticationTemplate` | | `built-in` | Plugin `staticSources` at boot | Static tools under `executor.*` namespace | None (not persisted) | Multi-API providers (for example Google, Microsoft) bundle several APIs into one integration so one credential covers the whole provider. ## Registration Plugins register integrations through `ctx.core.integrations.register` inside their extension methods. Core's `register` **upserts** on slug collision (idempotent boot re-registration), but explicit add flows (`addSpec`, `addServer`, `addIntegration`) **reject** duplicate slugs with `IntegrationAlreadyExistsError`. Pick a stable `slug` (for example `stripe`, `github_mcp`). Set `name` and `description` for humans and agents. MCP and GraphQL default the slug from the endpoint when omitted. Use the plugin extension or its static control tools: ```bash title="OpenAPI (HTTP API)" POST /openapi/specs # body: spec, slug, optional baseUrl, authenticationTemplate ``` ```bash title="MCP (HTTP API)" POST /mcp/servers # body: transport, name, endpoint, optional authenticationTemplate ``` ```bash title="GraphQL (HTTP API)" POST /graphql/integrations # body: endpoint, optional slug, authenticationTemplate ``` List or fetch the integration and confirm `kind`, `authMethods`, and `canRefresh`: ```bash GET /integrations GET /integrations/:slug ``` Registering an integration does not authenticate. Create an owner-scoped connection that picks an `authMethods[].template` and supplies credential values or completes OAuth. See [Configure credentials](/configure-credentials). ### Auth template merge Plugins that carry a slugged `authenticationTemplate` array (OpenAPI, GraphQL, MCP) use `mergeAuthTemplates`: an incoming entry with a matching slug replaces in place; slug-less entries receive a generated `custom_` slug. Configure flows (`openapi.configure`, `mcp.configureAuth`, GraphQL `configureAuth`) support `mode: "merge"` (default) or `mode: "replace"`. ### Integration presets Each plugin may declare `integrationPresets` (popular integrations in the web UI). Presets are catalog metadata only; registering still goes through the plugin add flow. Available presets are exposed via `ctx.core.integrations.presets()` aggregated across loaded plugins. ## URL detection `POST /integrations/detect` (SDK: `executor.integrations.detect(url)`) asks every loaded plugin with a `detect` hook whether the URL belongs to it. Results are returned as an array; the UI ranks by `confidence` (`high` > `medium` > `low`). URL to probe. Trimmed before dispatch. Max length 2048 characters. Plugin id that recognized the URL (`openapi`, `graphql`, `mcp`, ...). Match tier. Multiple plugins may claim the same URL; the UI picks the best rank. Normalized endpoint the plugin will use if the user proceeds. Suggested display name (spec title, hostname, etc.). Suggested catalog slug. | Plugin | High-confidence signal | Low-confidence fallback | | --- | --- | --- | | `openapi` | URL resolves to parseable OpenAPI document | None | | `graphql` | Live introspection succeeds | URL contains `graphql` token | | `mcp` | Unauthenticated tool discovery or wire-shape probe confirms MCP | URL contains `mcp` token | ```bash curl -X POST "$EXECUTOR_BASE/integrations/detect" \ -H "Content-Type: application/json" \ -d '{"url":"https://api.example.com/openapi.json"}' ``` ```json [ { "kind": "openapi", "confidence": "high", "endpoint": "https://api.example.com/openapi.json", "name": "Example API", "slug": "example_api" } ] ``` ## Auth method descriptors `authMethods` is a **derived projection** of each plugin's stored `authenticationTemplate`. Core calls the plugin's `describeAuthMethods(record)` when serving `integrations.list` or `integrations.get`. Malformed config degrades to `[]` rather than failing the catalog read. | `kind` | Meaning | Typical fields | | --- | --- | --- | | `oauth` | OAuth2 authorization code or discovered MCP OAuth | `oauth.authorizationUrl`, `oauth.tokenUrl`, `oauth.scopes`, `oauth.discoveryUrl`, `oauth.supportsDynamicRegistration` | | `apikey` | API key or bearer rendered via placements | `placements[]` with `carrier` (`header` or `query`), `name`, `prefix`, `variable` | | `header` | Custom header auth (alias of apikey projection) | Same as `apikey` | | `none` | No credential required | Empty placements | Stable id within the integration (usually the template slug). Auth-template slug a connection binds against (`AuthTemplateSlug`). Where credential values render on outbound requests. `variable` names the connection input (`token` when omitted). `literal` renders a static value with no credential input. OpenAPI derives methods from declared security schemes when `authenticationTemplate` is omitted at add time. MCP OAuth methods carry `discoveryUrl` (the MCP endpoint) and `supportsDynamicRegistration: true`; authorize/token endpoints are discovered at connect time. ## HTTP API Integrations are served under the v2 catalog group (formerly `sources`). Routes carry no scope segment; tenant binding comes from request auth. | Method | Path | Summary | | --- | --- | --- | | `GET` | `/integrations` | List all integrations (persisted + static sources) | | `GET` | `/integrations/:slug` | Fetch one integration | | `PATCH` | `/integrations/:slug` | Update `name` and/or `description` only | | `DELETE` | `/integrations/:slug` | Remove when `canRemove` is true | | `POST` | `/integrations/detect` | Probe a URL across plugins | :::endpoint GET /integrations/:slug Fetch the public integration projection including derived `authMethods`. **Params:** `slug` (IntegrationSlug) **Success:** `IntegrationResponse` **Errors:** `404` IntegrationNotFoundError ::: :::endpoint PATCH /integrations/:slug Update user-editable catalog metadata. Does not modify plugin `config`. New display name. New agent-visible description. **Success:** Updated `IntegrationResponse` **Errors:** `404` IntegrationNotFoundError ::: :::endpoint DELETE /integrations/:slug Remove an integration and cascade-delete its connections, tools, and definitions. **Success:** `{ "removed": true }` **Errors:** `409` IntegrationRemovalNotAllowedError when `canRemove` is false ::: ## SDK and plugin surfaces ```typescript // Public catalog read const all = await executor.integrations.list(); const one = await executor.integrations.get(IntegrationSlug.make("stripe")); // URL detection const matches = await executor.integrations.detect("https://mcp.example.com/mcp"); // Plugin-side registration (inside extension) yield* ctx.core.integrations.register({ slug: IntegrationSlug.make("my_api"), name: "My API", description: "Internal billing API", config: { /* opaque plugin config */ }, canRemove: true, canRefresh: true, }); ``` Plugin extension methods exposed on `executor`: | Plugin | Key methods | Static control tools | | --- | --- | --- | | OpenAPI | `addSpec`, `updateSpec`, `previewSpec`, `configure` | `executor.openapi.previewSpec`, `executor.openapi.addSpec` | | GraphQL | `addIntegration`, `configure`, `configureAuth` | `executor.graphql.addIntegration`, `executor.graphql.getIntegration` | | MCP | `addServer`, `probeEndpoint`, `configureAuth` | `executor.mcp.probeEndpoint`, `executor.mcp.addServer` | Core also exposes catalog helpers on `ctx.core.integrations` inside plugins: `register`, `update`, `list`, `get`, `remove`, `detect`, `presets`, `configureSchemas`. ## Lifecycle and refresh - **Remove:** Allowed only when `canRemove: true`. Deletes all connections, tool rows, and definitions for that `slug`. Built-in and boot-registered static integrations return `409`. - **Refresh:** When `canRefresh: true`, `connections.refresh` re-runs the plugin's `resolveTools` hook. OpenAPI `updateSpec` additionally refreshes every connection after swapping stored operations. - **Config revision:** Updating integration `config` stamps `config_revised_at`. Connections whose `tools_synced_at` is older lazily rebuild on next read (cross-subject owner policy). Re-adding an existing slug via explicit add flows fails with `integration_already_exists`. To change auth methods or spec content, use the plugin's update/configure paths (`updateSpec`, `configure`, `configureAuth`) instead of registering again. ## Related pages Step-by-step add flows for OpenAPI, GraphQL, and MCP from the web UI or CLI. Owner-scoped credentials bound to integration auth templates. Credential providers, OAuth minting, and placement-based auth templates. How integrations and connections produce discoverable, invocable tools. Full route payloads and error shapes for the integrations group. --- ## 07. Connections > Owner-scoped credentials bound to integrations, credential provider resolution, OAuth minting, and the `(owner, integration, name)` identity model. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/07-connections.md - Generated: 2026-06-23T19:23:05.428Z ### Source Files - `apps/docs/concepts/connections.mdx` - `packages/core/api/src/connections/api.ts` - `packages/core/api/src/handlers/connections.ts` - `packages/core/sdk/src/connection.ts` - `packages/core/sdk/src/oauth-service.ts` - `examples/docs-sdk-quickstart/src/main.ts` --- title: "Connections" description: "Owner-scoped credentials bound to integrations, credential provider resolution, OAuth minting, and the `(owner, integration, name)` identity model." --- A connection is the saved credential for one integration: owner-scoped, bound 1:1 to an integration slug, with its secret value stored in a `CredentialProvider` and applied lazily per tool call. Creating a connection (`executor.connections.create` or `POST /connections`) writes the routing row, stores pasted values in the default writable provider (or references an external provider item), and produces that connection's tool catalog. OAuth connections are minted through `executor.oauth.start` / `complete` instead. ## Identity model Every connection is uniquely identified by three fields: | Field | Type | Role | | --- | --- | --- | | `owner` | `"org"` \| `"user"` | Workspace-shared (`org`) or personal (`user`) partition | | `integration` | `IntegrationSlug` | The integration this credential is for | | `name` | `ConnectionName` | Distinct name under that owner + integration | The SDK type is `ConnectionRef`: ```ts interface ConnectionRef { readonly owner: Owner; readonly name: ConnectionName; readonly integration: IntegrationSlug; } ``` Connection names are normalized to JS-callable identifiers on create. Free-form input like `my-api-key` becomes `myApiKey` via `connectionIdentifier`. `owner: "user"` writes require a signed-in subject. Creating a personal connection without a user subject returns `InvalidConnectionInputError`. ### Address format Each connection exposes a callable address: ``` tools... ``` Append `.` for a full tool address: ``` tools.... ``` Example: `tools.inventory.org.default.listItems`. ## Connection record The `Connection` shape returned by list, get, create, and OAuth mint: Workspace (`org`) or personal (`user`) owner. Normalized connection name. Integration slug this credential is bound to. Which auth method on the integration this credential applies through (for example `apiKey`, `bearer`, or `none`). Credential backend key (`memory`, `default`, `1password`, `keychain`, etc.). Routing only; never the secret itself. Callable handle: `tools...`. Optional human label (which account). Not load-bearing. User-curated, agent-visible context (for example "staging CRM, reads only"). Surfaces in tool inventory and `connections.list`. Epoch ms when an OAuth access token expires. Null for static credentials. OAuth app slug that minted this connection. Null for static credentials. Owner of the OAuth app (may differ from the connection owner when a personal connection uses a workspace app). Space-delimited scopes the provider granted at connect/refresh. Compared against the integration's declared scopes to decide whether reconnect is needed. ## Born wired A connection is created already bound to one integration. There is no separate "connect" step and no unwired state. On create: 1. Validate the integration exists and credential inputs are well-formed. 2. Resolve value origins to one provider and an `item_ids` map (`variable → provider item id`). 3. Upsert the `connection` row (re-create with the same `(owner, integration, name)` updates credentials in place). 4. Call the integration plugin's `resolveTools` and persist the connection's tool rows. Credentials are applied to the integration's auth template lazily at invoke time, never pre-baked into headers or URLs ahead of time. ## Owner scopes | Owner | Visibility | Typical use | | --- | --- | --- | | `org` | Tenant-shared; `subject` is empty | Team API keys, shared OAuth accounts | | `user` | Scoped to the acting member's subject | Personal tokens, BYO credentials | One integration can have many connections under the same owner (for example `default` and `staging` on `inventory`). The same connection name can exist on different integrations because `integration` is part of the identity key. ## Credential origins Static connections accept exactly one origin form. The HTTP API enforces this with `"Expected exactly one credential origin"`. Sugar for a single `token` input. Written to the default writable provider. Multi-input map (one entry per named variable). All values go to the default writable provider. External provider reference. The value is resolved on demand via `provider.get(id)` and is never copied into core storage. Canonical per-variable origin map. Each entry is `{ value }` or `{ from: { provider, id } }`. SDK-only; mixes pasted and external in one map. ### Provider resolution rules | Rule | Behavior | | --- | --- | | Single provider per connection | All inputs of one connection share one `provider` key on the row | | Pasted inputs | Stored in the first registered writable provider (`defaultWritableProvider`) | | External inputs | Routed to the named provider; `item_ids` holds opaque provider item ids | | Mixed origins | Rejected: cannot mix pasted `value`/`values` with external `from` | | Multiple external providers | Rejected: all external inputs must use the same provider | | Missing writable provider | `CredentialProviderNotRegisteredError` (HTTP 409) | Pasted values are stored under ids like `connection:{owner}:{integration}:{name}:{variable}`. OAuth access tokens use `oauth:{owner}:{integration}:{name}` with refresh tokens at `{id}:refresh`. At invoke time, `resolveConnectionValues` loads each `item_ids` entry through the registered provider. OAuth connections refresh the access token first when `expiresAt` is within the skew window, then return `{ token: }`. External `from` references that resolve to `null` are allowed at create time. The failure surfaces at invoke time as `connection_value_missing`, not during create. ## No-auth connections Integrations with no credential requirement use `template: "none"` (`NO_AUTH_TEMPLATE`). These connections legitimately bind zero inputs; the persisted `item_ids` map is empty. ```ts await executor.connections.create({ owner: "org", name: "public", integration: "context7", template: "none", // No value, from, values, or inputs required }); ``` Credentialed templates reject empty `values: {}` or `inputs: {}` at create with `InvalidConnectionInputError` (HTTP 400). An empty-string `value` is allowed when a binding must exist but carries no secret. ## Create a static connection Add the integration first via `openapi.addSpec`, `graphql.addIntegration`, `mcp.addServer`, or a plugin extension. The integration declares auth templates (where credentials render on requests). Pass writable providers to `createExecutor({ providers: [...] })`. The first writable provider in registration order receives pasted values. Call `executor.connections.create` with `owner`, `name`, `integration`, `template`, and one credential origin. List tools filtered by integration. Each tool address includes the connection segment. ```ts SDK (inline value) await executor.connections.create({ owner: "org", name: "default", integration: "inventory", template: "apiKey", value: "inventory-api-key", }); ``` ```ts SDK (external reference) await executor.connections.create({ owner: "org", name: "prod", integration: "inventory", template: "apiKey", from: { provider: "1password", id: "op://vault/item/field", }, }); ``` ```http HTTP API POST /connections Content-Type: application/json { "owner": "org", "name": "default", "integration": "inventory", "template": "apiKey", "value": "inventory-api-key" } ``` ```json { "owner": "org", "name": "default", "integration": "inventory", "template": "apiKey", "value": "inventory-api-key", "description": "Production inventory API, read-only" } ``` ```json { "owner": "org", "name": "default", "integration": "inventory", "template": "apiKey", "provider": "memory", "address": "tools.inventory.org.default", "identityLabel": null, "description": "Production inventory API, read-only", "expiresAt": null, "oauthClient": null, "oauthClientOwner": null, "oauthScope": null } ``` ## OAuth minting OAuth is a credential mechanism, not an integration type. Do not use `connections.create` for OAuth tokens. Instead: 1. Register an owner-scoped OAuth app (`oauth.createClient` or `oauth.registerDynamicClient`). 2. Start a flow (`oauth.start`) for a target `(owner, integration, name, template)`. 3. Complete the flow (`oauth.complete`) after the user authorizes (or receive an immediate `connected` result for `client_credentials`). ```mermaid sequenceDiagram participant UI as Web UI / Agent participant API as Executor runtime participant AS as Authorization server participant CP as Credential provider UI->>API: oauth.start(client, clientOwner, owner, integration, name, template) alt client_credentials grant API->>AS: Token exchange AS-->>API: access_token API->>CP: set oauth:owner:integration:name API-->>UI: { status: "connected", connection } else authorization_code grant API->>API: Persist oauth_session (PKCE + state) API-->>UI: { status: "redirect", authorizationUrl, state } UI->>AS: User authorizes AS-->>UI: Redirect with code UI->>API: oauth.complete(state, code) API->>AS: Code exchange AS-->>API: access_token (+ refresh_token) API->>CP: set access + refresh item ids API->>API: mintOAuthConnection (row + tools) API-->>UI: Connection end ``` ### OAuth start result | `status` | Meaning | Next step | | --- | --- | --- | | `connected` | Token exchanged inline (`client_credentials`) | Connection is ready; tools are produced | | `redirect` | User must visit `authorizationUrl` | Complete with `state` + `code` after callback | OAuth app slug to run the flow through. Owner of the OAuth app. A workspace connection (`owner: "org"`) must use a workspace app (`clientOwner: "org"`). A personal connection may use a shared workspace app. Owner under which the minted connection is saved. Requested OAuth scopes come from the integration's declared auth template, not from the OAuth client row. Reusing a narrow client on a broad integration still requests the integration's full declared scope set. OAuth-minted connections carry `oauthClient`, `oauthClientOwner`, `expiresAt`, and `oauthScope` on the connection row. Token refresh runs automatically inside `resolveConnectionValues` before each tool invocation when the access token is expired or near expiry. Hosts must configure `redirectUri` on `createExecutor` (derived as `${webBaseUrl}${mountPrefix}/oauth/callback`). Redirect-requiring flows fail loudly when it is missing. ## SDK surface `executor.connections` exposes: | Method | Input | Returns | | --- | --- | --- | | `create` | `CreateConnectionInput` | `Connection` | | `list` | `{ integration?, owner? }` | `Connection[]` | | `get` | `ConnectionRef` | `Connection \| null` | | `update` | `ConnectionRef`, `UpdateConnectionInput` | `Connection` | | `remove` | `ConnectionRef` | `void` | | `refresh` | `ConnectionRef` | `Tool[]` | `UpdateConnectionInput` only accepts `description` and `identityLabel`. Credentials and OAuth lifecycle fields are not editable through update; recreate or refresh instead. Plugins resolve credentials through `ctx.connections.resolveValue(ref)` (primary `token` variable) or `resolveValues(ref)` (full variable map). ## HTTP API | Method | Path | Purpose | | --- | --- | --- | | `GET` | `/connections` | List connections (`?integration=`, `?owner=`) | | `POST` | `/connections` | Create or replace a static connection | | `GET` | `/connections/:owner/:integration/:name` | Get one connection | | `PATCH` | `/connections/:owner/:integration/:name` | Update metadata | | `DELETE` | `/connections/:owner/:integration/:name` | Remove connection and its tools | | `POST` | `/connections/:owner/:integration/:name/refresh` | Re-resolve and persist tools | :::endpoint POST /connections Create or upsert a static (non-OAuth) connection. Payload must include exactly one of `value`, `values`, or `from`. ::: :::endpoint GET /connections/:owner/:integration/:name Fetch a single connection by its `(owner, integration, name)` key. Returns 404 `ConnectionNotFoundError` when absent. ::: :::endpoint POST /connections/:owner/:integration/:name/refresh Re-run the integration plugin's `resolveTools` for this connection and return the updated tool list. ::: OAuth routes live under `/oauth/*` (`/oauth/start`, `/oauth/complete`, `/oauth/clients`, etc.) and mint connections through a separate path. See the HTTP API reference for full OAuth payloads. ## Errors | Error | HTTP | When | | --- | --- | --- | | `IntegrationNotFoundError` | 404 | Integration slug does not exist | | `ConnectionNotFoundError` | 404 | `(owner, integration, name)` not found | | `InvalidConnectionInputError` | 400 | Empty credential on credentialed template, mixed origins, missing user subject, or multiple origin fields | | `CredentialProviderNotRegisteredError` | 409 | Referenced provider is not registered, or no writable provider for pasted values | | `OAuthStartError` | 400 | Missing client, workspace/personal app mismatch, missing `redirectUri` | | `OAuthCompleteError` | 400 | Code exchange failed or session corrupt | | `OAuthSessionNotFoundError` | 404 | Unknown or expired OAuth session state | At invoke time, missing resolved values surface as `connection_value_missing` through the auth tool failure path. ## Security model - Agents and sandboxes never receive raw credential values. Connections store routing (`provider` + `item_ids`); values resolve inside the executor at call time. - OAuth client secrets and access tokens live in the credential provider, not in connection API responses. - Removing a connection deletes its tool and definition rows. External provider items are left intact when the provider is read-only; writable providers may delete stored items on OAuth client removal. ## Related pages Tenant-level catalog identities that connections bind to. Credential providers, OAuth flows, and placement-based auth templates. How connections produce callable tool addresses. End-to-end `connections.create` walkthrough with an in-memory provider. Full `/connections` and `/oauth` route payloads and error shapes. --- ## 08. Policies > Per-tool allow, require-approval, and block actions; pattern matching, effective policy resolution, and default annotations derived from integration specs. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/08-policies.md - Generated: 2026-06-23T19:23:07.664Z ### Source Files - `apps/docs/concepts/policies.mdx` - `packages/core/api/src/policies/api.ts` - `packages/core/api/src/handlers/policies.ts` - `packages/core/sdk/src/policies.ts` - `packages/hosts/mcp/src/browser-approval.ts` - `packages/core/sdk/src/errors.ts` --- title: "Policies" description: "Per-tool allow, require-approval, and block actions; pattern matching, effective policy resolution, and default annotations derived from integration specs." --- Executor gates every tool call through a layered policy model: user-authored rules in the `tool_policy` table, plugin-derived `requiresApproval` annotations on persisted tool rows, and runtime enforcement in `tools.list` and `execute`. Rules are owner-scoped (`org` or `user`), matched by dotted patterns against tool identity, and resolved to the most restrictive action across owners. ## Policy actions Each rule assigns one of three actions to matching tools. | Action | SDK value | Runtime behavior | |--------|-----------|------------------| | Always run | `approve` | Tool invokes without an approval prompt, even when the plugin marks `requiresApproval: true`. | | Require approval | `require_approval` | Execution pauses for human approval before the handler runs. | | Block | `block` | Tool is hidden from `tools.list` by default; direct `execute` returns `ToolBlockedError`. | Restriction rank (highest wins when owners disagree): `block` (3) > `require_approval` (2) > `approve` (1). The web UI labels `approve` as **Always run** and `block` as **Block** in menus, or **Blocked** when showing current state. ## Owner scope and precedence Policies are v2 owner-scoped rows, not legacy scope stacks. Each row carries `owner` (`org` | `user`), a `pattern`, an `action`, and a fractional-index `position` (lower lex order = higher precedence within that owner). Resolution proceeds in two stages: 1. **Per owner:** walk rules sorted by `position` (then `id` for ties). The first pattern that matches the tool wins for that owner. 2. **Across owners:** compare each owner's winning match and keep the most restrictive action. Org rules are the outer guardrail; a user `approve` cannot weaken an org `block`, but a user `require_approval` can strengthen an org `approve`. ```mermaid flowchart TD subgraph inputs [Inputs] P[tool_policy rows] A[tool.annotations.requiresApproval] T[tool id for matching] end subgraph perOwner [Per-owner match] S[Sort by owner rank then position] M[First matching pattern per owner] end subgraph resolve [Effective policy] R[Most restrictive action wins] F{User rule matched?} U[user source + pattern + policyId] D[plugin-default source] end P --> S --> M --> R T --> M R --> F F -->|yes| U F -->|no| D A --> D ``` Who owns the rule. `org` applies tenant-wide; `user` applies to the bound subject only. Creating `owner: "user"` rules requires an executor with a user subject. ## Pattern matching Patterns match against the tool identity string `...`. Static tools (for example `executor.coreTools.*`) match against the full `ToolAddress` instead. | Pattern form | Example | Matches | |--------------|---------|---------| | Universal | `*` | Every tool id | | Exact | `vercel.org.main.deploy` | Only that four-segment id | | Plugin-wide | `vercel.*` | Any tool under `vercel` | | Subtree (trailing `*`) | `vercel.dns.*` | `vercel.dns.create`, `vercel.dns.zones.list`, etc. | | Mid-segment `*` | `github.*.*.repos.list` | Wildcards exactly one segment per `*`; targets a tool name across all connections | Validation (`isValidPattern`) rejects empty patterns, leading/trailing dots, `..`, leading `*` (except bare `*`), and partial wildcards like `me*` or `a.b*`. The web UI authors patterns from display ids like `integration.tool`. It expands them to `integration.*.*.tool` so a rule applies across all connections. Patterns that already end in `*` (`integration.*`, `*`) pass through unchanged. ### Pattern examples ```text vercel.dns.create → exact match only vercel.dns.* → vercel.dns.create, vercel.dns.delete, vercel.dns.zones.list vercel.* → any vercel tool at any depth github.*.*.repos.list → github.org.acme.repos.list, github.user.alice.repos.list * → everything ``` ## Plugin default annotations When no user rule matches, Executor falls back to the tool row's `annotations.requiresApproval`. Plugins stamp these defaults when tools are produced or refreshed. | Plugin | Default `requiresApproval` | `approvalDescription` | |--------|---------------------------|----------------------| | OpenAPI | `true` for `POST`, `PUT`, `PATCH`, `DELETE` operations | `"METHOD /pathTemplate"` | | GraphQL | `true` for mutation bindings | `"mutation fieldName"` | | MCP | `true` when upstream `destructiveHint` is set | upstream tool title or name | The effective policy source is `plugin-default` in this case. `approve` from the plugin default means the tool runs without prompting; `require_approval` triggers elicitation. User rules with source `user` always override plugin defaults when they match, regardless of annotation. ## Enforcement surfaces ### `tools.list` By default, blocked tools are omitted. Pass `includeBlocked=true` on the HTTP query or SDK filter to surface them for admin views. The list response includes `requiresApproval` and `approvalDescription` from plugin annotations. The UI combines stored policies with annotations via `effectivePolicyFromSorted` to show the effective action per tool. ### `execute` On every invocation, Executor resolves the effective policy, then: | Effective action | Behavior | |------------------|----------| | `block` | Returns `ToolBlockedError` with `address` and matched `pattern`. | | `approve` | Skips approval even if `requiresApproval` is set. | | `require_approval` | Fires elicitation before the handler. | | No user rule + `requiresApproval: true` | Fires elicitation using `approvalDescription` when present. | | No user rule + no annotation | Runs immediately. | Declined or cancelled approval returns `ElicitationDeclinedError`. ### MCP approval flow When a gated call pauses, MCP hosts can surface browser approval. With `?elicitation_mode=browser`, the host returns an `approvalUrl` pointing at `/resume/`. The model calls the `resume` tool to wait for the human decision. Modes `model` (default) and `native` keep approval inline with the agent. ## Data model Policies persist in the `tool_policy` table (SQLite locally, Postgres in cloud). Rows are partitioned by tenant and owner policy, same as connections. Stable rule identifier (`pol_…`). Rule owner partition. Dotted match pattern (see grammar above). Enforcement action. Fractional-index sort key. New rules without an explicit position are inserted above the current minimum (highest precedence). ## HTTP API :::endpoint GET /policies List all tool policies visible to the authenticated identity. Returns an array of policy objects with epoch-millisecond `createdAt` and `updatedAt`. ::: :::endpoint POST /policies Create an owner-scoped policy. ```json title="Create policy" { "owner": "org", "pattern": "vercel.dns.*", "action": "require_approval" } ``` Owner partition for the new rule. Valid match pattern. Enforcement action. Optional fractional-index position. Omit to insert at the top of the owner's list. ::: :::endpoint PATCH /policies/:policyId Update pattern, action, or position. Payload must include `owner` to identify the partition. ```json title="Update action" { "owner": "org", "action": "block" } ``` ::: :::endpoint DELETE /policies/:policyId Remove a policy. Payload must include `owner`. ```json title="Remove policy" { "owner": "org" } ``` Returns `{ "removed": true }`. ::: ## SDK surface The `executor.policies` namespace mirrors the HTTP API and adds resolution: ```typescript title="Policy CRUD and resolve" const rules = await executor.policies.list(); const created = await executor.policies.create({ owner: "org", pattern: "github.*.*.repos.delete", action: "block", }); await executor.policies.update({ id: String(created.id), owner: "org", action: "require_approval", }); await executor.policies.remove({ id: String(created.id), owner: "org" }); const effective = await executor.policies.resolve( ToolAddress.make("tools.github.org.main.repos.delete"), ); // { action, source, pattern?, policyId? } ``` Pure helpers exported from `@executor-js/sdk` (and `@executor-js/sdk/shared`) support UI and tests without a live executor: - `matchPattern(pattern, toolId)` - `isValidPattern(pattern)` - `resolveToolPolicy(toolId, policies, ownerRank)` - `resolveEffectivePolicy(toolId, policies, ownerRank, defaultRequiresApproval?)` - `effectivePolicyFromSorted(toolId, sortedPolicies, defaultRequiresApproval?)` ## Resolution examples Given org rule `vercel.*` → `block` and user rule `vercel.dns.create` → `approve`, calling `vercel.dns.create` is blocked. The org guardrail wins. Given org `vercel.*` → `approve` and user `vercel.dns.create` → `require_approval`, that tool pauses for approval. Given `vercel.dns.create` → `approve` at position `a0` and `vercel.dns.*` → `require_approval` at `a1`, `vercel.dns.create` matches the more specific rule first and runs without approval. With no user rules, a tool annotated `requiresApproval: true` (for example an OpenAPI `DELETE`) pauses for approval. A `GET` tool with no annotation runs immediately. A user rule `vercel.*.*.delete` → `approve` suppresses the plugin's `requiresApproval` on the delete tool. ## Errors | Error | When | |-------|------| | `ToolBlockedError` | `execute` on a tool whose effective action is `block`. Message includes the matched pattern. | | `ElicitationDeclinedError` | User declined or cancelled an approval prompt. | | `StorageError` | Invalid pattern or action on create/update; `owner: "user"` without a bound subject; policy not found on update. | MCP tool dispatch maps `ToolBlockedError` to code `tool_blocked` in the sandbox result. ## Related pages Create and update owner-scoped rules from the web UI, CLI, and HTTP API; handle approval pauses end to end. Paused states, `execute` and `resume` routes, and MCP elicitation handling when approval is required. Tool addresses, discovery, and how `includeBlocked` surfaces gated tools. Single MCP endpoint with shared auth and per-tool policies across integrations. Full `policies` route payloads and error shapes. `executor.policies` helpers and typed policy exports. --- ## 09. Executions > Code-mode execution via QuickJS, paused states for auth and approval, `execute` and `resume` HTTP routes, and MCP elicitation handling. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/09-executions.md - Generated: 2026-06-23T19:24:18.920Z ### Source Files - `packages/core/api/src/executions/api.ts` - `packages/core/api/src/handlers/executions.ts` - `packages/core/execution/src/engine.ts` - `packages/kernel/runtime-quickjs/src/index.ts` - `packages/hosts/mcp/src/tool-server.ts` - `apps/cli/src/main.ts` --- title: "Executions" description: "Code-mode execution via QuickJS, paused states for auth and approval, `execute` and `resume` HTTP routes, and MCP elicitation handling." --- Executor runs agent-authored TypeScript in a sandboxed QuickJS runtime, wires a `tools.*` proxy into that sandbox, and routes every tool call through the same executor stack used by direct invocation. When a tool needs user input (OAuth, credentials, policy approval), the execution engine pauses, returns an `executionId`, and resumes on `accept`, `decline`, or `cancel`. The same pause/resume model is exposed over HTTP (`POST /api/executions`), MCP (`execute` / `resume` tools), and the CLI (`executor resume`). ## Architecture ```mermaid flowchart TB subgraph surfaces["Caller surfaces"] MCP["MCP host
execute / resume tools"] HTTP["HTTP API
POST /api/executions"] CLI["CLI
call / resume"] UI["Web UI
tool run panel"] end subgraph engine["@executor-js/execution"] EE["createExecutionEngine"] Pause["executeWithPause / resume"] Inline["execute + onElicitation"] end subgraph runtime["Code substrate"] QJS["runtime-quickjs
makeQuickJsExecutor"] DW["runtime-dynamic-worker
Cloudflare Workers"] end subgraph sandbox["QuickJS sandbox"] Proxy["tools.* proxy"] Emit["emit() / console"] Invoker["SandboxToolInvoker"] end subgraph executor["@executor-js/sdk Executor"] Tools["executor.execute(address, args)"] Policy["policy + elicitation"] end MCP --> EE HTTP --> EE CLI --> HTTP UI --> HTTP EE --> Pause EE --> Inline EE --> QJS EE --> DW QJS --> Proxy Proxy --> Invoker Invoker --> Tools Tools --> Policy ``` | Layer | Package / surface | Role | | --- | --- | --- | | Engine | `@executor-js/execution` | Pause/resume orchestration, result formatting, built-in sandbox tools | | Runtime | `@executor-js/runtime-quickjs` (local, self-host) or `@executor-js/runtime-dynamic-worker` (cloud) | Sandboxed JS execution with timeout and memory limits | | Invoker | `makeExecutorToolInvoker` | Maps `tools.(args)` to `executor.execute` | | Host wiring | `@executor-js/api` `makeExecutionStack` | Binds scoped executor + `CodeExecutorProvider` per request | MCP paused executions are **session-scoped**. The web approval page at `/resume/:executionId` resolves pauses through `/api/mcp-sessions/:mcpSessionId/executions/:executionId`, not the session-less `/api/executions/:id` route. HTTP `POST /api/executions` uses a separate engine instance per request. ## Execution lifecycle ```mermaid stateDiagram-v2 [*] --> Running: execute / executeWithPause Running --> Completed: script finishes Running --> Paused: elicitation or policy gate Paused --> Running: resume accept (+ content) Paused --> Completed: resume decline / cancel Paused --> Completed: sandbox timeout / error Completed --> [*] ``` An execution returns one of two top-level statuses: | Status | Meaning | | --- | --- | | `completed` | Sandbox finished. Includes `text`, `structured`, and `isError` when the script or a tool failed inside the sandbox. | | `paused` | Waiting for user interaction. Includes `executionId`, interaction metadata, and resume instructions in `text` / `structured`. | Paused execution IDs are globally unique (`exec_`). The engine keeps a bounded FIFO cache (64 entries) of settled outcomes so duplicate `resume` calls replay the same result instead of returning "not found". ## QuickJS sandbox Local and self-hosted deployments use `makeQuickJsExecutor()` from `@executor-js/runtime-quickjs`. Cloud uses `makeDynamicWorkerExecutor()` instead; both implement the same `CodeExecutor` interface from `@executor-js/codemode-core`. ### Runtime defaults | Option | Default | Constraint | | --- | --- | --- | | `timeoutMs` | `300_000` (5 minutes) | Minimum `100` | | `memoryLimitBytes` | `64 * 1024 * 1024` | Per-VM allocation cap | | `maxStackSizeBytes` | `1 * 1024 * 1024` | Call-stack depth cap | ### Sandbox API Scripts run inside an async IIFE with these globals: | Global | Behavior | | --- | --- | | `tools` | Lazy proxy. `await tools.github.org.main.getRepo({ owner, repo })` dispatches to the matching executor tool address. | | `tools.search({ query, namespace?, limit?, offset? })` | Built-in tool discovery (default limit `12`). | | `tools.describe.tool({ path })` | Returns compact TypeScript input/output shapes for a tool path. | | `tools.executor.sources.list({ query?, limit?, offset? })` | Lists configured integrations. | | `emit(value)` | Sends user-visible output (MCP content blocks, `ToolFile`, or text). Emitted items are not returned to the model. | | `console.log/warn/error/info/debug` | Captured into execution logs. | | `fetch` | **Disabled** — all network access goes through `tools.*`. | TypeScript type syntax (`: T`, `as T`, generics) is stripped before evaluation. Decorators and `enum` are not supported. ```typescript title="Example: search then call" const { items } = await tools.search({ query: "github issues", limit: 12 }); const path = items[0]?.path; if (!path) return "No matching tools found."; const details = await tools.describe.tool({ path }); const result = await tools[path]({ title: "Bug report" }); return result; ``` ```typescript title="Example: emit file to user" const attachment = await tools.gmail.org.main.getAttachment({ id: "..." }); if (attachment.ok) emit(attachment.data); return undefined; ``` ## Pause reasons Executions pause when the elicitation handler is invoked mid-run. Common triggers: | Trigger | Request type | Typical cause | | --- | --- | --- | | Tool `elicit()` | `FormElicitation` or `UrlElicitation` | Missing credentials, OAuth browser flow, structured user input | | Policy `require_approval` | `FormElicitation` (empty schema) | Owner policy matched the tool path | | Tool annotation `requiresApproval` | `FormElicitation` (empty schema) | Integration spec marked the operation as sensitive | ### Elicitation request shapes Structured input or approval-only gate. - `message` (string): Human-readable prompt. - `requestedSchema` (JSON Schema object): Fields to collect. An empty schema means "approve or decline" with no form fields. Browser redirect flow (OAuth, external approval page). - `message` (string): Human-readable prompt. - `url` (string): URL the user must open. - `elicitationId` (string): Correlation id for the callback. ### Resume response How the user responded to the paused interaction. Required for `accept` on form elicitations with a non-empty `requestedSchema`. Omitted or `{}` for approval-only gates. On `decline` or `cancel`, the engine raises `ElicitationDeclinedError` and the sandbox sees a tool failure message. ## HTTP API All routes are under `/api/executions` and use the pause/resume engine (`executeWithPause`). | Method | Path | Handler | Purpose | | --- | --- | --- | --- | | `POST` | `/api/executions` | `execute` | Run code; return `completed` or `paused` | | `GET` | `/api/executions/:executionId` | `getPaused` | Inspect a paused execution without resuming | | `POST` | `/api/executions/:executionId/resume` | `resume` | Submit `action` + optional `content` | :::endpoint POST /api/executions Run TypeScript in the QuickJS sandbox. Returns immediately on completion or on the first pause point. ::: TypeScript/JavaScript source to execute. Top-level outcome discriminator. Human-readable result or pause instructions (includes `executionId` and resume guidance when paused). Machine-readable envelope. Completed runs use `{ status: "completed" | "error", result?, error?, logs, emitted? }`. Paused runs use `{ status: "waiting_for_interaction", executionId, interaction: { kind, message, instructions, url?, requestedSchema?, address, args } }`. Present on `completed` responses when the sandbox or a tool returned an error. ```bash curl -sS -X POST http://localhost:3001/api/executions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"code":"return await tools.search({ query: \"github\" });"}' ``` ```json { "status": "completed", "text": "{\n \"items\": [...],\n \"total\": 3,\n \"hasMore\": false\n}", "structured": { "status": "completed", "result": { "items": [], "total": 3, "hasMore": false }, "logs": [] }, "isError": false } ``` :::endpoint POST /api/executions/:executionId/resume Resume a paused execution. May return another `paused` status if a second elicitation occurs in the same script. ::: ID from the paused response (`structured.executionId` or `text`). User decision. JSON object matching `requestedSchema` when accepting a form elicitation. Same union as `POST /api/executions`. ```bash curl -sS -X POST "http://localhost:3001/api/executions/exec_abc123/resume" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -d '{"action":"accept","content":{"note":"Approved"}}' ``` :::endpoint GET /api/executions/:executionId Fetch formatted pause details for a known `executionId`. Returns `404 ExecutionNotFoundError` if the id is unknown or already resumed. ::: ## MCP surface The MCP host registers two tools when elicitation is not fully native: | Tool | When registered | Input | | --- | --- | --- | | `execute` | Always | `{ code: string }` | | `resume` | `elicitationMode` is `model` or `browser` | See mode below | ### Elicitation modes The host calls `engine.executeWithPause(code)`. On pause, the model receives structured interaction metadata and must call `resume` with the user's decision. `resume` input: - `executionId` (string) - `action`: `accept` | `decline` | `cancel` - `content` (optional JSON string, default `"{}"`) This is the default for `executor mcp --elicitation-mode model`. Same pause flow, but `execute` returns `status: "user_approval_required"` with an `approvalUrl` instead of full interaction details. The model prompts the user to open the URL; `resume` blocks until the browser records a decision (up to 10 minutes). Local CLI builds approval URLs as `{baseUrl}/resume/{executionId}?mcp_session_id=...`. `executor mcp --elicitation-mode browser` selects this mode. The host calls `engine.execute` with an inline MCP `elicitInput` handler. Paused executions never surface `executionId`; the MCP client handles form/url elicitation directly. The `resume` tool is not registered. Used when the connected MCP client advertises elicitation capabilities and the host opts into native mode. Paused MCP executions live in the MCP session's in-memory engine. They expire after a few minutes or when the session/runtime restarts. A missing execution returns `status: "execution_not_found"` with recovery guidance to re-run `execute`. ## CLI The CLI routes codemode through the HTTP API. `executor call` and `executor tools search` compile to sandbox code and call `POST /api/executions`. On `status: "paused"`, the CLI prints pause text, the browser approval URL (`{origin}/resume/{executionId}`), and ready-made `executor resume` commands. ```bash executor resume --execution-id exec_abc123 --action accept executor resume --execution-id exec_abc123 --action accept --content '{"note":"ok"}' executor resume --execution-id exec_abc123 --action decline ``` Use `--base-url` or `--server` to target a remote Executor instance. Paused state is not persisted across server restarts. ## Result formatting `formatExecuteResult` and `formatPausedExecution` normalize engine output for HTTP and MCP: | Field | Completed | Paused | | --- | --- | --- | | `text` | Truncated at 30,000 chars. Includes result value, logs, or emit acknowledgment. | Pause message, URL or schema, `executionId`, and step-by-step resume instructions. | | `structured.status` | `"completed"` or `"error"` | `"waiting_for_interaction"` | | `isError` | `true` when sandbox `error` is set | Not set (pause is not an error) | Scripts that only `emit()` without `return` produce `(no return value; N items emitted to the user)` in `text` and an `emitted` count in `structured`. ## SDK embedding ```typescript import { createExecutor } from "@executor-js/sdk"; import { createExecutionEngine } from "@executor-js/execution"; import { makeQuickJsExecutor } from "@executor-js/runtime-quickjs"; const executor = await createExecutor({ onElicitation: "accept-all" }); const engine = createExecutionEngine({ executor, codeExecutor: makeQuickJsExecutor({ timeoutMs: 120_000 }), }); // Inline elicitation (MCP-native style) const result = await engine.execute(code, { onElicitation: async (ctx) => { // render ctx.request, collect user input return { action: "accept", content: { field: "value" } }; }, }); // Pause/resume (HTTP / model-MCP style) const started = await engine.executeWithPause(code); if (started.status === "paused") { const resumed = await engine.resume(started.execution.id, { action: "accept", content: { note: "approved" }, }); } ``` `engine.getDescription` returns the canonical workflow prose (search → describe → call) plus up to 50 connection prefixes for LLM tool selection. ## Failure modes | Symptom | Likely cause | Recovery | | --- | --- | --- | | `ExecutionNotFoundError` (404) | Pause expired, already resumed, or wrong API scope (MCP session vs HTTP) | Re-run `execute`; for MCP pauses, include `mcp_session_id` on `/resume` | | `No paused execution: exec_...` (MCP) | Session restarted or timeout | Re-run `execute` with the original code | | `fetch is disabled in QuickJS executor` | Script called `fetch` directly | Route through `tools.*` | | QuickJS timeout after N ms | Script or pending tool calls exceeded `timeoutMs` | Increase `timeoutMs` or shorten the workflow | | `Tool requires approval but ... declined` | User chose `decline` or `cancel` on a policy or elicitation gate | Adjust policy or re-run with approval | | Hang until client timeout | Rare race on fast sandbox failure (fixed via `Effect.raceFirst`) | Upgrade to current engine; verify runtime returns failures promptly | Set `EXECUTOR_MCP_DEBUG=1` to log MCP elicitation capability snapshots and pause/resume transitions. ## Related pages Tool addresses, discovery, and how the sandbox `tools` proxy maps paths to executor tools. Per-tool `require_approval` rules that trigger approval pauses during execution. Handle approval pauses from the web UI, MCP, and CLI resume flow. How Executor exposes `execute` and `resume` as MCP tools in front of integrations. Full route inventory including `executions`, payloads, and error shapes. `executor call`, `executor resume`, and `executor mcp --elicitation-mode` flags. End-to-end path from install through a paused execution and resume. --- ## 10. Add integrations > Add OpenAPI, GraphQL, and MCP sources from the web UI or CLI, including spec URLs, namespaces, base URLs, and post-add verification with `tools sources`. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/10-add-integrations.md - Generated: 2026-06-23T19:24:45.539Z ### Source Files - `README.md` - `apps/docs/local/cli.mdx` - `packages/plugins/openapi/src/sdk/plugin.ts` - `packages/plugins/graphql/src/sdk/plugin.ts` - `packages/plugins/mcp/src/sdk/plugin.ts` - `packages/core/api/src/integrations/api.ts` - `apps/cli/src/integrations.ts` --- title: "Add integrations" description: "Add OpenAPI, GraphQL, and MCP sources from the web UI or CLI, including spec URLs, namespaces, base URLs, and post-add verification with `tools sources`." --- Registering an integration adds a tenant-level catalog entry (slug, description, auth method descriptors). It does not attach credentials. OpenAPI operations are extracted at add time; GraphQL and MCP defer per-connection tool materialization until a connection exists. Add from the web UI **Connect** flow, plugin control tools (`executor.openapi.addSpec`, `executor.graphql.addIntegration`, `executor.mcp.addServer`), or the HTTP API groups under `/openapi`, `/graphql`, and `/mcp`. ```text Web UI / CLI / HTTP API │ ▼ Plugin add handler (addSpec / addIntegration / addServer) │ ▼ Tenant integration catalog ──► connections (separate step) │ ▼ Tool catalog (OpenAPI: at add; GraphQL/MCP: after connection) ``` The catalog slug is the stable integration identity (`slug` in API payloads). The web UI labels this field **Namespace** in identity editors; it maps to the same value as `slug`. ## Prerequisites - A running Executor runtime: `executor install` (durable daemon) or `executor web --foreground` (throwaway foreground runtime). - Protocol plugins loaded on the runtime (OpenAPI, GraphQL, MCP ship with the default local app). ## Web UI Run `executor web` and open **Integrations**, or navigate to the integrations route in your deployment. Click **Connect** (or **Connect an integration** when the list is empty). The dialog accepts a preset search, a URL for auto-detection, or a manual plugin type. Paste a URL and click **Detect**. Executor calls `POST /integrations/detect` with `{ "url": "" }` and each loaded plugin returns zero or one `IntegrationDetectionResult` candidates (`kind`, `confidence`, `endpoint`, `name`, `slug`). The UI picks the highest-confidence match and routes to the matching add form with `url` and `namespace` (slug) prefilled. If detection fails, pick **OpenAPI**, **GraphQL**, or **MCP** under **Or add manually**, or choose a preset from **Popular integrations**. | Plugin | Form behavior | Registers via | | --- | --- | --- | | OpenAPI | Auto-previews the spec (`previewSpec`), lets you set base URL, display name, namespace, description, and auth methods | `POST /openapi/specs` (`addSpec`) | | GraphQL | Endpoint, identity fields, optional auth methods (apiKey placements) | `POST /graphql/integrations` (`addIntegration`) | | MCP (remote) | Auto-probes endpoint (`probeEndpoint`), seeds auth from probe, optional stdio tab when enabled | `POST /mcp/servers` (`addServer`) | Submitting registers the integration and routes to its detail hub. Connection creation is a follow-up step on that page. Confirm the new slug appears in the Integrations grid with the expected `kind` and description. ### OpenAPI-specific fields - **Spec**: URL or raw JSON/YAML blob. Wire shape: `{ "kind": "url", "url": "..." }` or `{ "kind": "blob", "value": "..." }`. - **Base URL**: Required when the spec declares no `servers` or only relative server URLs (for example `"/api/v3"`). When omitted and servers exist, the first resolved server is used. - **Auth methods**: Derived from the spec on preview; send an explicit `authenticationTemplate` (including `[]`) to override detected methods. ## CLI `executor call`, `executor tools`, and `executor resume` auto-start the local daemon when needed. ```bash executor call executor openapi previewSpec '{"spec":"https://petstore3.swagger.io/api/v3/openapi.json"}' ``` ```bash executor call executor openapi addSpec '{ "spec": { "kind": "url", "url": "https://petstore3.swagger.io/api/v3/openapi.json" }, "slug": "petstore", "baseUrl": "https://petstore3.swagger.io/api/v3" }' ``` OpenAPI document source. `{ "kind": "url", "url": string }` or `{ "kind": "blob", "value": string }`. Catalog slug for the new integration. Override base URL when the spec uses relative `servers` entries or you need a non-default host. Agent-visible catalog description. Auth method inputs. Omit to derive from spec security schemes; pass `[]` for no auth methods. Registered integration slug. Operations extracted from the spec at registration time. ```bash executor call executor graphql addIntegration '{ "endpoint": "https://api.example.com/graphql", "slug": "example_graphql", "name": "Example GraphQL" }' ``` GraphQL HTTP endpoint URL. Catalog slug. When omitted, derived from the endpoint hostname. Static introspection JSON when live introspection is disabled on the endpoint. Declared apiKey header/query placements for connections. Registered integration slug. Display name stored on the integration. Probe before add when the server requires OAuth or custom headers: ```bash executor call executor mcp probeEndpoint '{"endpoint":"https://mcp.example.com/mcp"}' ``` ```bash executor call executor mcp addServer '{ "transport": "remote", "name": "Example MCP", "endpoint": "https://mcp.example.com/mcp", "slug": "example_mcp" }' ``` Remote stdio registration (when stdio is enabled on the runtime): ```bash executor call executor mcp addServer '{ "transport": "stdio", "name": "Local MCP", "command": "npx", "args": ["-y", "some-mcp-server"] }' ``` Remote MCP URL (remote transport). `streamable-http`, `sse`, or `auto` (default). Executable for stdio transport. Auth methods connections can apply (OAuth, apiKey, none). Registered integration slug. `addSpec`, `addIntegration`, and `addServer` are annotated `requiresApproval: true`. A CLI or MCP invocation may pause until approved. Resume with `executor resume --execution-id `. ## HTTP API | Method | Path | Purpose | | --- | --- | --- | | `POST` | `/integrations/detect` | URL type detection across loaded plugins | | `POST` | `/openapi/preview` | Preview spec servers, auth, operation count | | `POST` | `/openapi/specs` | Register OpenAPI integration | | `POST` | `/graphql/integrations` | Register GraphQL integration | | `POST` | `/mcp/probe` | Probe remote MCP endpoint shape and auth | | `POST` | `/mcp/servers` | Register MCP integration (remote or stdio) | | `GET` | `/integrations` | List tenant integrations | :::endpoint POST /integrations/detect Detect integration type from a URL. Payload: `{ "url": string }` (max 2048 chars). Returns an array of detection results sorted by confidence tier (`high`, `medium`, `low`). ::: :::endpoint POST /openapi/specs Register an OpenAPI integration. Returns `{ slug, toolCount }`. Re-adding an existing slug returns `IntegrationAlreadyExistsError` (409). ::: ## Verify with `tools sources` After adding, list configured integrations and tool counts: ```bash executor tools sources ``` Optional filters: ```bash executor tools sources --query petstore --limit 20 ``` The command executes `tools.executor.sources.list({ query?, limit?, offset? })` inside the runtime sandbox. Each item includes: | Field | Meaning | | --- | --- | | `id` / `name` | Integration slug | | `kind` | Owning plugin (`openapi`, `graphql`, `mcp`, …) | | `toolCount` | Tools currently in the catalog for that integration | | `canRemove` / `canRefresh` | Whether the integration supports removal or spec refresh | | `description` | Catalog description when it adds information beyond the slug | OpenAPI integrations typically show `toolCount > 0` immediately after `addSpec`. GraphQL and MCP integrations often show `toolCount: 0` until you create a connection; tools are materialized per connection at create/refresh time. ```bash executor tools sources ``` ```json { "items": [ { "id": "petstore", "name": "petstore", "kind": "openapi", "toolCount": 19, "canRemove": true, "canRefresh": true } ], "hasMore": false } ``` Follow-up discovery: ```bash executor tools search "list pets" --namespace petstore executor call petstore --help ``` ## Errors and constraints | Error | Cause | Recovery | | --- | --- | --- | | `integration_already_exists` | Slug collision | Pick a new slug or update the existing integration | | `openapi_parse_failed` / `openapi_extraction_failed` | Invalid or unsupported OpenAPI document | Fix the spec URL or paste valid JSON/YAML | | `graphql_introspection_failed` | Endpoint unreachable or introspection disabled | Supply `introspectionJson` or fix endpoint/auth | | `mcp_connection_failed` | MCP probe/connect failed | Check endpoint URL, transport, and headers | | Paused execution | Approval gate on add tools | `executor resume --execution-id ` | Duplicate slugs are blocked at the API layer (`IntegrationAlreadyExistsError`, HTTP 409) to avoid clobbering existing connections and policies. ## Related pages Tenant-level catalog identities, detection, and auth method descriptors. Create connections and attach credentials after registering an integration. Tool addresses, discovery, and invocation after integrations are registered. Full `executor` subcommands including `call`, `tools`, and `resume`. Integrations, connections, and plugin route groups. --- ## 11. Connect MCP clients > Wire Cursor, Claude Code, OpenCode, and other MCP clients via stdio (`executor mcp`) or streamable HTTP, including `add-mcp` setup and client restart requirements. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/11-connect-mcp-clients.md - Generated: 2026-06-23T19:24:38.361Z ### Source Files - `apps/docs/local/cli.mdx` - `apps/docs/mcp-proxy.mdx` - `apps/cli/src/main.ts` - `packages/hosts/mcp/src/tool-server.ts` - `packages/core/api/src/server/mcp-build.ts` - `apps/local/package.json` --- title: "Connect MCP clients" description: "Wire Cursor, Claude Code, OpenCode, and other MCP clients via stdio (`executor mcp`) or streamable HTTP, including `add-mcp` setup and client restart requirements." --- Executor exposes one MCP endpoint that fronts your full tool catalog. Clients connect over **streamable HTTP** at `/mcp` on a running Executor server, or over **stdio** by launching `executor mcp` as a subprocess. The web UI **Connect an agent** card and `npx add-mcp` generate copy-paste setup for Cursor, Claude Code, OpenCode, and other MCP clients. ## Prerequisites Run the durable local service (or use a hosted deployment): ```bash executor install executor daemon status ``` For a throwaway foreground runtime instead, run `executor web --foreground`. Local and self-hosted runtimes serve streamable HTTP at `/mcp`. Cloud runtimes use `//mcp`. The **Connect an agent** card on the Integrations page prints the exact URL for your deployment. An unauthenticated `POST` to the MCP URL should return **401** (auth challenge), not **404**. A 404 usually means the path or org segment is wrong. ## Choose a transport | | Remote HTTP | Standard I/O (stdio) | | --- | --- | --- | | Client config | URL to `/mcp` | Command: `executor mcp` | | Requires running daemon | Yes (`executor install` or `executor daemon run`) | No; CLI starts a foreground local server | | Auth | Bearer token (local) or OAuth (cloud/self-host) | Built into the spawned process | | Approval flow | `browser`, `model`, or `native` via `?elicitation_mode=` | `model` (default) or `browser` via `--elicitation-mode` | | Desktop app | Supported (HTTP only) | Not shown; desktop routes through the sidecar over HTTP | After you add or change an MCP server entry, most clients only load servers at startup. Restart the client or open a new chat session before expecting `execute` and `resume` tools to appear. ## Connect with `add-mcp` `npx add-mcp` detects the installed MCP client and writes its config. Use the command from the **Connect an agent** card when possible; it already includes your origin, org slug (cloud), auth header (when needed), and elicitation mode. ```bash npx add-mcp http://127.0.0.1:4789/mcp --transport http --name executor ``` When the web UI has an active bearer session, the generated command may append an auth header: ```bash npx add-mcp http://127.0.0.1:4789/mcp --transport http --name executor --header 'Authorization: Bearer ' ``` On Executor Cloud, the URL is org-scoped: ```bash npx add-mcp https://executor.example/acme-corp/mcp --transport http --name executor ``` Requires the published `executor` CLI on your `PATH`: ```bash npx add-mcp "executor mcp" --name executor ``` Pin a workspace scope (directory containing `executor.jsonc`): ```bash npx add-mcp "executor mcp --scope /path/to/workspace" --name executor ``` Browser approval over stdio: ```bash npx add-mcp "executor mcp --elicitation-mode browser" --name executor ``` Restart your MCP client after running `add-mcp`. Until the client reloads its server list, Executor tools will not be available in the session. ## Use the Connect card The **Connect an agent** card on the Integrations page is the canonical source for install commands: - **Remote HTTP** is the default tab. It targets streamable HTTP at your server's `/mcp` path (or `//mcp` on cloud). - **Standard I/O** appears on local runtimes where the `executor` CLI is on `PATH`. The desktop app shows HTTP only because it does not ship a global `executor` binary. - **Advanced → Resume approvals** sets how paused tool calls are handled (see [Elicitation modes](#elicitation-modes) below). Executor Cloud also surfaces MCP setup on `/setup-mcp` during onboarding. ## Manual client configuration If you prefer to edit config files directly, use the same transport and URL the Connect card would generate. ### Claude Code / Cursor (stdio) ```json { "mcpServers": { "executor": { "command": "executor", "args": ["mcp"] } } } ``` With scope and browser approval: ```json { "mcpServers": { "executor": { "command": "executor", "args": ["mcp", "--scope", "/path/to/workspace", "--elicitation-mode", "browser"] } } } ``` ### OpenCode (remote HTTP) ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "executor": { "type": "remote", "url": "http://127.0.0.1:4789/mcp", "enabled": true } } } ``` Replace the URL with your deployment's MCP endpoint. On cloud, use `https:////mcp`. ## MCP endpoint reference :::endpoint POST /mcp Streamable-HTTP MCP transport. Creates a session on the first `POST` without an `mcp-session-id` header; subsequent requests forward to the active session. Also accepts `GET`, `DELETE`, and `OPTIONS` (CORS preflight). ::: Local runtimes gate `/mcp` with a bearer token (401 when missing). Cloud and self-hosted deployments authenticate through their OAuth layer (401 challenge with protected-resource metadata). Session identifier returned by the transport. Required on follow-up requests after session creation. Query parameter on the MCP URL. One of `browser`, `model`, or `native`. Defaults to `model`. Legacy alias: `allow_model_resume=true` maps to `model`. ### Default ports by runtime | Runtime | Typical port | MCP path | | --- | --- | --- | | `executor install` (supervised daemon) | `4789` | `/mcp` | | `executor daemon run` | `4788` | `/mcp` | | Docker self-host | `17888` | `/mcp` | | Executor Cloud | HTTPS default | `//mcp` | The CLI may pick another free port when the default is busy. Use `executor daemon status` or the Connect card for the live origin; do not hard-code a port unless you pin it yourself. ## `executor mcp` (stdio) ```bash executor mcp [--scope ] [--elicitation-mode browser|model] ``` Sets `EXECUTOR_SCOPE_DIR` to a workspace directory containing `executor.jsonc`. `model` exposes a `resume` tool the agent calls with accept/decline/cancel. `browser` returns an approval URL and waits for a browser decision before resuming. Stdio behavior: - The CLI reroutes `stdout` logging to `stderr` so MCP JSON-RPC on stdout stays clean. - It starts a foreground local HTTP server, publishes a local server manifest, connects an MCP server over `StdioServerTransport`, and tears down when the client closes stdin or sends `SIGINT`/`SIGTERM`. - Stdio does not support `native` elicitation; use Remote HTTP with `?elicitation_mode=native` for that mode. ## Elicitation modes Paused executions (auth or policy approval) behave differently per mode: | Mode | Transport | Behavior | | --- | --- | --- | | `model` (default) | HTTP query or stdio default | Agent calls the `resume` MCP tool with `executionId`, `action`, and optional `content` | | `browser` | HTTP query or stdio `--elicitation-mode` | `execute` returns an `approvalUrl`; user approves in the web UI; agent calls `resume` to wait for the decision | | `native` | HTTP query only | Executor uses the client's native MCP elicitation capability during `execute` | HTTP examples: ``` http://127.0.0.1:4789/mcp?elicitation_mode=browser https://executor.example/acme-corp/mcp?elicitation_mode=native ``` ## MCP tools exposed to clients Every Executor MCP session registers: | Tool | Always present | Purpose | | --- | --- | --- | | `execute` | Yes | Run TypeScript against the tool catalog (discover, call, handle pauses) | | `resume` | When elicitation mode is not `native` | Continue a paused execution | New integrations added in the web UI or CLI appear in the catalog automatically; you do not reconfigure the MCP client per integration. ## Verify the connection Quit and reopen the MCP client, or start a new chat/agent session, so it reloads server definitions. In the client, check that `execute` (and `resume` when applicable) appear in the MCP tool list. ```bash executor tools sources executor tools search "list issues" ``` These commands auto-start the local daemon when needed. ## Troubleshooting Most MCP clients load servers only at startup. Restart the client or open a new chat. If you edited config manually, confirm JSON syntax and that the transport (`http` URL vs `command`/`args`) matches your chosen mode. Local HTTP requires a bearer token on every `/mcp` request. Copy the `--header 'Authorization: Bearer …'` flags from the Connect card, or read the token from `auth.json` under your `EXECUTOR_DATA_DIR`. Cloud and self-hosted endpoints expect OAuth; complete the client authorization flow when prompted. On self-host, the server serves bare `/mcp` but the card may print `//mcp` for parity with cloud routing. The self-host front-end strips the org segment; if you still see 404, confirm you are hitting the correct origin and that the daemon is running (`executor daemon status`). Install the global CLI (`npm install -g executor`) or switch to Remote HTTP. On monorepo dev checkouts, the Connect card uses `bun run dev:cli mcp` instead of `executor mcp`. Paused executions live in the session runtime and expire after a few minutes or when the host restarts. Re-run `execute` with the original code to obtain a fresh `executionId`. ## Related pages How Executor fronts OpenAPI, GraphQL, and upstream MCP integrations behind one endpoint. Register sources so they appear in the MCP catalog after you connect a client. Full `executor mcp`, `daemon`, and `install` flags and behavior. Org-scoped MCP URLs and OAuth on Executor Cloud. Daemon port conflicts, unreachable servers, and recovery commands. --- ## 12. Configure credentials > Credential providers (file secrets, keychain, 1Password, encrypted stores), connection creation payloads, OAuth flows, and placement-based auth templates. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/12-configure-credentials.md - Generated: 2026-06-23T19:24:35.489Z ### Source Files - `packages/core/api/src/oauth/api.ts` - `packages/core/api/src/handlers/oauth.ts` - `packages/core/sdk/src/oauth-service.ts` - `packages/plugins/file-secrets/src/sdk/plugin.ts` - `packages/plugins/keychain/src/sdk/plugin.ts` - `packages/plugins/onepassword/src/sdk/plugin.ts` - `packages/core/sdk/src/http-auth.ts` --- title: "Configure credentials" description: "Credential providers (file secrets, keychain, 1Password, encrypted stores), connection creation payloads, OAuth flows, and placement-based auth templates." --- Executor stores credentials as **connections**: owner-scoped bindings to one integration, one auth template, and one credential provider. Static secrets are created with `connections.create` (HTTP `POST /connections`, SDK `executor.connections.create`); OAuth connections are minted through `oauth.start` / `oauth.complete`. Protocol plugins declare **placement-based auth templates** via `@executor-js/sdk/http-auth`; the runtime resolves credential values lazily per tool call. ## Credential providers A `CredentialProvider` is where secret material lives. The connection row stores routing (`provider` key plus opaque `item_ids` per template variable), not the secret itself. Providers register at executor startup from `createExecutor({ providers: [...] })` and from each plugin's `credentialProviders` hook. Config-level providers register first and the **first writable provider** becomes the default store for pasted `value` / `values` inputs. | Provider key | Package | Writable | Storage | `list` support | |---|---|---|---|---| | `file` | `@executor-js/plugin-file-secrets` | yes | Flat JSON map at `{XDG_DATA_HOME}/executor/auth.json` (mode `0600`) | yes | | `keychain` | `@executor-js/plugin-keychain` | yes | OS keychain (`@napi-rs/keyring`, service name default `executor`) | no | | `onepassword` | `@executor-js/plugin-onepassword` | no (read-only) | `op://` URIs scoped to a configured vault | yes | | `workos-vault` | `@executor-js/plugin-workos-vault` | yes | WorkOS Vault (KEK-partitioned encrypted objects) | yes | The keychain plugin probes write/delete at startup. If the platform keychain is unreachable (headless CI, WSL without secret-service), the provider is skipped rather than registered. ### File secrets (`file`) Secrets are a flat map of opaque id to value. The v2 model drops per-scope partitioning; the connection row owns the `(tenant, owner, subject)` partition. ```json { "github-token": "ghp_xxx", "connection:org:inventory:default:token": "inventory-api-key" } ``` Override the directory with `fileSecretsPlugin({ directory: "/path/to/dir" })`. The extension exposes `executor.fileSecrets.filePath`. ### Keychain (`keychain`) Each `ProviderItemId` is the keychain account name. Override the service name with `keychainPlugin({ serviceName: "my-app" })`. ### 1Password (`onepassword`) Configure once per owner partition via the plugin tools (`onepassword.configure`) or extension API. Auth modes: - `desktop-app` with `accountName` (local biometric) - `service-account` with `token` Item ids are either fully qualified `op://vault/item/field` URIs or bare item ids scoped to the configured vault. The provider resolves secrets on read; it never writes. ### WorkOS Vault (`workos-vault`) Cloud-hosted encrypted storage for self-host and Executor Cloud. Requires `workosVaultPlugin({ credentials: { apiKey, clientId } })` or a pre-built client. Object names encode owner partitions (`connection::...`, `oauth::...`). ### Register providers in application code ```typescript title="SDK (promise mode)" import { createExecutor, ProviderKey, ProviderItemId, Effect } from "@executor-js/sdk/promise"; import { fileSecretsPlugin, keychainPlugin, onepasswordPlugin } from "..."; const memory = new Map(); const memoryProvider = { key: ProviderKey.make("memory"), writable: true, get: (id) => Effect.sync(() => memory.get(String(id)) ?? null), set: (id, value) => Effect.sync(() => { memory.set(String(id), value); }), }; const executor = await createExecutor({ plugins: [fileSecretsPlugin(), keychainPlugin(), onepasswordPlugin()], providers: [memoryProvider], // registers first; wins as default writable }); ``` ```typescript title="all-plugins reference" // examples/all-plugins wires every published provider + protocol plugin. // Uncomment workosVaultPlugin when WORKOS_API_KEY is available. ``` Discover registered backends: | Endpoint | Returns | |---|---| | `GET /providers` | `ProviderKey[]` | | `GET /providers/:key/items` | `{ id, name }[]` for browse-and-pick UIs | ## Connection creation payloads A connection is identified by `(owner, integration, name)` where `owner` is `org` (workspace-shared) or `user` (personal). The `template` field selects one auth method slug from the integration catalog. ### Credential origin (exactly one) The HTTP API enforces one origin per create request. The SDK accepts the same shapes plus a per-variable `inputs` map. Single pasted secret. Sugar for the `token` variable. Written to the default writable provider at `connection:{owner}:{integration}:{name}:token`. One pasted value per placement variable. Required for multi-input methods (for example Datadog `api_token` + `team_id`). Reference an external provider entry. The value is resolved on demand; Executor stores only the opaque id. SDK-only canonical form. Mixes `{ value }` and `{ from: { provider, id } }` per variable. HTTP create does not expose this field yet. ### Common fields `org` or `user`. Personal connections require a signed-in subject. Unique per `(owner, integration)`. Catalog slug for the OpenAPI, GraphQL, or MCP source. Auth method slug (`apiKey`, `bearer`, `oauth2`, `none`, ...). Optional human label (which account). Agent-visible context surfaced in `connections.list` and execute-tool inventory. ### Constraints - A credentialed template requires at least one input. Exception: `template: "none"` for public integrations (empty `values: {}` is valid). - Cannot mix pasted and external inputs in one connection. - All external inputs must use the same provider. - OAuth connections are minted via `oauth.start`, not `connections.create`. ```json title="POST /connections — single API key" { "owner": "org", "name": "default", "integration": "inventory", "template": "apiKey", "value": "inventory-api-key" } ``` ```json title="POST /connections — multi-input method" { "owner": "org", "name": "mixed", "integration": "datadog", "template": "token_and_team", "values": { "api_token": "tok_mixed", "team_id": "team_42" } } ``` ```json title="POST /connections — external provider reference" { "owner": "org", "name": "prod", "integration": "github", "template": "apiKey", "from": { "provider": "onepassword", "id": "op://VaultName/GitHub/item/password" } } ``` ```json title="Connection response" { "owner": "org", "name": "default", "integration": "inventory", "template": "apiKey", "provider": "file", "address": "tools.inventory.org.default", "identityLabel": null, "description": null, "expiresAt": null, "oauthClient": null, "oauthClientOwner": null, "oauthScope": null } ``` Creating a connection writes the credential, persists the connection row, and **produces per-connection tools** for that integration. ## Placement-based auth templates Protocol plugins (OpenAPI, GraphQL, MCP) share the `@executor-js/sdk/http-auth` vocabulary. An integration declares a **list** of auth methods; a connection binds one by `template` slug. ### ApiKey methods Each `apikey` method carries `placements`: spots on the outbound HTTP request. | Placement field | Role | |---|---| | `carrier` | `header` or `query` | | `name` | Header or query param name | | `prefix` | Literal prepended to the credential (for example `Bearer `) | | `variable` | Credential input name; defaults to `token` | | `literal` | Static value with no credential input | Core resolves `values: Record` and plugins render via `renderAuthPlacements`. Use `requiredPlacementVariables(placements)` to know which inputs a connection must supply. ### Authoring dialect Plugin registration inputs accept a request-shaped template normalized at the boundary: ```typescript import { variable } from "@executor-js/sdk/http-auth"; authenticationTemplate: [ { slug: "token_and_team", type: "apiKey", headers: { Authorization: ["Bearer ", variable("api_token")] }, queryParams: { team_id: [variable("team_id")] }, }, { slug: "bearer", type: "apiKey", headers: { Authorization: ["Bearer ", variable("token")] } }, { kind: "oauth2" }, // OAuth is per-plugin, not in placements model ] ``` Rules for template values: - A parts-array renders at most **one** variable, and it must be the **final** part. - Two placements sharing a `variable` share one credential input. - Distinct variables get distinct inputs (and a `values` map at connect time). ### OAuth methods OAuth is **not** modeled as placements. Each protocol plugin carries its own OAuth variant (`kind: "oauth2"` for OpenAPI/MCP, with plugin-specific endpoint/scope fields). OAuth-refreshed connections resolve only the `token` input; do not mix OAuth token values into apikey placement methods. ### None auth `{ slug: "none", kind: "none" }` integrations need no credential. Create with `template: "none"` and no value origin. ## OAuth flows OAuth is a credential mechanism separate from integration type. The v2 model: 1. **Register an OAuth app** (`oauth_client` row) with endpoints and client credentials. 2. **Start a flow** through that app to mint a connection for one integration. 3. **Complete** the authorization code exchange (or connect inline for `client_credentials`). ```mermaid sequenceDiagram participant UI as Web UI / client participant API as Executor HTTP API participant OAuth as oauth service participant AS as Authorization server participant CP as Credential provider UI->>API: POST /oauth/clients (createClient) API->>OAuth: createClient OAuth->>CP: set oauth-client:{owner}:{slug}:secret UI->>API: POST /oauth/start API->>OAuth: start alt client_credentials OAuth->>AS: token exchange OAuth->>CP: set oauth:{owner}:{integration}:{name} OAuth-->>UI: { status: "connected", connection } else authorization_code OAuth->>OAuth: persist oauth_session + PKCE OAuth-->>UI: { status: "redirect", authorizationUrl, state } UI->>AS: user authorizes AS->>API: GET /oauth/callback?state&code API->>OAuth: complete OAuth->>AS: code exchange OAuth->>CP: set access + refresh tokens OAuth-->>UI: connection (via popup postMessage) end ``` ### OAuth HTTP endpoints | Method | Path | Purpose | |---|---|---| | `POST` | `/oauth/clients` | Register owner-scoped OAuth app | | `POST` | `/oauth/clients/register-dynamic` | RFC 7591 Dynamic Client Registration | | `GET` | `/oauth/clients` | List visible apps (no secrets) | | `DELETE` | `/oauth/clients/:slug` | Remove app (connections fail at next refresh) | | `POST` | `/oauth/start` | Begin flow; returns `connected` or `redirect` | | `POST` | `/oauth/complete` | Exchange code, mint connection | | `POST` | `/oauth/cancel` | Drop in-flight session | | `POST` | `/oauth/probe` | Discover AS metadata for onboarding | | `GET` | `/oauth/callback` | Browser callback; renders popup HTML | ### Start payload OAuth app slug. Owner of the OAuth app. A personal connection may use a shared workspace app (`clientOwner: "org"`, `owner: "user"`). Workspace connections cannot use a personal app. Connection owner to mint. Connection name. Target integration. OAuth template slug (for example `oauth2`). Per-flow override. Defaults to executor `redirectUri` (`${webBaseUrl}${mountPrefix}/oauth/callback`). Required for `authorization_code` flows; hosts without a callback must fail loudly. Requested scopes come from the integration's **declared** OAuth scopes for `(integration, template)`, not from the OAuth app row. ### Token storage layout | Item id pattern | Content | |---|---| | `oauth:{owner}:{integration}:{name}` | Access token | | `oauth:{owner}:{integration}:{name}:refresh` | Refresh token | | `oauth-client:{owner}:{slug}:secret` | OAuth app client secret | The connection row records `oauthClient`, `oauthClientOwner`, `oauthScope`, `expiresAt`, and optional regional `oauthTokenUrl` override (Datadog multi-site). ### Dynamic Client Registration `POST /oauth/clients/register-dynamic` mints a public PKCE client via the server's `registration_endpoint`. The user supplies no client id/secret. Auth method negotiation: `none` when advertised or empty; otherwise `client_secret_post`. ### Probe `POST /oauth/probe` with `{ url }` tries RFC 9728 protected-resource metadata first, then RFC 8414/OIDC authorization-server metadata. Returns `authorizationUrl`, `tokenUrl`, `scopesSupported`, `registrationEndpoint`, and related fields for UI pre-fill. `redirectUri` has no localhost default. An executor constructed without it rejects redirect-requiring flows instead of registering a wrong callback URL with providers. ## Runtime resolution On each tool invocation, the executor: 1. Loads the connection row and resolves the registered `CredentialProvider`. 2. For OAuth connections with expired (or near-expired) tokens, refreshes first (shared in-flight gate prevents parallel refresh races). 3. Fetches each `item_ids[variable]` from the provider. 4. Passes `values` to the protocol plugin, which renders placements onto the outbound request. Errors surface as `CredentialProviderNotRegisteredError` (HTTP 409), `InvalidConnectionInputError` (HTTP 400), or `CredentialResolutionError` with `reauthRequired: true` when refresh fails. ## Configure from the web UI The connect modal mirrors the HTTP payloads: 1. Pick owner (`org` / `user`), connection name, and auth method from the integration catalog. 2. For apikey methods, fill one field per `requiredPlacementVariables` entry (or browse external provider items via `GET /providers/:key/items`). 3. For OAuth, select an OAuth app, call `POST /oauth/start`, complete the browser redirect, and receive the minted connection. 4. Verify with `connections.list` or `tools.list` filtered by integration. Provider choice is automatic: pasted values go to the default writable provider; `from` references route to the named external provider. ## Failure modes | Symptom | Likely cause | Recovery | |---|---|---| | `Credential provider "default" is not registered` | No writable provider registered | Add `fileSecretsPlugin`, `keychainPlugin`, inline provider, or `workos-vault` | | `Expected exactly one credential origin` | Multiple of `value`, `values`, `from` in one payload | Send exactly one origin field | | `A connection cannot mix pasted and external-provider inputs` | Mixed `value` + `from` (or `inputs` mix) | Use all pasted or all external per connection | | `OAuth redirect flow requires a configured redirectUri` | Host missing callback URL | Set `redirectUri` on `createExecutor`; local default is `{webBaseUrl}/api/oauth/callback` | | `OAuth session expired or not found` | TTL exceeded or cancelled session | Restart with `POST /oauth/start` | | Keychain provider missing | Probe failed at startup | Use `file` provider or fix secret-service on Linux | | 1Password returns null | Not configured or URI outside vault | Run `onepassword.configure`; check vault scope | ## Related pages Owner-scoped credential identity, provider resolution, and the `(owner, integration, name)` model. How auth method descriptors are declared and projected into the catalog. Full route listings for `connections`, `providers`, and `oauth` groups. Compose `createExecutor` with plugins and credential providers in application code. Published provider plugins and how `examples/all-plugins` wires them. `EXECUTOR_DATA_DIR`, `EXECUTOR_WEB_BASE_URL`, and OAuth callback derivation. --- ## 13. Manage policies > Create and update owner-scoped tool policies, interpret effective policy precedence, and handle approval pauses from the web UI, MCP, and CLI resume flow. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/13-manage-policies.md - Generated: 2026-06-23T19:25:56.731Z ### Source Files - `apps/docs/concepts/policies.mdx` - `packages/core/api/src/policies/api.ts` - `packages/core/api/src/handlers/policies.ts` - `packages/core/sdk/src/policies.ts` - `packages/hosts/mcp/src/browser-approval.ts` - `packages/hosts/mcp/src/browser-approval-store.ts` --- title: "Manage policies" description: "Create and update owner-scoped tool policies, interpret effective policy precedence, and handle approval pauses from the web UI, MCP, and CLI resume flow." --- Executor persists owner-scoped tool policies in the `tool_policy` table and resolves them on every `tools.list` and `execute` call through `resolveEffectivePolicy`. Policies are created and updated through the web UI at `/policies`, the HTTP `policies` API group, SDK `executor.policies` methods, and built-in core tools (`executor.coreTools.policies.*`). When a matched action is `require_approval`, invocation pauses until a human approves via the console `/resume/:executionId` page, the MCP `resume` tool, or `executor resume`. ## Policy actions | Action | At list time | At invoke time | |--------|--------------|----------------| | `approve` | Tool appears in search and catalog | Runs without an approval prompt | | `require_approval` | Tool appears | Pauses for human approval before running | | `block` | Hidden from search (unless `includeBlocked`) | Fails with `ToolBlockedError` | The HTTP API and SDK schema use `approve`, not `allow`. User-facing labels in the web UI map `approve` to **Allow**. ## Owner scopes Each policy row is scoped to an `owner`: | Owner | Web UI label | Role | |-------|--------------|------| | `org` | Workspace (or **Local** on single-player hosts) | Outer guardrail shared across the workspace | | `user` | Personal | Inner preference for the signed-in member | Org and user each contribute at most one matched rule per tool. The final action is the **most restrictive** match across owners: `block` beats `require_approval`, which beats `approve`. A user `approve` cannot weaken an org `block`; a user `require_approval` can strengthen an org `approve`. Within a single owner, rules are ordered by `position` (fractional-indexing key). Lower lexicographic `position` means higher precedence. The first matching pattern for that owner wins. ## Pattern grammar Policies match against the full tool address: ```text ... ``` Static core tools (for example `executor.coreTools.policies.list`) match on their fqid address directly. | Pattern form | Example | Matches | |--------------|---------|---------| | Universal | `*` | Every tool | | Integration subtree | `vercel.*` | Any tool under `vercel` | | Trailing wildcard | `vercel.dns.*` | Literal prefix plus anything deeper | | Exact | `vercel.dns.create` | One tool path | | Mid-segment `*` | `vercel.*.*.dns.create` | Wildcards exactly one segment per `*` | Invalid patterns are rejected at create time: empty strings, leading `*`, partial wildcards like `me*`, and consecutive dots are not allowed. Use `isValidPattern` (SDK) or the web UI validator before writing rules. ### Connection-agnostic UI patterns The tools tree displays `integration.` without owner or connection segments. When you author a rule from a tool or category row, the UI stores a connection-wildcarded pattern via `toPolicyPattern`: ```text integration.*.*. ``` A leaf rule on `records.create` becomes `myapi.*.*.records.create`; a category rule on `records` becomes `myapi.*.*.records.*`. Rules authored on one connection apply to every connection for that integration. ## Effective policy resolution ```mermaid flowchart TD subgraph inputs [Inputs per tool call] T[Tool address] P[Owner-scoped policy rows] D[Plugin default annotation] end subgraph perOwner [Per owner] O1[Org: first match by position] O2[User: first match by position] end subgraph merge [Cross-owner merge] M[Most restrictive action wins] end subgraph fallback [No user match] F[Plugin default: requiresApproval or approve] end T --> O1 T --> O2 P --> O1 P --> O2 O1 --> M O2 --> M M -->|no match| F D --> F ``` When no user-authored rule matches, the executor falls back to the plugin annotation `requiresApproval`. OpenAPI maps `POST`, `PUT`, `PATCH`, and `DELETE` to `requiresApproval: true`; read-only `GET` operations default to auto-approve. MCP upstream tools inherit `requiresApproval` from `destructiveHint`. ## Manage policies in the web UI Open **Policies** (`/policies`) to list, create, reorder, and remove rules. Enter a pattern, choose an action (`Allow`, `Require approval`, or `Block`), and pick **Workspace** or **Personal** when the host exposes both owners. Click **Add policy**. New rules without an explicit position are inserted at the top of that owner's list (highest precedence). On an integration's **Tools** tab, use **Set policy for …** on a tool row (exact rule) or category row (subtree rule). The menu previews the stored pattern before write. The tool detail header badge is the same surface: set, recognize, or clear a rule. Use **Move up** / **Move down** on `/policies` to change `position`. More-specific patterns should sit above broader ones so a leaf rule is not shadowed by a later group rule. Confirm the rule appears under **Active policies** with the expected owner, pattern, and action. Invoke a gated tool or run `tools.list` to confirm blocked tools disappear from search. `usePolicyActions` auto-places new tree-authored rules below more-specific existing rules so a freshly added group rule does not silently override a leaf rule. ## HTTP API | Method | Path | Purpose | |--------|------|---------| | `GET` | `/policies` | List all policies for the authenticated identity | | `POST` | `/policies` | Create a policy | | `PATCH` | `/policies/:policyId` | Update pattern, action, or position | | `DELETE` | `/policies/:policyId` | Remove a policy | :::endpoint POST /policies Create an owner-scoped tool policy. ::: `org` or `user`. Tool address pattern. Must pass `isValidPattern`. `approve`, `require_approval`, or `block`. Optional fractional-indexing key. Omit to place at the top of the owner's list. Stable policy identifier. `org` or `user`. Stored match pattern. `approve`, `require_approval`, or `block`. Fractional-indexing order key. Unix milliseconds. Unix milliseconds. ```bash title="Create a require-approval gate" curl -X POST "$EXECUTOR_BASE_URL/policies" \ -H "content-type: application/json" \ -H "authorization: Bearer $TOKEN" \ -d '{ "owner": "org", "pattern": "executor.coreTools.policies.list", "action": "require_approval" }' ``` ::: :::endpoint PATCH /policies/:policyId Update an existing policy. The payload must include `owner` so the handler can verify partition ownership. ::: Policy to update. Owning partition (`org` or `user`). New pattern. New action. New order key for precedence within the owner. ::: :::endpoint DELETE /policies/:policyId Remove a policy. Payload requires `owner`. ::: Policy to remove. Owning partition (`org` or `user`). ::: ## SDK and core tools `createExecutor` exposes `executor.policies.list`, `.create`, `.update`, `.remove`, and `.resolve(address)`. ```typescript title="SDK (promise mode)" const policy = await executor.policies.create({ owner: "org", pattern: "myapi.*.*.records.create", action: "require_approval", }); const effective = await executor.policies.resolve( "myapi.org.prod.records.create" as ToolAddress, ); ``` ```typescript title="Core tools via execute" const result = await tools.executor.coreTools.policies.create({ owner: "org", pattern: "vercel.dns.*", action: "block", }); ``` `policies.create`, `policies.update`, and `policies.remove` core tools carry `annotations: { requiresApproval: true }`. Mutating policies always pauses for approval so prompt-injected code cannot silently disable guardrails. ## Handle approval pauses When effective policy or tool annotations require approval, `execute` pauses and returns a `PausedExecution`. Resume the pause from the console, MCP, or CLI. ### Web console Browser approval URLs follow: ```text /resume/?mcp_session_id= ``` The `mcp_session_id` query routes MCP-session-scoped pauses to `/api/mcp-sessions/:id/executions/:executionId/resume`. Pauses without that query use the standard `/api/executions/:executionId/resume` path. Follow the `approvalUrl` from the paused MCP result or the link printed by `executor call` / `executor resume`. The page shows the elicitation message, tool id, and argument preview. Click **Approve**, **Decline**, or **Cancel**. The host records `{ action, content? }` and wakes any in-flight `resume` waiter. ### MCP elicitation modes | Mode | Query | Resume surface | |------|-------|----------------| | `browser` (typical for human-in-the-loop) | `?elicitation_mode=browser` | `approvalUrl` plus long-poll on MCP `resume` | | `model` (default) | absent or `?elicitation_mode=model` | MCP `resume` tool exposed to the agent | | `native` | `?elicitation_mode=native` | Client-native elicitation only; no `resume` tool | In `browser` mode, `BrowserApprovalStore.waitForResponse(executionId)` blocks until the console posts a decision. `recordResponse` wakes the waiter. ### CLI resume ```bash executor resume --execution-id --action accept executor resume --execution-id --action decline executor resume --execution-id --action cancel ``` Optional `--content '{"key":"value"}'` supplies form content when `action=accept`. If the resumed execution pauses again, the CLI prints the next approval URL. `executor call`, `executor resume`, and `executor tools` auto-start the local daemon when needed. ```text title="Paused call output" Approval required: http://127.0.0.1:5173/resume/exec_abc123?mcp_session_id=sess_xyz ``` ### Declined or canceled approvals If the human declines or cancels, the engine returns `ElicitationDeclinedError` and the gated tool does not run. For browser flows, the MCP `resume` call completes with acknowledgement text (`I've denied it`, `I've canceled it`) rather than the tool result. ## Troubleshooting Check owner precedence first (org block beats user approve), then position within the owner (lower `position` wins). A broad rule listed above a specific rule shadows the leaf. Tree-authored rules store `integration.*.*.`. Compare against the full five-segment address or static fqid, not the shortened display id. Confirm the console approval page loaded with the same `mcp_session_id` from the paused result and that you clicked Approve or Decline. The in-process store times out after 10 minutes without a decision. Policy writes are optimistic in the web UI. A failed API call rolls back the row; check network errors on create/update/remove. ## Related pages Per-tool actions, pattern matching grammar, and plugin-derived defaults. Paused states, `execute` and `resume` routes, and elicitation handling. Single MCP endpoint, elicitation modes, and shared policy enforcement. Full `policies` route payloads and error shapes. `executor resume`, `executor call`, and auto-start behavior. --- ## 14. Embed with the SDK > Compose `createExecutor` with plugins and credential providers, register integrations, create connections, list and invoke tools, and shut down cleanly in application code. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/14-embed-with-the-sdk.md - Generated: 2026-06-23T19:26:01.498Z ### Source Files - `packages/core/sdk/src/executor.ts` - `packages/core/sdk/src/promise.ts` - `packages/core/sdk/package.json` - `examples/docs-sdk-quickstart/src/main.ts` - `examples/all-plugins/src/main.ts` - `packages/plugins/openapi/README.md` --- title: "Embed with the SDK" description: "Compose `createExecutor` with plugins and credential providers, register integrations, create connections, list and invoke tools, and shut down cleanly in application code." --- `@executor-js/sdk` exposes `createExecutor`, a composable runtime that wires protocol plugins, credential providers, and a FumaDB-backed catalog into one typed `Executor` object. Application code registers integrations through plugin extensions (`executor.openapi.addSpec`, `executor.graphql.addIntegration`, `executor.mcp.addServer`), saves credentials as connections, lists persisted tools per connection, and invokes them with `executor.execute`. The default published import is Promise-based; the Effect entry at `@executor-js/sdk/core` is for plugin authors and hosts that already run on Effect. ## Install ```sh bun add @executor-js/sdk @executor-js/plugin-openapi ``` Add additional `@executor-js/plugin-*` packages for GraphQL, MCP, keychain, file-secrets, 1Password, Google bundles, or WorkOS Vault as needed. See the [plugin catalog](/plugin-catalog) for the full set. ## Import paths Use the root or `/promise` subpath. Every Effect-returning method is promisified; no Effect dependency required in application code. ```ts import { createExecutor, ProviderKey, ProviderItemId } from "@executor-js/sdk"; import { openApiPlugin, variable } from "@executor-js/plugin-openapi"; ``` `examples/docs-sdk-quickstart` is the canonical snippet source for this surface. Use `@executor-js/sdk/core` (or `@executor-js/sdk` in the monorepo dev tree) when the host already runs on Effect. Plugin factories and credential provider `get`/`set` methods return `Effect`s. ```ts import { Effect } from "effect"; import { createExecutor, Tenant } from "@executor-js/sdk/core"; import { openApiPlugin } from "@executor-js/plugin-openapi/core"; const program = Effect.gen(function* () { const executor = yield* createExecutor({ tenant: Tenant.make("my-tenant"), /* ... */ }); yield* executor.close(); }); ``` `examples/all-plugins` exercises this shape end to end. Plugin READMEs that reference `executor.tools.invoke`, `executor.scopes`, or `executor.secrets` describe the pre-v2 surface. The v2 SDK invokes tools with `executor.execute(address, args)` and stores credentials as connections routed through credential providers. ## Architecture ```mermaid flowchart TB subgraph app [Application] CE["createExecutor(config)"] EX["Executor"] end subgraph plugins [Protocol plugins] OA["executor.openapi"] GQL["executor.graphql"] MCP["executor.mcp"] end subgraph providers [Credential providers] MEM["inline memory provider"] KC["keychain / file-secrets / 1Password"] end subgraph store [Persistence] DB["FumaDB (default: in-memory)"] end CE --> EX EX --> plugins EX --> providers EX --> DB OA -->|"addSpec"| INT["integrations catalog"] INT -->|"connections.create"| CON["connections + tool rows"] CON -->|"tools.list"| TOOLS["addressable tools"] TOOLS -->|"execute"| INV["plugin.invokeTool"] providers --> INV ``` Integrations are tenant-level catalog entries. Connections bind a credential to one integration and produce that integration's tools. Tool addresses follow `tools....`; the tool segment may contain dots (for example `tools.inventory.org.default.items__list`). ## Compose `createExecutor` Pass protocol plugins in `plugins` and optional inline credential providers in `providers`. Plugins may also contribute providers through `plugin.credentialProviders`; config-level providers register first and win as the default writable store. `onElicitation` is required. Pass `"accept-all"` for scripts, tests, and non-interactive hosts. Pass a handler function for interactive hosts that must answer approval prompts and mid-call form or URL elicitations. `createExecutor` returns a Promise (Promise surface) or `Effect` (Effect surface). Plugin extension methods are merged onto the returned object as `executor[pluginId]` (for example `executor.openapi`). ### `ExecutorConfig` fields | Field | Default | Role | | --- | --- | --- | | `tenant` | `"default-tenant"` | Org/workspace partition for `owner: "org"` rows | | `subject` | omitted | Acting member; required to target `owner: "user"` | | `plugins` | `[]` | Protocol and provider plugins to load | | `providers` | `[]` | Inline credential providers (registered before plugin providers) | | `db` | in-memory FumaDB | Persistent store factory or handle; omit for ephemeral scripts | | `onElicitation` | required | `"accept-all"` or `(ctx) => ElicitationResponse` | | `redirectUri` | none | OAuth callback URL; required for interactive OAuth (no localhost default) | | `coreTools` | disabled | Built-in agent-facing static tools over integrations/connections/policies | | `blobs` | FumaDB blob table | Object-store backend for large plugin blobs | | `httpClientLayer` / `fetch` | platform default | Outbound HTTP for plugins | Org or workspace id. Branded as `Tenant` on the Effect surface. Optional member id. Omit for a pure-org executor with no `owner: "user"` rows. Plugin factories such as `openApiPlugin()`, `graphqlPlugin()`, `mcpPlugin()`, `keychainPlugin()`, `fileSecretsPlugin()`. Writable stores for inline credential values. A writable provider is required before `connections.create({ value })` can persist a pasted secret. How the executor answers approval prompts and tool elicitations. Overridable per call through `execute` options. Supply a SQLite/LibSQL handle for durable hosts (as `apps/local` does). Omit to use the SDK's ephemeral in-memory adapter. OAuth redirect such as `${webBaseUrl}/oauth/callback`. Omit only when the executor never runs interactive OAuth. Enable `core-tools` static tools. Set `webBaseUrl`, optional `orgSlug`, and `includeProviders` for agent-facing configuration helpers. ### Minimal composition ```ts title="Promise — in-memory script" import { createExecutor, ProviderKey, ProviderItemId, type CredentialProvider } from "@executor-js/sdk"; import { Effect } from "effect"; import { openApiPlugin } from "@executor-js/plugin-openapi"; const memory = new Map(); const memoryProvider: CredentialProvider = { key: ProviderKey.make("memory"), writable: true, get: (id) => Effect.sync(() => memory.get(String(id)) ?? null), set: (id, value) => Effect.sync(() => { memory.set(String(id), value); }), }; const executor = await createExecutor({ plugins: [openApiPlugin()], providers: [memoryProvider], onElicitation: "accept-all", }); ``` ```ts title="Effect — with tenant" import { Effect } from "effect"; import { createExecutor, Tenant } from "@executor-js/sdk/core"; import { openApiPlugin } from "@executor-js/plugin-openapi/core"; const executor = yield* createExecutor({ tenant: Tenant.make("example-tenant"), plugins: [openApiPlugin()], onElicitation: "accept-all", }); ``` ## Credential providers A connection's value lives in a registered `CredentialProvider`, not a separate secret store. Providers expose `key`, `writable`, `get`, and optional `set`, `delete`, and `list`. Plugin-provided providers (keychain, file-secrets, 1Password, WorkOS Vault) register at startup; inline providers in `config.providers` register first and become the default writable store. ```ts const keys = await executor.providers.list(); const entries = await executor.providers.items(ProviderKey.make("memory")); ``` For production hosts, swap the in-memory map for a durable plugin provider. See [Configure credentials](/configure-credentials). ## Register integrations Each protocol plugin exposes an extension object on the executor. Registration methods write to the integrations catalog and declare auth templates; they do not create callable tools until a connection exists. | Plugin | Extension | Registration method | | --- | --- | --- | | OpenAPI | `executor.openapi` | `addSpec({ slug, spec, baseUrl, authenticationTemplate, ... })` | | GraphQL | `executor.graphql` | `addIntegration({ slug, endpoint, introspectionJson, ... })` | | MCP | `executor.mcp` | `addServer({ slug, transport, endpoint, ... })` | | Google | `executor.google` | `addBundle({ slug, urls, ... })` | OpenAPI auth templates declare where credentials render on each request. Use `variable("token")` as the slot the resolved credential fills: ```ts import { variable } from "@executor-js/plugin-openapi"; await executor.openapi.addSpec({ slug: "inventory", description: "Inventory API", baseUrl: "https://inventory.example.com", spec: { kind: "blob", value: JSON.stringify(openApiDocument) }, authenticationTemplate: [ { slug: "apiKey", type: "apiKey", headers: { "X-API-Key": [variable("token")] }, }, ], }); ``` `executor.integrations.list()`, `executor.integrations.get(slug)`, `executor.integrations.detect(url)`, and `executor.integrations.remove(slug)` operate on the shared catalog regardless of which plugin registered an entry. ## Create connections A connection is the saved credential for one integration, scoped by `(owner, integration, name)`. Creating a connection with an inline `value` writes to the default writable provider and produces the integration's per-connection tool rows. `"org"` for workspace-scoped credentials; `"user"` requires `subject` on the executor. Connection name within the owner and integration (commonly `"default"`). Slug of the registered integration. Which auth method from the integration's `authenticationTemplate` to apply. Inline credential for single-input templates. Written to the default writable provider. ```ts const connection = await executor.connections.create({ owner: "org", name: "default", integration: "inventory", template: "apiKey", value: "inventory-api-key", }); ``` Callable prefix `tools...`. Append `.` for a specific tool address. For OAuth-backed integrations, use `executor.oauth.start` and `executor.oauth.complete` instead of inline `value`. Hosts that serve OAuth must pass `redirectUri` to `createExecutor`. External provider references use `from: { provider, id }` or multi-input `values` / `inputs` maps. See [Connections](/connections) for the full identity model. ## List and inspect tools Tools are persisted per connection at create/refresh time. `tools.list` reads stored rows; it does not dial upstream APIs on every call. ```ts const tools = await executor.tools.list({ integration: "inventory" }); for (const tool of tools) { console.log(`${tool.address}: ${tool.description}`); } ``` ### `ToolListFilter` | Field | Purpose | | --- | --- | | `integration` | Narrow to one integration slug | | `owner` | Filter by `org` or `user` | | `connection` | Filter by connection name | | `query` | Case-insensitive substring on name or description | | `includeAnnotations` | Resolve plugin-derived annotations (default `true`) | | `includeBlocked` | Include tools with effective `block` policy (default `false`) | Inspect input schemas and generated TypeScript previews: ```ts const schema = await executor.tools.schema(tools[0].address); console.log(schema?.inputTypeScript ?? "No input required"); ``` `ToolSchemaView` includes `inputSchema`, `outputSchema`, `schemaDefinitions` for `$ref` resolution, and optional `inputTypeScript` / `outputTypeScript` strings. ## Invoke tools Call `executor.execute` with a `ToolAddress` and arguments matching the tool's input schema. This is the v2 invoke path: the executor resolves the connection credential, enforces effective policy and approval elicitation, then dispatches to the owning plugin's `invokeTool`. ```ts const result = await executor.execute( "tools.inventory.org.default.items__list", {}, ); ``` Full five-segment address from `tools.list`, or a static tool fqid for core-tools entries. JSON-shaped arguments matching the tool input schema. Per-call override of the executor-level elicitation handler. ### Invoke-time behavior | Stage | Behavior | | --- | --- | | Policy resolution | `block` raises `ToolBlockedError`; `require_approval` or `annotations.requiresApproval` triggers an approval elicitation | | Credential resolution | Connection value loaded from the registered provider and rendered through the auth template | | Plugin dispatch | Owning plugin's `invokeTool` builds and sends the upstream request | | Elicitation | Mid-call form or URL requests route through `onElicitation`; `"accept-all"` auto-accepts | Typed failures on the `execute` channel include `ToolNotFoundError`, `ToolInvocationError`, `ToolBlockedError`, `ConnectionNotFoundError`, `CredentialResolutionError`, and `ElicitationDeclinedError`. Promise callers receive these as rejected Promise values. POST and DELETE OpenAPI operations commonly carry `requiresApproval: true` in default annotations. With `onElicitation: "accept-all"`, approval prompts are auto-accepted. Interactive hosts should supply a handler that surfaces approval UI. ## Policies Owner-scoped tool policies are available directly on the embedded executor: ```ts await executor.policies.create({ owner: "org", pattern: "tools.inventory.*", action: "require_approval" }); const effective = await executor.policies.resolve(toolAddress); ``` See [Policies](/policies) and [Manage policies](/manage-policies) for precedence and approval flows. ## Persist across restarts Omitting `db` uses an in-memory FumaDB adapter suitable for scripts and tests. Durable hosts pass a database factory or handle with the executor-owned table set from `collectTables()`. The local daemon (`apps/local`) wires SQLite, runs data migrations, sets `redirectUri` from `EXECUTOR_WEB_BASE_URL`, and enables `coreTools`. ```ts const executor = await createExecutor({ tenant: "my-workspace", subject: "user-123", db: sqliteHandle, plugins, onElicitation: interactiveHandler, redirectUri: new URL("/api/oauth/callback", webBaseUrl).toString(), coreTools: { webBaseUrl }, }); ``` ## Shut down Call `executor.close()` when the process or request scope ends. `close` runs every plugin's `close` hook (for example MCP connection pool teardown) and invokes the database `close` callback when supplied. ```ts await executor.close(); ``` Hosts that wrap the executor in a managed runtime should close on dispose, as `apps/local` does in `createExecutorHandle`. ## End-to-end example The `examples/docs-sdk-quickstart` package walks the full embed flow in under 150 lines: in-memory provider, `openApiPlugin`, `addSpec`, `connections.create`, `tools.list`, `tools.schema`, and `close`. Run it with: ```sh cd examples/docs-sdk-quickstart && bun run start ``` For every published plugin wired together, see `examples/all-plugins` and the [SDK quickstart example](/sdk-quickstart-example) page. ## Related pages `createExecutor` exports, typed IDs, plugin extension typing, promise-mode entry points, and error tags. Line-by-line walkthrough of `examples/docs-sdk-quickstart`. Published protocol and provider plugins and how `examples/all-plugins` composes them. Owner-scoped credential identity, provider routing, and OAuth minting. Tool addresses, discovery, schema inspection, and invocation across surfaces. Durable credential providers, auth templates, and connection payloads. --- ## 15. Deploy self-hosted > Run Executor in Docker or on Cloudflare Workers: image defaults, volume mounts, bootstrap admin env vars, TLS/public-origin requirements, and sandbox network constraints. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/15-deploy-self-hosted.md - Generated: 2026-06-23T19:25:45.544Z ### Source Files - `apps/docs/hosted/docker.mdx` - `apps/docs/hosted/cloudflare.mdx` - `apps/host-selfhost/Dockerfile` - `apps/host-selfhost/docker-compose.yml` - `apps/host-selfhost/executor.config.ts` - `apps/host-cloudflare/wrangler.jsonc` - `apps/host-cloudflare/executor.config.ts` --- title: "Deploy self-hosted" description: "Run Executor in Docker or on Cloudflare Workers: image defaults, volume mounts, bootstrap admin env vars, TLS/public-origin requirements, and sandbox network constraints." --- Executor ships two operator-run runtimes that expose the same surfaces (web UI, HTTP API, streamable-HTTP MCP, QuickJS code execution) without Executor Cloud: a single-container Docker image (`apps/host-selfhost`) and a Cloudflare Worker (`apps/host-cloudflare`). Both are single-tenant, disable stdio MCP spawning (`dangerouslyAllowStdioMCP: false`), and persist encrypted secrets with the encrypted-secrets plugin. The Docker image bundles libSQL (SQLite), Better Auth, QuickJS, and the web SPA in one process. No external database or proxy is required. The Worker bundles D1 storage, R2 blob storage, QuickJS-WASM, and Workers Static Assets for the SPA. Authentication is Cloudflare Access only; there is no in-app login or bootstrap admin flow. | Surface | Docker (`host-selfhost`) | Cloudflare (`host-cloudflare`) | | --- | --- | --- | | Auth | Better Auth (email/password, API keys, MCP OAuth) | Cloudflare Access JWT on every API/MCP request | | Storage | libSQL file under `/data` | D1 + R2 (`executor-blobs`) | | Code execution | QuickJS in-process | QuickJS-WASM in the Worker | | Default port / URL | `4788` (`http://localhost:4788`) | `executor-cloudflare..workers.dev` | | Admin bootstrap | Browser first-run or `EXECUTOR_BOOTSTRAP_ADMIN_*` env vars | `ADMIN_EMAILS` + Access policies | | Public origin var | `EXECUTOR_WEB_BASE_URL` | `VITE_PUBLIC_SITE_URL` (optional) | | Sandbox network opt-in | `EXECUTOR_ALLOW_LOCAL_NETWORK=true` | `ALLOW_LOCAL_NETWORK=true` | ```mermaid flowchart TB subgraph docker["Docker container (host-selfhost)"] SPA_D["Web SPA"] API_D["HTTP API /api/*"] MCP_D["MCP /mcp"] QJS_D["QuickJS executor"] DB_D["libSQL at /data/data.db"] SPA_D --> API_D API_D --> QJS_D MCP_D --> QJS_D API_D --> DB_D end subgraph cf["Cloudflare Worker (host-cloudflare)"] ACCESS["Cloudflare Access"] SPA_C["Static Assets (dist/)"] API_C["Worker /api/*"] MCP_C["Worker /mcp + McpSessionDO"] QJS_C["QuickJS-WASM"] D1["D1 (executor)"] R2["R2 (executor-blobs)"] ACCESS --> SPA_C ACCESS --> API_C ACCESS --> MCP_C API_C --> QJS_C MCP_C --> QJS_C API_C --> D1 API_C --> R2 end ``` ## Docker ```bash title="Published GHCR image" docker run -d \ --name executor-selfhost \ -p 4788:4788 \ -v executor-data:/data \ ghcr.io/rhyssullivan/executor-selfhost:latest ``` ```bash title="Build from a clone (apps/host-selfhost)" docker compose up -d --build ``` Open `http://localhost:4788`. A bare run needs no env vars: the container generates and persists session and encryption keys under `/data` on first boot. The image healthcheck probes `GET /api/health` on port `4788`. ```bash curl -sf http://localhost:4788/api/health ``` Without bootstrap env vars, the first account created in the browser becomes the owner. After that, new users join only through single-use invite links from the **Admin** page. For headless deploys, set both bootstrap variables before start (see [Bootstrap admin](#bootstrap-admin-docker)). ### Image defaults The multi-stage `apps/host-selfhost/Dockerfile` produces a distroless runtime image: | Setting | Default | | --- | --- | | Base runtime | `gcr.io/distroless/cc-debian12` with Bun copied from `oven/bun:1` | | `NODE_ENV` | `production` | | `EXECUTOR_HOST` | `0.0.0.0` (bind all interfaces inside the container) | | `PORT` | `4788` | | `EXECUTOR_DATA_DIR` | `/data` | | Entrypoint | `bun run dist-server/serve.js` | | Published image | `ghcr.io/rhyssullivan/executor-selfhost` (`latest` for stable, `beta` for prereleases) | The local CLI daemon (`executor install`) listens on `17888` by default. The self-hosted Docker image uses `4788`; map the host port accordingly. ### Volume mounts Mount `/data` so the SQLite database and generated keys survive restarts and upgrades: ```bash -v executor-data:/data # named volume (docker-compose default) -v /srv/executor:/data # host path ``` | Path in container | Contents | | --- | --- | | `/data/data.db` | libSQL database (`EXECUTOR_DB_PATH` overrides the file path) | | `/data/auth-secret.key` | Generated `BETTER_AUTH_SECRET` when unset | | `/data/secret.key` | Generated `EXECUTOR_SECRET_KEY` when unset | Back up by snapshotting the volume or copying `/data`. ## Cloudflare Workers From the repo root: ```bash bun install cd apps/host-cloudflare bunx wrangler login ``` ```bash bun run deploy:setup ``` `deploy:setup` (`scripts/deploy.sh`) is idempotent. It: 1. Verifies `wrangler` login 2. Creates or reuses the `executor` D1 database and writes its `database_id` into `wrangler.jsonc` 3. Generates and uploads `EXECUTOR_SECRET_KEY` via `wrangler secret put` if not already set 4. Builds the SPA (`vite build` → `dist/`) 5. Deploys the Worker The script also provisions R2 (`executor-blobs`) and a Durable Object (`McpSessionDO`) per `wrangler.jsonc`. Until the Worker sits behind an Access application, API and MCP routes return `401`. In the Zero Trust dashboard: 1. **Access → Applications → Add an application → Self-hosted** 2. Application domain: `executor-cloudflare..workers.dev` 3. Add an Access policy (for example, emails ending in `@yourcompany.com`) 4. Copy the application **Audience (AUD)** tag, then redeploy: ```bash bunx wrangler deploy \ --var ACCESS_AUD: \ --var ACCESS_TEAM_DOMAIN:.cloudflareaccess.com ``` You can also set `ACCESS_AUD` and `ACCESS_TEAM_DOMAIN` in `wrangler.jsonc` and redeploy. Set `ADMIN_EMAILS` to a comma-separated list of emails that receive the admin role after Access authentication: ```bash bunx wrangler deploy --var ADMIN_EMAILS:admin@example.com,ops@example.com ``` `ENABLE_DEV_AUTH=true` bypasses Access and treats every request as a fixed dev admin. Use only in local `wrangler dev` with `.dev.vars`. Never set it on a deployed Worker that is not already behind Access. ### Worker routing `wrangler.jsonc` serves the built SPA from `./dist` with `single-page-application` fallback. `run_worker_first` routes `/api/*`, `/mcp`, and `/mcp/*` to the Worker; client routes like `/policies` fall through to the SPA. ## Bootstrap admin (Docker) Docker supports two admin paths. Cloudflare has no equivalent: identity and membership come from Access. **Browser first-run (default).** On a fresh instance with no bootstrap env vars, boot creates a single organization with zero members. The first signup through the setup screen claims ownership. **Headless bootstrap.** Set both email and password to pre-create the admin at boot: Email for the bootstrap admin. Must be set together with `EXECUTOR_BOOTSTRAP_ADMIN_PASSWORD`. Password for the bootstrap admin. Must be set together with `EXECUTOR_BOOTSTRAP_ADMIN_EMAIL`. Display name for the bootstrap admin. ```bash docker run -d \ -p 4788:4788 \ -v executor-data:/data \ -e EXECUTOR_BOOTSTRAP_ADMIN_EMAIL=you@example.com \ -e EXECUTOR_BOOTSTRAP_ADMIN_PASSWORD='change-me-to-something-strong' \ -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \ ghcr.io/rhyssullivan/executor-selfhost:latest ``` `BETTER_AUTH_SECRET` and `EXECUTOR_SECRET_KEY` are optional on Docker: when unset, random keys are generated and persisted under `/data`. Set them explicitly to manage rotation and to keep secrets readable if you move the data directory. ## Public origin and TLS Executor builds absolute links for OAuth redirects, MCP OAuth metadata, and connect-card URLs from a configured public origin. It does **not** derive this from the request `Host` header (that would allow host-header injection). ### Docker Public URL browsers use (scheme + host + port). Must exactly match the address loaded in the browser. Behind a reverse proxy or TLS terminator, set `EXECUTOR_WEB_BASE_URL` to the exact public URL (for example `https://executor.example.com`). A mismatch causes Better Auth to reject logins with `403 Invalid origin`. When `EXECUTOR_WEB_BASE_URL` is unset, the resolver checks platform-injected vars (`RAILWAY_PUBLIC_DOMAIN`, `RENDER_EXTERNAL_URL`, `FLY_APP_NAME`, and others) before falling back to `http://localhost:`. ### Cloudflare Optional canonical web base URL. When unset, the Worker derives the origin from each request's URL (Cloudflare-set, not spoofable via `Host`). Set `VITE_PUBLIC_SITE_URL` only when you need a pinned canonical URL, for example behind a proxy that rewrites `Host`. ## Sandbox network constraints Sandboxed code (QuickJS executions and tool calls that use the hosted HTTP client) outbound requests pass through a network guard. By default, local and private addresses are blocked. | Runtime | Opt-in variable | Default | | --- | --- | --- | | Docker | `EXECUTOR_ALLOW_LOCAL_NETWORK` | `false` (unset or any value other than `"true"`) | | Cloudflare | `ALLOW_LOCAL_NETWORK` | `false` | When the guard is active (`allowLocalNetwork: false`), outbound HTTP/HTTPS requests are blocked if they target: - `localhost` or `*.localhost` - Private, loopback, link-local, or multicast IPv4/IPv6 ranges - Cloud metadata hostnames (`metadata.google.internal`, `169.254.169.254`, and similar) - Hostnames that DNS-resolve to any of the above (rebinding protection on Docker) Only `http:` and `https:` protocols are allowed. Set `EXECUTOR_ALLOW_LOCAL_NETWORK=true` or `ALLOW_LOCAL_NETWORK=true` only when you trust the code running in the sandbox and need it to reach internal services. Keep the default off for adversarial or LLM-generated code. ## Environment reference ### Docker | Variable | Default | Purpose | | --- | --- | --- | | `PORT` | `4788` | HTTP listen port | | `EXECUTOR_HOST` | `0.0.0.0` in image; `127.0.0.1` in bare `loadConfig()` | Bind address | | `EXECUTOR_DATA_DIR` | `/data` in image | Data directory for DB and generated keys | | `EXECUTOR_DB_PATH` | `/data.db` | SQLite file path | | `EXECUTOR_WEB_BASE_URL` | platform-detected or `http://localhost:` | Public browser URL | | `BETTER_AUTH_SECRET` | generated in `/data` | Session secret (32+ chars if set explicitly) | | `EXECUTOR_SECRET_KEY` | generated in `/data` | At-rest secret encryption key | | `EXECUTOR_BOOTSTRAP_ADMIN_EMAIL` | unset | Headless admin email | | `EXECUTOR_BOOTSTRAP_ADMIN_PASSWORD` | unset | Headless admin password | | `EXECUTOR_BOOTSTRAP_ADMIN_NAME` | `Admin` | Headless admin display name | | `EXECUTOR_ORG_NAME` | `Default` | Single org display name | | `EXECUTOR_ORG_SLUG` | `default` | URL slug for org-prefixed routes | | `EXECUTOR_ALLOW_LOCAL_NETWORK` | `false` | Allow sandbox code to reach private networks | Copy `apps/host-selfhost/.env.example` to `.env` beside `docker-compose.yml` for optional overrides. ### Cloudflare (`wrangler.jsonc` vars and secrets) | Name | Kind | Purpose | | --- | --- | --- | | `EXECUTOR_SECRET_KEY` | **secret** (`wrangler secret put`) | Required. Encrypts stored secrets at rest in D1 | | `ACCESS_TEAM_DOMAIN` | var | Zero Trust team domain | | `ACCESS_AUD` | var | Access application audience tag | | `ACCESS_NAME_CLAIM` | var | JWT claim for display name (default `name`) | | `ACCESS_GROUPS_CLAIM` | var | JWT claim for groups (default `groups`) | | `ADMIN_EMAILS` | var | Comma-separated admin emails | | `SELF_HOSTED_ORG_ID` | var | Single org id (default `default`) | | `SELF_HOSTED_ORG_NAME` | var | Single org name (default `Default`) | | `SELF_HOSTED_ORG_SLUG` | var | Org URL slug (default `default`) | | `ALLOW_LOCAL_NETWORK` | var | Sandbox private-network opt-in | | `VITE_PUBLIC_SITE_URL` | var | Optional pinned public origin | | `ENABLE_DEV_AUTH` | var | Local dev only; bypasses Access | ## Connect agents and clients Both runtimes expose streamable-HTTP MCP at `/mcp`: - Docker: `http://localhost:4788/mcp` (or your public `EXECUTOR_WEB_BASE_URL` + `/mcp`) - Cloudflare: `https://executor-cloudflare..workers.dev/mcp` (authenticated through Access) See [MCP proxy](/mcp-proxy) for how the endpoint fronts your integrations, and [Connect MCP clients](/connect-mcp-clients) for client wiring. ## Related pages Environment variables, runtime paths, ports, and client overrides across all runtimes. Wire Cursor, Claude Code, and other MCP clients to your self-hosted `/mcp` endpoint. Set up credential providers and connections after the instance is running. How Executor Cloud differs from Docker and Cloudflare self-host deployments. Recovery for port conflicts, invalid-origin errors, OAuth behind proxies, and daemon issues. --- ## 16. Executor Cloud > Hosted Executor Cloud entry points, sign-in flow, shared MCP endpoint usage, and how cloud deployments differ from local daemon and self-host runtimes. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/16-executor-cloud.md - Generated: 2026-06-23T19:26:02.576Z ### Source Files - `apps/docs/hosted/cloud.mdx` - `apps/cloud/package.json` - `apps/cloud/executor.config.ts` - `packages/core/api/src/api.ts` - `e2e/setup/cloud.globalsetup.ts` - `apps/docs/mcp-proxy.mdx` --- title: "Executor Cloud" description: "Hosted Executor Cloud entry points, sign-in flow, shared MCP endpoint usage, and how cloud deployments differ from local daemon and self-host runtimes." --- Executor Cloud is the hosted `apps/cloud` deployment at [https://executor.sh](https://executor.sh): a Cloudflare Worker that serves the web console, the protected `/api/*` HTTP API, and the org-scoped MCP transport on a shared Postgres backend (Hyperdrive), R2 blob storage, and Durable Object MCP sessions. ## Entry points | Surface | URL pattern | Purpose | | --- | --- | --- | | Web console | `https://executor.sh` | Manage integrations, connections, policies, billing, and API keys | | Protected HTTP API | `https://executor.sh/api/*` | Same core API groups as other runtimes: `tools`, `integrations`, `connections`, `providers`, `executions`, `oauth`, `policies` | | MCP transport | `https://executor.sh/mcp` or `https://executor.sh//mcp` | Streamable HTTP MCP endpoint agents connect to | | OAuth discovery | `/.well-known/oauth-protected-resource//mcp`, `/.well-known/oauth-authorization-server` | MCP client OAuth metadata (RFC 9728) | | OpenAPI docs | `https://executor.sh/api/docs` | Swagger UI for the HTTP API | | Billing proxy | `https://executor.sh/api/billing/*` | Autumn subscription and usage endpoints | Org-scoped console routes use `//…` (for example `//policies`, `//api-keys`). Public onboarding routes (`/login`, `/create-org`, `/setup-mcp`) sit outside the org prefix. ```mermaid flowchart TB subgraph clients [Clients] Browser[Web browser] MCP[MCP agents] CLI[executor CLI] end subgraph worker [executor-cloud Worker] Start[start.ts dispatch] App[ExecutorApp.make handler] DO[McpSessionDO] Loader[Dynamic worker loader] end subgraph external [External services] WorkOS[WorkOS AuthKit] PG[(Postgres via Hyperdrive)] R2[(R2 executor-cloud-blobs)] Autumn[Autumn billing] end Browser --> Start MCP --> Start CLI --> Start Start -->|/api/* and /mcp| App App --> DO App --> Loader App --> PG App --> R2 App --> WorkOS App --> Autumn ``` ## Sign in Executor Cloud authenticates users through WorkOS AuthKit. A successful web login sets the `wos-session` sealed-session cookie. The protected `/api/*` plane accepts credentials in this order on the `Authorization` header: a WorkOS device-login JWT (from `executor login`), then a WorkOS API key, then (with no header) the session cookie. ### Web sign-in Go to [https://executor.sh/login](https://executor.sh/login) and click **Sign in**. The page redirects to `/api/auth/login`, which starts the WorkOS hosted AuthKit flow. WorkOS redirects back to `/api/auth/callback` with an authorization code. On success the worker sets `wos-session` and sends you to your `returnTo` path (default: the app shell). If you have no active organization, create one at `/create-org` via `POST /api/auth/create-organization`, or accept a pending invitation from `GET /api/auth/pending-invitations`. Free accounts can belong to up to three organizations unless they hold a paid subscription on another org. Unsigned visitors hitting protected console routes are redirected to `/login` before the SPA loads. OAuth integration callbacks that arrive without a session redirect to login with the callback URL preserved. ### CLI device login The CLI signs into cloud with the OAuth 2.0 Device Authorization Grant (RFC 8628). Discovery comes from `GET /api/auth/cli-login`, which returns WorkOS device and token endpoints plus the public client id. ```bash title="Sign in to cloud" executor login --base-url https://executor.sh ``` ```bash title="Verify the stored profile" executor whoami --server ``` ```bash title="Call the API with stored credentials" executor tools sources --server ``` Origin of the hosted server (for example `https://executor.sh`). Mutually exclusive with `--server`. Named CLI server profile to update. Mutually exclusive with `--base-url`. Profile name to save under. Defaults to the authenticated account email. Print the verification URL instead of opening a browser. The CLI polls the WorkOS token endpoint until you approve the device in the browser, then stores the access (and refresh) token as an `oauth` credential on the profile. Subsequent `executor` commands send `Authorization: Bearer ` to `/api/*`. Device-login JWTs are WorkOS *user_management* tokens verified against the SSO JWKS. MCP OAuth tokens use a separate AuthKit `/oauth2/jwks` keyset. Do not interchange them. ## Connect MCP clients Cloud exposes one shared MCP endpoint per organization. The install card and `/setup-mcp` page build org-pinned URLs: ``` https://executor.sh//mcp ``` The server also accepts the legacy `//mcp` form (`org_…` WorkOS id). Bare `/mcp` resolves the organization from the authenticated token's `org_id` claim. After sign-in, open **Connect** in the org shell or finish onboarding at `/setup-mcp`. The page prints the MCP server URL and an `npx add-mcp` install command for your org slug. Run the generated command (HTTP transport is the default for cloud): ```bash npx add-mcp 'https://executor.sh//mcp' --transport http --name executor ``` Restart the MCP client so it picks up the new server entry. MCP clients authenticate through OAuth against AuthKit (`MCP_AUTHKIT_DOMAIN`, default `https://signin.executor.sh`). Protected-resource metadata is served at `https://executor.sh/.well-known/oauth-protected-resource//mcp`. Optional query parameter `elicitation_mode` controls approval handling: `browser` (web UI), `model` (default resume tool), or `native` (client-native elicitation). Cloud does not support stdio MCP (`executor mcp`). Agents must use streamable HTTP against the hosted `/mcp` path. See [Connect MCP clients](/connect-mcp-clients) for client-specific wiring. ## How cloud differs from other runtimes | Dimension | Executor Cloud | Local daemon (`apps/local`) | Self-host (`apps/host-selfhost`) | | --- | --- | --- | --- | | Hosting | Managed Worker at `executor.sh` | Background service on your machine | Your infrastructure (Docker, etc.) | | Identity | WorkOS AuthKit (multi-tenant orgs) | Local scope, no hosted login | Better Auth (single configured org) | | Database | Postgres via Hyperdrive | Local SQLite / scope storage | libSQL file in `EXECUTOR_DATA_DIR` | | MCP sessions | Durable Object (`McpSessionDO`) | In-process | In-process | | Code execution | Cloudflare dynamic worker loader | QuickJS in-process | QuickJS in-process | | MCP URL | `https://executor.sh//mcp` | `http://localhost:/mcp` or `executor mcp` stdio | `https:///mcp` | | Stdio MCP | Disabled (`dangerouslyAllowStdioMCP: false`) | Enabled | Disabled | | Secret providers | WorkOS Vault plugin | Keychain, file secrets, 1Password | Encrypted DB secrets plugin | | Billing | Autumn metering and seat gates | None | None | | CLI login provider | WorkOS (`provider: "workos"` from `/api/auth/cli-login`) | N/A (local profile) | Better Auth | The core HTTP API shape is identical across runtimes (`CoreExecutorApi` groups). Cloud adds auth, org, billing, and MCP-session extensions on top of the shared `ExecutorApp.make` assembly. ### Plugin set Cloud ships only plugins safe in a multi-tenant Worker: OpenAPI, Google, Microsoft, GraphQL, HTTP MCP, and WorkOS Vault. It excludes local-only credential backends (keychain, file secrets, 1Password) and blocks stdio MCP process spawning. ```ts // apps/cloud/executor.config.ts (abbreviated) mcpHttpPlugin({ dangerouslyAllowStdioMCP: false }), workosVaultPlugin({ credentials: workosCredentials ?? { apiKey: "", clientId: "" } }), ``` Local adds desktop settings and OS credential plugins; self-host swaps WorkOS Vault for `encryptedSecretsPlugin`. ## API authentication reference :::endpoint GET /api/auth/cli-login CLI device-login discovery. Returns WorkOS device authorization and token endpoints plus `clientId`. No authentication required. ::: :::endpoint GET /api/auth/login Starts the WorkOS hosted login redirect. Optional `returnTo` query param (same-origin relative path). ::: :::endpoint GET /api/auth/callback OAuth callback from WorkOS. Sets `wos-session` on success. ::: :::endpoint GET /api/auth/me Returns the signed-in user and active organization. Requires session or bearer credentials. ::: For programmatic access without the CLI device flow, mint a WorkOS API key from the org **API keys** page (`//api-keys`) and send `Authorization: Bearer ` to `/api/*`. API keys take precedence over the session cookie when both are present. MCP accepts the same bearer forms plus MCP OAuth access tokens verified against AuthKit JWKS. ## Plans and limits Free organizations include up to three members and 10,000 executions per month, with pay-as-you-go overage. Free accounts without a paid org subscription can create up to three organizations. Team and Enterprise plans lift member and execution limits. Billing routes live under `/api/billing/*` and the console **Billing** pages (`//billing`). ## Operations notes Production deploys with `bun run deploy` from `apps/cloud` (build + `wrangler deploy`). The Worker binds: - `HYPERDRIVE` to Postgres - `BLOBS` to the `executor-cloud-blobs` R2 bucket - `MCP_SESSION` to the `McpSessionDO` Durable Object class - `LOADER` for sandboxed code execution - `MARKETING` service for apex marketing pages `VITE_PUBLIC_SITE_URL` is `https://executor.sh`. `ALLOW_LOCAL_NETWORK` defaults unset (`false`), blocking sandboxed code from reaching private networks. Do not point MCP clients at bare `/mcp` when you need a specific organization unless the token already carries the correct `org_id`. Prefer the org-slug URL the console prints. ## Related pages How Executor fronts OpenAPI, GraphQL, and upstream MCP with one endpoint, shared auth, and per-tool policies. Wire Cursor, Claude Code, and other agents via HTTP or stdio, including `add-mcp` setup. `login`, `logout`, `whoami`, `mcp`, `call`, and server profile flags. Run Executor on Docker or Cloudflare Workers when you need your own infrastructure. Connection payloads, OAuth flows, and credential provider options across runtimes. Route groups, payloads, and error shapes for the protected API. --- ## 17. CLI reference > All `executor` subcommands and flags: `install`, `web`, `daemon`, `service`, `mcp`, `call`, `resume`, `tools`, `server`, `login`, and auto-start behavior. - Page Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/pages/17-cli-reference.md - Generated: 2026-06-23T19:26:51.492Z ### Source Files - `apps/cli/src/main.ts` - `apps/cli/bin/executor.ts` - `apps/cli/src/daemon.ts` - `apps/cli/src/daemon-state.ts` - `apps/cli/src/service.ts` - `apps/cli/src/server-profile.ts` - `README.md` --- title: "CLI reference" description: "All `executor` subcommands and flags: `install`, `web`, `daemon`, `service`, `mcp`, `call`, `resume`, `tools`, `server`, `login`, and auto-start behavior." --- The `executor` binary (`apps/cli/bin/executor.ts`) is the local entry point for installing a background service, opening the web UI, managing the daemon, invoking tools, resuming paused executions, exposing an MCP stdio server, and targeting hosted or local HTTP APIs. Commands are defined in `apps/cli/src/main.ts` using Effect CLI. Default local daemon port is **4788**; the OS-supervised service defaults to **4789**. ## Command overview | Command | Purpose | | --- | --- | | `executor install` | Install and start the OS-supervised background service | | `executor web` | Open the running web UI (or start a temporary foreground server) | | `executor open` | Open the running web app in the browser with `?_token=` pre-filled | | `executor daemon` | Run, stop, restart, or inspect the local daemon | | `executor service` | Install, uninstall, restart, or inspect the OS-supervised service | | `executor mcp` | Start an MCP server over stdio | | `executor call` | Invoke a tool by dot-separated path segments | | `executor resume` | Resume a paused execution (auth or approval) | | `executor tools` | Search, list sources, or describe tools | | `executor server` | Manage named server connection profiles | | `executor login` | Sign in to a hosted server via OAuth device flow | | `executor logout` | Clear stored credentials for a server profile | | `executor whoami` | Show the authenticated account for a server | ## Global options Print the CLI version and exit. Defined in `apps/cli/package.json` (currently `1.5.18`). When set to `debug`, `trace`, or `all`, error output includes full stack traces. Otherwise errors are normalized to a short message with a hint to re-run with `--log-level debug`. ## Shared server targeting flags Several commands accept these flags to choose which Executor HTTP server to talk to: Executor server origin (for example `http://localhost:4788` or `https://cloud.example.com`). For local `http://` origins without stored credentials, the CLI may auto-start a daemon. Mutually exclusive with `--server`. Named server profile from `~/.executor/server-connections.json`. Mutually exclusive with `--base-url`. Path to a workspace directory containing `executor.jsonc`. Sets `EXECUTOR_SCOPE_DIR` for the command. **Server resolution order** (when neither flag is passed): 1. Default server profile (if configured) 2. Active local server manifest (`~/.executor/server-control/server.json`) 3. Implicit default `http://localhost:4788` Environment fallbacks for bearer auth when a profile has no stored credential: - `EXECUTOR_API_KEY` (hosted API key) - `EXECUTOR_AUTH_TOKEN` (local/desktop bearer token) ## `executor install` Installs Executor as an OS-supervised background service. Alias of `executor service install`. ```bash executor install [--port ] ``` Loopback port the supervised daemon binds. Clients discover the live port from `server.json`. **Behavior:** - Registers a service with the OS manager: **launchd** (macOS), **systemd --user** (Linux), or **Windows Task Scheduler** (Windows). - Runs ` daemon run --foreground --port --hostname 127.0.0.1`. - Waits up to 45 seconds for a reachable `cli-daemon` manifest at `http://127.0.0.1:`. - Idempotent: if the same version, port, and executable are already running, prints a noop message. - **Requires the compiled binary** in production. In a dev checkout (`bun run src/main.ts`), fails with a message to use `executor daemon run --foreground` instead. ```bash executor install executor install --port 4789 ``` After install, open the UI with `executor web` or `executor open`. ## `executor service` Manages the same OS-supervised daemon as `install`, with explicit lifecycle commands. | Subcommand | Description | | --- | --- | | `service install [--port ]` | Same as `executor install` | | `service uninstall` | Stop and remove the OS service registration | | `service status` | Show platform, registration, running state, serving origin, and version drift | | `service restart` | Restart via the OS manager (`launchctl kickstart`, `systemctl --user restart`, or Task Scheduler) | Service label: `sh.executor.daemon`. Logs: `~/.executor/logs/daemon.log` and `daemon.error.log`. On Windows, `service install` may require an **Administrator** PowerShell because boot-triggered Scheduled Tasks need elevation. ## `executor web` Opens the Executor web UI. ```bash executor web [--foreground] [--port ] [--hostname ] [--allowed-host ...] [--auth-token ] [--scope ] ``` **Default (no `--foreground`):** reads the active local server manifest and opens the browser to `{origin}/?_token={bearer}`. If nothing is running, prints install instructions. **With `--foreground`:** starts a temporary in-process server, publishes a `foreground` manifest, and blocks until Ctrl+C. Run a temporary web server in the current terminal instead of opening the installed background service. Port for the `--foreground` server. Bind address for `--foreground`. Use `0.0.0.0` to listen on all interfaces (only on trusted networks). Grant an extra CORS origin for `--foreground`. Localhost is always allowed; bearer token is the access gate. Override the bearer token for `--foreground`. Defaults to the stable token in `auth.json`. ```bash executor web executor web --foreground executor web --foreground --port 4788 --hostname 0.0.0.0 ``` ## `executor open` Same browser-open behavior as `executor web` without `--foreground`: reads `server.json`, prints the URL, and opens `{origin}/?_token={token}`. ## `executor daemon` Manages the local Executor HTTP daemon (distinct from the OS-supervised service, though both run `daemon run` under the hood). | Subcommand | Description | | --- | --- | | `daemon run` | Start the daemon (background by default) | | `daemon status [--base-url ]` | Show running state, PID, and scope | | `daemon stop [--base-url ]` | SIGTERM the recorded PID and clean up state files | | `daemon restart [--base-url ] [--scope ]` | Stop then ensure the daemon is reachable again | ### `daemon run` flags Preferred listen port. If busy, an ephemeral port is chosen and reported on stderr. Bind address. Keep local unless you trust the network. Run in the current process (used by OS service managers). Without it, spawns a detached child. Extra CORS origins (repeatable). Override bearer token; defaults to `auth.json` under `EXECUTOR_DATA_DIR`. **State files** (under `EXECUTOR_DATA_DIR`, default `~/.executor`): - `daemon-{host}-{port}.json` — PID record for a specific port - `daemon-active-{host}-{scope-hash}.json` — scope-scoped pointer with token - `server-control/server.json` — active server manifest with bearer token (mode `0600`) ```bash executor daemon run executor daemon run --foreground --port 4788 executor daemon status executor daemon stop executor daemon restart ``` ## `executor mcp` Starts an MCP server over stdio for Cursor, Claude Code, OpenCode, and other MCP clients. ```bash executor mcp [--scope ] [--elicitation-mode browser|model] ``` `browser`: approval pauses open `{baseUrl}/resume/{executionId}` in the browser. `model`: exposes a CLI resume tool to the model. **Behavior:** - Acquires a local server startup lock, picks an available port (preferred 4788), and starts an in-process server. - Reroutes stdout to stderr so JSON-RPC on stdout stays clean. - Publishes a `foreground` manifest for the MCP session. - Stops the server when the MCP session ends. Example MCP client config: `"command": "executor", "args": ["mcp"]`. See [Connect MCP clients](/connect-mcp-clients). ## `executor call` Invokes a tool by dot-separated path segments. The CLI compiles the path and trailing JSON args into TypeScript, executes it via the `/executions/execute` API, and prints the result. ```bash executor call [ ...] ['{"key":"value"}'] ``` ### Browse mode (`--help`) ```bash executor call --help [--match ""] [--limit ] [--base-url ] [--server ] [--scope ] ``` `--match` filters large namespaces; `--limit` caps listed subcommands. ```bash executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}' executor call github --help executor call cloudflare --help --match dns --limit 20 ``` **Paused executions:** when a call pauses for auth or approval, the CLI prints the execution ID, a browser approval URL, and suggested `executor resume` commands. ## `executor resume` Resumes a paused execution. ```bash executor resume --execution-id [--action accept|decline|cancel] [--content ''] [--base-url ] [--server ] [--scope ] ``` Execution ID from a paused `call` or MCP elicitation. `accept`, `decline`, or `cancel`. JSON object payload when `--action accept` and the pause requested form input. ```bash executor resume --execution-id exec_abc123 executor resume --execution-id exec_abc123 --action accept --content '{"approved":true}' executor resume --execution-id exec_abc123 --action decline ``` ## `executor tools` | Subcommand | Description | | --- | --- | | `tools search [--namespace ] [--limit ]` | Search tools by natural-language query (default limit 12) | | `tools sources [--query ] [--limit ]` | List configured sources and tool counts (default limit 50) | | `tools describe ` | Show a tool's TypeScript and JSON schema | All `tools` subcommands accept `--base-url`, `--server`, and `--scope`, and auto-start a local daemon when needed. ```bash executor tools search "send email" executor tools sources executor tools describe github.issues.list ``` ## `executor server` Manages named connection profiles in `~/.executor/server-connections.json`. | Subcommand | Description | | --- | --- | | `server add [--display-name