Self-host Executor, the open-source MCP gateway

Add your tools#

Open https://my-executor.exe.xyz/ and create your account: an organization name, your name, an email and a password. Skip Connect your accounts for now.

On Apps, choose Add app:

• From an MCP server takes a remote MCP server's URL. Try https://mcp.deepwiki.com/mcp: Executor finds its three tools and makes an app of them. Servers that need a sign-in use OAuth, from the app's Accounts tab.
• Browse app catalog lists ready-made apps such as Gmail, GitHub, Linear and Stripe. Some need an OAuth client of your own; give the provider https://my-executor.exe.xyz/api/oauth/callback as its redirect URL.
• From scratch gives you a prompt for your agent, which then writes the app: for an OpenAPI or GraphQL API, a service with an API key, or a tool of your own.

Each app is TypeScript code you can read on its Source tab. Apps made from an MCP server ask for your approval before any tool the server marks as destructive; edit that rule there.

Connect your agents#

Each agent sends two headers:

• X-Exedev-Authorization: Bearer exe1.…, a VM token that gets it through exe.dev's proxy, which removes it before Executor sees the request.
• Authorization: Bearer exp_…, an Executor personal access token.

Make the VM token on your computer (--exp sets when it expires):

ssh exe.dev ssh-key generate-api-key --vm=my-executor --label=executor-agents --exp=90d

For the Executor token, open your avatar menu → Account settings → Tokens → Create token, name it after the agent, and limit it to your organization. It's shown once. Below, replace exe1.paste-yours-here and exp_paste-yours-here with yours.

Claude Code, on your computer or a VM like the one in Claude Code on exe.dev:

claude mcp add --transport http --scope user executor https://my-executor.exe.xyz/mcp \
  --header "X-Exedev-Authorization: Bearer exe1.paste-yours-here" \
  --header "Authorization: Bearer exp_paste-yours-here"
claude mcp list

Expect executor: https://my-executor.exe.xyz/mcp (HTTP) - ✔ Connected.

Codex, on your computer or a Codex VM, in ~/.codex/config.toml:

[mcp_servers.executor]
url = "https://my-executor.exe.xyz/mcp"
http_headers = { "X-Exedev-Authorization" = "Bearer exe1.paste-yours-here", "Authorization" = "Bearer exp_paste-yours-here" }

Shelley, on any of your VMs:

shelley mcp add executor -d "Executor: my apps and tools" \
  -H "X-Exedev-Authorization: Bearer exe1.paste-yours-here" \
  -H "Authorization: Bearer exp_paste-yours-here" \
  https://my-executor.exe.xyz/mcp
shelley mcp call executor.search query=deepwiki

Other clients: any MCP client that speaks Streamable HTTP and can send headers works the same way. An agent on the Executor VM itself can skip the VM token and use http://localhost:8000/mcp.

Tip

For agents on your other exe.dev VMs, a VM-to-VM integration can add both headers at exe.dev's edge, so no token is stored on the agent's VM. On your computer, for an agent on my-hermes-agent: ssh exe.dev integrations add http-proxy --name executor-hermes --target https://my-executor.exe.xyz/ --peer --bearer exp_paste-yours-here --attach vm:my-hermes-agent. The agent's URL is then https://executor-hermes.int.exe.xyz/mcp, with no headers.

Try it#

Ask your agent:

Use executor to find out how the UsefulSoftwareCo/executor repository is structured.

It searches Executor's catalog, finds the DeepWiki tools, and calls one. The six tools an agent sees are always the same (search, describe, call, execute, resume, skills); the apps behind them are what you add. To have an agent add one:

Use executor to add an app for the Linear API.

When a call needs your approval, the agent shows you the request and passes on your answer.

Keys off the VM#

API keys you give Executor stay in its encrypted database, not in your agents. To keep some off the VM entirely, use an exe.dev integration: exe.dev holds the secret and adds it at its edge when the VM calls https://<name>.int.exe.xyz. Executor's app sandbox refuses private addresses, which these are, until you allow them in ~/executor/compose.yaml, under environment:

      EXECUTOR_APPS_ALLOW_PRIVATE_FETCH: "true"

Then run docker compose up -d in ~/executor, and ask your agent for an app that calls https://<name>.int.exe.xyz with no credentials.

Warning

This applies to every app, not just one: any app can then reach every integration attached to the VM and services on the VM itself. Allow it only if you read the apps your agents write.

Cloud agents#

claude.ai, ChatGPT, and agents running in their makers' clouds can't send an exe.dev token, so they can reach only a public VM. Executor then is the only lock, and a real one: /mcp refuses requests without a token, and clients sign in with OAuth in your browser, which needs your Executor password and your approval. Create your account first, then, on your computer:

ssh exe.dev share set-public my-executor

Add https://my-executor.exe.xyz/mcp to the app as a custom connector and sign in. Claude Code (/mcp) and Codex (codex mcp login executor) can sign in the same way. OAuth connections can also be limited to some apps: on Connections, make a connection and use its MCP URL.

Warning

Public means Executor's sign-in page faces the internet. Use a strong password, approve only connections you just started, and go back with ssh exe.dev share set-private my-executor when you're done.

The nuts and bolts#

Happy with what Shelley set up? Stop here. Below are the steps it followed, and maintenance for later.

ssh exe.dev new --name=my-executor
ssh my-executor.exe.xyz

mkdir -p ~/executor && cd ~/executor
echo "BETTER_AUTH_URL=https://$(hostname).exe.xyz" > .env
cat > compose.yaml <<'EOF'
services:
  executor:
    image: ghcr.io/usefulsoftwareco/executor-selfhost:2.0.0-beta.34
    init: true
    restart: unless-stopped
    ports:
      - "8000:4400"
    environment:
      BETTER_AUTH_URL: ${BETTER_AUTH_URL}
      EXECUTOR_CATALOG_URL: https://catalog.executor.sh/index.json
      DO_NOT_TRACK: "1"
    volumes:
      - ./data:/app/data
    stop_grace_period: 30s
EOF
sudo systemctl enable --now docker.service
docker compose up -d

until curl -fsS http://localhost:8000/health; do sleep 2; done; echo
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8000/mcp

cd ~/executor
docker compose stop
(umask 077; tar -czf - data compose.yaml .env > ~/executor-$(date -u +%Y%m%d).tar.gz)
docker compose start

cd ~/executor
docker compose stop
rm -rf data
tar -xzf ~/executor-20261031.tar.gz -C ~/executor
docker compose start

cd ~/executor
docker compose pull && docker compose up -d