Skip to main content
Executor can be deployed to hosted Convex for production use, providing a fully managed control plane with global availability and automatic scaling.

​
Prerequisites

1

Convex Account

Create a Convex account at convex.dev if you don’t have one.
2

Install Convex CLI

npm install -g convex
3

Clone Repository

git clone https://github.com/RhysSullivan/executor.git
cd executor/executor

​
Deployment Process

1

Initialize Convex Project

From the executor/ directory:
bunx convex dev
This will:
  • Create a new Convex deployment
  • Generate deployment credentials
  • Start watching for code changes
2

Configure Environment

Copy the environment template:
cp ../.env.example .env
Set required variables:
.env
# Convex deployment (from convex dev output)
CONVEX_DEPLOYMENT=dev:your-deployment-slug
CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_SITE_URL=https://your-deployment.convex.site

# Deployment mode for cloud
EXECUTOR_DEPLOYMENT_MODE=cloud

# Use Cloudflare storage (required for cloud)
AGENT_STORAGE_PROVIDER=agentfs-cloudflare
3

Deploy Functions

Deploy to production:
bun run deploy
This runs convex deploy and pushes all backend functions to Convex.
4

Deploy Web UI

Build and deploy the Next.js web UI to your hosting platform:
cd apps/web
bun run build
Deploy the .next build to Vercel, Netlify, or your hosting provider.

​
Deployment Modes

Executor uses EXECUTOR_DEPLOYMENT_MODE to control security and storage behavior: 
# Default mode for local/single-host deployments
# Allows local storage primitives
EXECUTOR_DEPLOYMENT_MODE=self-hosted
AGENT_STORAGE_PROVIDER=agentfs-local
Using agentfs-local in cloud deployments will fail because local filesystem state is not shared across Convex workers. Always use agentfs-cloudflare for production cloud deployments.

​
Runtime Configuration

​
Execution Mode

Control where code executes: 
# Allow local Bun VM execution (self-hosted only)
DANGEROUSLY_ALLOW_LOCAL_VM=1

# Production: use Cloudflare runtime (default when unset)
# Leave DANGEROUSLY_ALLOW_LOCAL_VM unset
In production cloud deployments, leave DANGEROUSLY_ALLOW_LOCAL_VM unset to enforce Cloudflare Worker sandbox execution for security.

​
OpenAPI Generator

For heavy OpenAPI parsing, configure an external generator endpoint: 
# Optional external generator for Convex
EXECUTOR_GENERATE_URL=http://localhost:4312
This endpoint expects: 
GET /api/generate?specUrl=...&sourceName=...&includeDts=0|1

​
Authentication Setup

Enable organization-based authentication with WorkOS:
1

Create WorkOS Application

Sign up at workos.com and create an application.
2

Configure Environment

.env
WORKOS_CLIENT_ID=client_...
WORKOS_API_KEY=sk_test_...
WORKOS_COOKIE_PASSWORD=<32+ char random string>
WORKOS_WEBHOOK_SECRET=...
Generate a secure cookie password:
openssl rand -base64 32
3

Set MCP Authorization

Configure OAuth for the MCP endpoint:
MCP_AUTHORIZATION_SERVER=https://your-authkit-domain.authkit.app

​
Anonymous Mode

For development or single-user deployments, use anonymous JWT auth: 
# Generate ES256 key pair
openssl ecparam -name prime256v1 -genkey -noout -out private.pem
openssl ec -in private.pem -pubout -out public.pem

# Convert to single-line PEM format
export ANONYMOUS_AUTH_PRIVATE_KEY_PEM=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' private.pem)
export ANONYMOUS_AUTH_PUBLIC_KEY_PEM=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' public.pem)

# API key signing secret
export MCP_API_KEY_SECRET=change-me
Add to your .env or Convex environment variables.

​
Billing Integration

​
Stripe Setup

Enable checkout and billing portal with Stripe:
.env
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID=price_...

