# 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.

- Repository: RhysSullivan/executor
- GitHub: https://github.com/RhysSullivan/executor
- Human docs: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052
- Complete Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/llms-full.txt

## 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/<org-slug>/mcp` | Streamable HTTP MCP endpoint agents connect to |
| OAuth discovery | `/.well-known/oauth-protected-resource/<org>/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 `/<org-slug>/…` (for example `/<org-slug>/policies`, `/<org-slug>/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

<Steps>
<Step title="Open the login page">

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.

</Step>
<Step title="Complete AuthKit and land in the console">

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).

</Step>
<Step title="Create or join an organization">

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.

</Step>
</Steps>

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.

<CodeGroup>
```bash title="Sign in to cloud"
executor login --base-url https://executor.sh
```

```bash title="Verify the stored profile"
executor whoami --server <profile-name>
```

```bash title="Call the API with stored credentials"
executor tools sources --server <profile-name>
```
</CodeGroup>

<ParamField body="--base-url" type="string">
  Origin of the hosted server (for example `https://executor.sh`). Mutually exclusive with `--server`.
</ParamField>

<ParamField body="--server" type="string">
  Named CLI server profile to update. Mutually exclusive with `--base-url`.
</ParamField>

<ParamField body="--name" type="string">
  Profile name to save under. Defaults to the authenticated account email.
</ParamField>

<ParamField body="--no-browser" type="boolean" default="false">
  Print the verification URL instead of opening a browser.
</ParamField>

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 <access_token>` to `/api/*`.

<Note>
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.
</Note>

## 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/<org-slug>/mcp
```

The server also accepts the legacy `/<org_id>/mcp` form (`org_…` WorkOS id). Bare `/mcp` resolves the organization from the authenticated token's `org_id` claim.

<Steps>
<Step title="Copy the endpoint from the console">

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.

</Step>
<Step title="Add the server to your agent">

Run the generated command (HTTP transport is the default for cloud):

```bash
npx add-mcp 'https://executor.sh/<org-slug>/mcp' --transport http --name executor
```

Restart the MCP client so it picks up the new server entry.

</Step>
<Step title="Complete MCP OAuth when prompted">

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/<org>/mcp`.

</Step>
</Steps>

Optional query parameter `elicitation_mode` controls approval handling: `browser` (web UI), `model` (default resume tool), or `native` (client-native elicitation).

<Tip>
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.
</Tip>

## 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/<org-slug>/mcp` | `http://localhost:<port>/mcp` or `executor mcp` stdio | `https://<your-host>/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 (`/<org-slug>/api-keys`) and send `Authorization: Bearer <api_key>` 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 (`/<org-slug>/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.

<Warning>
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.
</Warning>

## Related pages

<CardGroup>
<Card title="MCP proxy" href="/mcp-proxy">
How Executor fronts OpenAPI, GraphQL, and upstream MCP with one endpoint, shared auth, and per-tool policies.
</Card>
<Card title="Connect MCP clients" href="/connect-mcp-clients">
Wire Cursor, Claude Code, and other agents via HTTP or stdio, including `add-mcp` setup.
</Card>
<Card title="CLI reference" href="/cli-reference">
`login`, `logout`, `whoami`, `mcp`, `call`, and server profile flags.
</Card>
<Card title="Deploy self-hosted" href="/deploy-selfhost">
Run Executor on Docker or Cloudflare Workers when you need your own infrastructure.
</Card>
<Card title="Configure credentials" href="/configure-credentials">
Connection payloads, OAuth flows, and credential provider options across runtimes.
</Card>
<Card title="HTTP API reference" href="/http-api-reference">
Route groups, payloads, and error shapes for the protected API.
</Card>
</CardGroup>