Skip to content

Commit 6b186bf

Browse files
RhysSullivanRhysSullivan
authored
docs: rewrite README (#1187)
1 parent 1e63315 commit 6b186bf

1 file changed

Lines changed: 156 additions & 87 deletions

File tree

‎README.md‎

Lines changed: 156 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,108 @@
1-
# executor
1+
# Executor
22

3-
[https://github.com/user-attachments/assets/11225f83-e848-42ba-99b2-a993bcc88dad](https://github.com/user-attachments/assets/11225f83-e848-42ba-99b2-a993bcc88dad)
3+
**Connect any agent to everything.**
44

5-
The integration layer for AI agents. One catalog for every tool, shared across every agent you use.
5+
Executor is an open-source integration layer for AI agents. Configure every
6+
integration once (MCP servers, OpenAPI specs, GraphQL APIs) with authentication
7+
and per-tool policies, then use that one catalog from any MCP-compatible agent.
68

7-
[Ask DeepWiki](https://deepwiki.com/RhysSullivan/executor)
9+
[Website](https://executor.sh) · [Documentation](https://executor.sh/docs) · [Discord](https://discord.gg/eF29HBHwM6) · Backed by Y Combinator
810

9-
## Quick start
11+
[https://github.com/user-attachments/assets/11225f83-e848-42ba-99b2-a993bcc88dad](https://github.com/user-attachments/assets/11225f83-e848-42ba-99b2-a993bcc88dad)
1012

11-
```bash
12-
npm install -g executor
13-
executor install
14-
executor web
15-
```
13+
## Why Executor
1614

17-
This installs the local background service and opens the web UI. From there, add your first source and start using tools.
15+
Every agent you use (Claude Code, Cursor, ChatGPT, and the rest) needs its own
16+
copy of every integration: the same API keys pasted in three places, the same
17+
MCP servers wired up again, no shared idea of what each tool is allowed to do.
1818

19-
### Use as an MCP server
19+
Executor is the layer in between. Add a tool once, give it credentials once,
20+
set its policy once, and every agent shares it over MCP. Your integrations,
21+
auth, and policies live in one place instead of being scattered across each
22+
client.
2023

21-
Point any MCP-compatible agent (Cursor, Claude Code, OpenCode, etc.) at Executor to share your tool catalog, auth, and policies across all of them.
24+
- **Any source.** First-party support for MCP servers, OpenAPI, GraphQL, and
25+
Google Discovery. If you can describe it with a JSON schema, it can be an
26+
integration. The plugin system is open to any source type.
27+
- **One catalog, every agent.** Anything MCP-compatible connects to the same
28+
set of tools.
29+
- **Governed by policy.** Each tool is allowed, gated behind approval, or
30+
blocked, with sensible defaults derived from the spec.
31+
- **Run it your way.** Local CLI, a desktop app, hosted Executor Cloud, or
32+
self-hosted on Docker or Cloudflare. Same functionality, different packaging.
2233

23-
```bash
34+
## How it works
2435

25-
executor mcp
26-
```
36+
1. **Add an integration**: an MCP server, an OpenAPI spec, or a GraphQL API.
37+
2. **Create a connection**: one configured (optionally authenticated) instance
38+
of that integration. An integration can have many connections.
39+
3. **Set policies**: decide whether each tool is always allowed, needs
40+
approval, or is blocked.
41+
4. **Point your agents at Executor** over MCP. They all share the same catalog.
2742

28-
Example `mcp.json` for Claude Code / Cursor:
29-
30-
```json
31-
{
32-
"mcpServers": {
33-
"executor": {
34-
"command": "executor",
35-
"args": ["mcp"]
36-
}
37-
}
38-
}
39-
```
43+
See [Concepts](https://executor.sh/docs/concepts/integrations) for the full model.
44+
45+
## Quick start
4046

41-
### Use with Pi
47+
The fastest path is **[Executor Cloud](https://executor.sh)**: sign in, add an
48+
integration, and point your agents at the hosted MCP endpoint. Nothing to
49+
install.
4250

43-
[Pi](https://pi.dev) does not include a built-in MCP client. To use Executor from Pi, install the community bridge:
51+
To run it locally instead (Node.js 20+):
4452

4553
```bash
46-
pi install git:github.com/gvkhosla/pi-executor-mcp@v0.2.0
54+
npm install -g executor # or: pnpm add -g / bun add -g / yarn global add
55+
executor install # install the durable background service
56+
executor web # open the web UI in your browser
4757
```
4858

49-
Reload Pi, then verify the bridge:
59+
`executor install` keeps the service running across restarts. For a throwaway
60+
foreground runtime, use `executor web --foreground`. From the web UI, add your
61+
first integration and connect an agent.
5062

51-
```text
52-
/reload
53-
/executor-status
54-
```
63+
### Set up with your agent
64+
65+
Prefer to let your coding agent do the setup? Copy the
66+
[setup prompt from the docs](https://executor.sh/docs) and paste it into Claude,
67+
Cursor, or any MCP-capable agent. It will help you pick how to run Executor,
68+
install it, connect over MCP, and get your first integration working end to end.
69+
70+
## Ways to run
71+
72+
Every form exposes the same functionality, just packaged differently.
5573

56-
After that, ask Pi to search, inspect, and call tools through Executor.
74+
| Form | Best for | Docs |
75+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
76+
| **Executor Cloud** | The fastest start. Use it from many agents (including cloud agents like ChatGPT) with nothing running locally. Free tier. | [Cloud](https://executor.sh/docs/hosted/cloud) |
77+
| **CLI** | A headless or server environment. Runs a local background service. | [CLI](https://executor.sh/docs/local/cli) |
78+
| **Desktop app** | A regular desktop (Mac, Windows, Linux). The same runtime, as a native app. | [Desktop](https://executor.sh/docs/local/desktop) |
79+
| **Self-host (Docker)** | Your own infrastructure, full control. | [Docker](https://executor.sh/docs/hosted/docker) |
80+
| **Self-host (Cloudflare)** | Deploy as a Cloudflare Worker. | [Cloudflare](https://executor.sh/docs/hosted/cloudflare) |
5781

58-
## Add a source
82+
## Connect an agent over MCP
5983

60-
If you can represent it with a JSON schema, it can be an integration. Executor has first-party support for OpenAPI, GraphQL, MCP, and Google Discovery — but the plugin system is open to any source type.
84+
Add Executor to any MCP client (Claude Code, Cursor, OpenCode) with
85+
[`add-mcp`](https://www.npmjs.com/package/add-mcp), which detects the client and
86+
writes its config for you:
87+
88+
```bash
89+
# Over HTTP (the running service serves a streamable-HTTP endpoint)
90+
npx add-mcp http://127.0.0.1:4788/mcp --transport http --name executor
91+
92+
# Or over stdio, with the executor CLI on your PATH
93+
npx add-mcp "executor mcp" --name executor
94+
```
6195

62-
### Via the web UI
96+
The **Connect** card in the web UI shows the exact command (and port, if it
97+
differs) already filled in. Most MCP clients only load servers at startup, so
98+
you may need to restart the client or open a new chat before the Executor tools
99+
appear.
63100

64-
Run `executor web`, go to **Add Source**, paste a URL, and Executor will detect the type, index the tools, and handle auth.
101+
## Add an integration
65102

66-
### Via the CLI
103+
From the web UI, click **Add Source**, paste an OpenAPI, GraphQL, or MCP URL,
104+
and Executor detects the type, indexes the tools, and handles auth. Or add one
105+
from the CLI:
67106

68107
```bash
69108
executor call executor openapi addSource '{
@@ -73,51 +112,48 @@ executor call executor openapi addSource '{
73112
}'
74113
```
75114

76-
Use `baseUrl` when the OpenAPI document has relative `servers` entries (for example `"/api/v3"`).
115+
Use `baseUrl` when the OpenAPI document has relative `servers` entries (for
116+
example `"/api/v3"`). Confirm it is live with `executor tools sources`.
77117

78-
## Use tools
118+
## Using tools
79119

80-
Agents discover and call tools through a typed TypeScript runtime:
120+
### From the CLI
81121

82-
```ts
83-
// discover by intent
84-
const matches = await tools.discover({ query: "github issues", limit: 5 });
85-
86-
// inspect the schema
87-
const detail = await tools.describe.tool({
88-
path: matches.bestPath,
89-
includeSchemas: true,
90-
});
91-
92-
// call with type safety
93-
const issues = await tools.github.issues.list({
94-
owner: "vercel",
95-
repo: "next.js",
96-
});
122+
```bash
123+
executor tools search "send email" # find tools by intent
124+
executor call github issues --help # browse a namespace
125+
executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
97126
```
98127

99-
Use tools via the CLI:
128+
`executor call`, `executor resume`, and `executor tools ...` auto-start the
129+
local daemon if needed, and pick a free port if the default is busy. If an
130+
execution pauses for auth or approval, resume it:
100131

101132
```bash
102-
executor tools search "send email"
103-
executor call --help
104-
executor call github --help
105-
executor call github issues --help
106-
executor call cloudflare --help --match dns --limit 20
107-
executor call github issues create '{"owner":"octocat","repo":"Hello-World","title":"Hi"}'
108-
executor call gmail send '{"to":"alice@example.com","subject":"Hi"}'
133+
executor resume --execution-id exec_123
109134
```
110135

111-
`executor call`, `executor resume`, and `executor tools ...` commands auto-start a local daemon if needed.
112-
If the default port is busy, the CLI will pick an available local port and track it automatically.
136+
### From your own code
113137

114-
If an execution pauses for auth or approval, resume it:
138+
Embed Executor with the TypeScript SDK (a Promise API; an Effect-native API is
139+
also available):
115140

116-
```bash
117-
executor resume --execution-id exec_123
141+
```ts
142+
import { createExecutor } from "@executor-js/sdk/promise";
143+
import { openApiPlugin } from "@executor-js/plugin-openapi/promise";
144+
145+
const executor = await createExecutor({ plugins: [openApiPlugin()] });
146+
147+
// add an integration, create a connection, then list and call tools
148+
const tools = await executor.tools.list({ integration: "inventory" });
149+
const schema = await executor.tools.schema(tools[0].address);
150+
151+
await executor.close();
118152
```
119153

120-
## CLI reference
154+
See [`examples/`](examples) for runnable end-to-end scripts.
155+
156+
### CLI reference
121157

122158
```bash
123159
executor install # install/start the durable background service
@@ -127,7 +163,7 @@ executor daemon run # start persistent local daemon in backgroun
127163
executor daemon status # show daemon status
128164
executor daemon stop # stop daemon
129165
executor daemon restart # restart daemon
130-
executor mcp # start MCP endpoint
166+
executor mcp # start MCP endpoint (stdio)
131167
executor call <path...> '{"k":"v"}' # invoke a tool by path segments
132168
executor call <path...> --help # browse namespaces/resources/methods
133169
executor call <path...> --help --match "<text>" --limit <n> # narrow huge namespaces
@@ -137,14 +173,44 @@ executor tools sources # list configured sources + tool counts
137173
executor tools describe <path> # show tool TypeScript/JSON schema
138174
```
139175

140-
## Developing locally
176+
## Project layout
177+
178+
Executor is a Bun + Turborepo monorepo.
179+
180+
```
181+
apps/
182+
cli/ the `executor` CLI and local background service
183+
desktop/ the desktop app (Mac, Windows, Linux)
184+
local/ the local runtime shared by the CLI and desktop
185+
cloud/ Executor Cloud (the hosted product)
186+
host-selfhost/ self-hosted server (Docker)
187+
host-cloudflare/ Cloudflare Worker deployment
188+
marketing/ the executor.sh site
189+
docs/ the docs at executor.sh/docs
190+
packages/
191+
core/ contracts, plugin wiring, scopes, policies, SDK, API, CLI core
192+
kernel/ execution runtimes (QuickJS, Deno subprocess, dynamic worker)
193+
plugins/ source and provider plugins (openapi, graphql, mcp, google,
194+
microsoft, 1password, keychain, encrypted/file secrets, ...)
195+
hosts/ host adapters (MCP surface, Cloudflare)
196+
react/ shared React UI
197+
app/ the web app UI
198+
examples/ runnable SDK examples
199+
e2e/ full-stack end-to-end tests
200+
```
201+
202+
## Develop locally
141203

142204
```bash
143205
bun install
144-
bun dev
206+
bun run bootstrap # idempotent: install deps, build required artifacts, fetch Playwright
207+
bun run dev # start the dev servers (defaults to http://127.0.0.1:4788)
145208
```
146209

147-
The dev server starts at `http://127.0.0.1:4788`.
210+
`bun run bootstrap` is required in a fresh checkout: its build step produces
211+
artifacts the dev servers fail without. See [RUNNING.md](RUNNING.md) for dev
212+
servers, ports, and environment gotchas, and [AGENTS.md](AGENTS.md) for the
213+
contributor contract.
148214

149215
### Tests
150216

@@ -158,27 +224,30 @@ The browser e2e scenarios need Playwright's Chromium once per machine:
158224

159225
## Community
160226

161-
Join the Discord: [https://discord.gg/eF29HBHwM6](https://discord.gg/eF29HBHwM6)
227+
Join the [Discord](https://discord.gg/eF29HBHwM6). To learn more, visit
228+
[executor.sh](https://executor.sh) or [Ask DeepWiki](https://deepwiki.com/RhysSullivan/executor).
162229

163-
## Learn more
230+
## License
164231

165-
Visit [executor.sh](https://executor.sh) to learn more.
232+
[MIT](LICENSE)
166233

167234
## Attribution
168235

169-
- Thank you to [Crystian](https://www.linkedin.com/in/crystian/) for providing the npm package name `executor`.
236+
- Thank you to [Crystian](https://www.linkedin.com/in/crystian/) for providing
237+
the npm package name `executor`.
170238

171239
## References
172240

173-
As part of my coding process, I give my agent access to references to other codebases to understand patterns and how other people have implemented systems.
174-
175-
A non exhaustive list of references are:
241+
As part of my coding process, I give my agent access to references to other
242+
codebases to understand patterns and how other people have implemented systems.
243+
A non-exhaustive list:
176244

177-
- [Better Auth](https://github.com/better-auth/better-auth) - Storage adapter reference
245+
- [FumaDB](https://github.com/fuma-nama/fumadb) - Storage adapter reference
178246
- [Effect](https://github.com/Effect-TS/effect) - General code patterns
179247
- [OpenCode](https://github.com/anomalyco/opencode) - Plugin system reference
180248
- [OpenClaw](https://github.com/openclaw/openclaw) - Plugin system reference
181249
- [Emdash](https://github.com/emdash-cms/emdash) - Plugin system reference
182250
- [Pi](https://github.com/badlogic/pi-mono) - Plugin system reference
183251

184-
It's encouraged also that you can use this codebase as a reference to understand how it's implemented
252+
You are also encouraged to use this codebase as a reference to understand how it
253+
is implemented.

0 commit comments

Comments
 (0)