# Redirect URLs
BILLING_SUCCESS_URL=https://your-domain.com/organization?tab=billing&success=true
BILLING_CANCEL_URL=https://your-domain.com/organization?tab=billing&canceled=true
BILLING_RETURN_URL=https://your-domain.com/organization?tab=billing
Stripe is optional. Omit these variables to disable billing features.

​
Storage Providers

​
Cloudflare Storage (Cloud)

Required for hosted Convex deployments: 
AGENT_STORAGE_PROVIDER=agentfs-cloudflare

# Cloudflare Durable Objects proxy (served by runner-sandbox-host)
CLOUDFLARE_SANDBOX_RUN_URL=https://your-worker.workers.dev
CLOUDFLARE_SANDBOX_AUTH_TOKEN=your-auth-token

​
Local Storage (Self-Hosted Only)

AGENT_STORAGE_PROVIDER=agentfs-local
AGENT_STORAGE_ROOT=/tmp/executor-agentfs

# Optional: disable metadata writes for read-only access
AGENT_STORAGE_TOUCH_ON_READ=false
agentfs-local is only supported for self-hosted/single-host deployments. Do not use in cloud.

​
MCP Endpoints

Cloud deployments expose MCP at: 
https://your-deployment.convex.site/mcp
https://your-deployment.convex.site/mcp/anonymous

​
OAuth Protected Endpoint

/mcp requires bearer token verification when MCP_AUTHORIZATION_SERVER is configured: 
curl -H "Authorization: Bearer <token>" \
  https://your-deployment.convex.site/mcp

​
Anonymous Endpoint

/mcp/anonymous uses API key authentication: 
curl -H "x-api-key: <api-key>" \
  https://your-deployment.convex.site/mcp/anonymous?workspaceId=...
Alternatively, pass as Authorization header: 
curl -H "Authorization: Bearer <api-key>" \
  https://your-deployment.convex.site/mcp/anonymous?workspaceId=...

​
Environment Variables in Convex

Convex uses environment variables set in your dashboard:
1

Open Convex Dashboard

Navigate to your deployment at dashboard.convex.dev
2

Set Environment Variables

Go to Settings → Environment Variables and add:
  • EXECUTOR_DEPLOYMENT_MODE=cloud
  • AGENT_STORAGE_PROVIDER=agentfs-cloudflare
  • Auth credentials (WorkOS or anonymous JWT keys)
  • Optional: Stripe keys for billing
3

Redeploy

bun run deploy
Convex environment variables are separate from your local .env file. Set them in the dashboard for production.

​
Production Checklist

1

Security

  • Set EXECUTOR_DEPLOYMENT_MODE=cloud
  • Use agentfs-cloudflare storage
  • Leave DANGEROUSLY_ALLOW_LOCAL_VM unset
  • Configure WorkOS or anonymous JWT auth
  • Set secure cookie password (32+ chars)
2

Infrastructure

  • Deploy Convex functions with bun run deploy
  • Deploy web UI to hosting platform
  • Configure custom domain
  • Set up SSL/TLS certificates
3

Monitoring

  • Enable Convex logs in dashboard
  • Set up error tracking (Sentry, etc.)
  • Configure uptime monitoring
4

Optional Features

  • Configure Stripe for billing
  • Set up external OpenAPI generator
  • Configure credential vault (WorkOS Vault)

​
Troubleshooting

Verify bearer token issuer matches MCP_AUTHORIZATION_SERVER:
# Check JWT issuer
echo $TOKEN | jwt decode -
Pass API key from workspace settings:
curl -H "x-api-key: $API_KEY" \
  https://your-deployment.convex.site/mcp/anonymous?workspaceId=...
You’re using agentfs-local in cloud. Switch to agentfs-cloudflare:
AGENT_STORAGE_PROVIDER=agentfs-cloudflare
Verify CONVEX_URL and CONVEX_SITE_URL in web UI environment variables match your deployment.

​
Next Steps

Configuration

Complete environment variable reference

Self-Hosting

Deploy locally with the binary CLI

Build docs developers (and LLMs) love

Get started for freeTalk to us