The Executor monorepo provides a set of high-level SDKs designed for embedding tool execution capabilities directly into user applications. While the internal architecture is built on the Effect ecosystem, the Developer SDKs provide a standard Promise-based interface that abstracts away the underlying functional complexity.
The primary entry point for developers is the @executor-js/sdk package. It allows for the creation of an Executor instance that can discover, manage, and invoke tools across various protocols (OpenAPI, GraphQL, MCP) using a unified interface.
The SDK is designed to be "Effect-agnostic" at the surface level. By using createExecutor from the @executor-js/sdk/promise entry point, developers interact with standard JavaScript Promises and simple configuration objects.
invoke method.CredentialProvider implementations (e.g., Keychain, 1Password, or environment variables).openApiHttpPlugin to support REST APIs).For details, see Promise SDK.
To facilitate the discovery of available integrations without hardcoding specifications, Executor provides an Integrations Registry. This system allows applications to fetch a remote catalog of verified integrations (the "IR" or Intermediate Representation format).
DO_NOT_TRACK and EXECUTOR_DISABLE_INTEGRATIONS_FETCH environment variables to restrict outbound registry requests.For details, see Integrations Registry.
The monorepo includes several reference implementations to demonstrate SDK usage:
Located in examples/docs-sdk-quickstart, this example demonstrates the minimal setup required to:
Sources:
Located in examples/all-plugins, this is a comprehensive demonstration of an Executor instance configured with the full suite of available plugins, including secret management and specialized protocols.
| Plugin Type | Package Reference |
|---|---|
| Protocols | plugin-openapi, plugin-graphql, plugin-mcp, plugin-google |
| Secrets | plugin-keychain, plugin-file-secrets, plugin-onepassword, plugin-workos-vault |
Sources:
The following diagrams illustrate how natural language concepts map to specific code entities within the Developer SDK.
This diagram bridges the gap between a user's intent to "run a tool" and the internal ExecutionEngine.
Sources:
makeTestExecutor factory logic)defineExecutorConfig and plugin composition)This diagram shows how a request for "Auth" maps to specific CredentialProvider entities.
Sources:
workosVaultPlugin integration)The SDK provides a robust testing harness in @executor-js/sdk/testing to help developers write integration tests for their toolkits.
makeTestExecutor: Creates an in-memory executor instance pre-configured for testing.OAuthTestServer: A mock server for testing OAuth2 flows without hitting real providers.serveTestHttpApp: A utility to spin up local HTTP servers for mocking API responses.Sources:
serveTestHttpApp in GraphQL tests)When embedding the SDK in a hosted environment (like a Cloudflare Worker), security is enforced via the HostedHttpClient. This utility ensures that tools cannot be used to perform SSRF (Server-Side Request Forgery) attacks by validating outbound URLs against private network ranges.
Sources:
validateHostedOutboundUrl)Refresh this wiki