The Executor project provides two primary multi-user host distributions: a self-hosted Docker-ready application (apps/host-selfhost) and a Cloudflare Workers variant (apps/host-cloudflare). Both hosts extend the core SDK and API layer to support multi-tenancy, centralized authentication, and persistence while maintaining strict scope isolation between users and organizations.
The self-hosted distribution is a unified Bun-based application that bundles the React SPA, a libSQL (SQLite) database, and the Executor API into a single container image.
Self-host uses better-auth for identity management, supporting email/password sign-in, personal API keys, and RFC 8628 device authorization for the CLI apps/host-selfhost/src/auth/better-auth.ts112-117
A critical implementation detail is the "one connection, two schema regions" strategy. The SelfHostDb handle is shared between the Executor's FumaDB tables and the better-auth Kysely adapter apps/host-selfhost/src/auth/better-auth.ts32-48 This prevents data loss bugs associated with multiple connections competing for WAL inodes in SQLite apps/host-selfhost/src/auth/better-auth.ts41-52
Multi-tenancy is achieved by mapping the better-auth session to the Executor's Tenant and Subject model:
organizationId from the session apps/host-selfhost/src/auth/better-auth.ts113userId acting within that tenant.Isolation is verified through concurrent request testing, ensuring that requests with distinct identities receive disjoint executor bindings apps/host-selfhost/src/scope-isolation.test.ts100-115
To support standard Model Context Protocol (MCP) clients that expect stable URLs, the self-host application implements "org-path" routing. It rewrites URLs like /<organizationId>/mcp to a bare /mcp route internally while preserving the original path in the X-Executor-Mcp-Original-Path header apps/host-selfhost/src/serve.ts41-49
Identity and Scope Resolution Flow
Sources: apps/host-selfhost/src/auth/better-auth.ts29-62 apps/host-selfhost/src/serve.ts50-92 apps/host-selfhost/src/scope-isolation.test.ts10-15
The self-host environment is configured via loadConfig, which prioritizes environment variables like EXECUTOR_DATA_DIR and BETTER_AUTH_SECRET apps/host-selfhost/src/config.ts1-15
The vite.config.ts for self-host uses a specialized executorVitePlugin to feed plugin client bundles into the SPA apps/host-selfhost/vite.config.ts27-28 In development, it proxies API, MCP, and documentation requests to an in-process Effect handler using makeSelfHostApiHandler apps/host-selfhost/vite.config.ts48-60
Because the host relies on native binaries (specifically libSQL and QuickJS), the package-runtime.ts script dynamically maps the correct native package based on the build platform (e.g., linux-arm64-gnu vs linux-x64-gnu) apps/host-selfhost/scripts/package-runtime.ts19-36
| Component | Implementation |
|---|---|
| HTTP Server | BunHttpServer via @effect/platform-bun apps/host-selfhost/src/serve.ts26 |
| Database | libSQL (SQLite) with WAL mode apps/host-selfhost/src/auth/better-auth.ts48 |
| Auth | better-auth with organization and apiKey plugins apps/host-selfhost/src/auth/better-auth.ts113-115 |
| Static Assets | Served with immutable cache headers for hashed assets apps/host-selfhost/src/serve.ts111-115 |
Sources: apps/host-selfhost/vite.config.ts48-109 apps/host-selfhost/scripts/package-runtime.ts10-47 apps/host-selfhost/src/serve.ts111-129
The host-cloudflare variant is optimized for the Cloudflare Workers runtime. It utilizes specialized infrastructure to handle state and high-performance database access.
AgentSessionDurableObject) and tracking execution owners (ExecutionOwnerDirectory) packages/hosts/cloudflare/package.json15-22Cloud Entity Space Mapping
Sources: packages/hosts/cloudflare/package.json6-27 apps/host-selfhost/src/app.ts29-33
The monorepo includes an ephemeral preview system for testing host variants in CI. This is managed by preview.ts and GitHub Actions.
docker build before being published to ghcr.io RELEASING.md62-63latest and beta tags for both NPM packages and Docker images RELEASING.md27-31Sources: RELEASING.md13-31 RELEASING.md62-63
Refresh this wiki