Configuration - Executor

Executor configuration is managed through environment variables. This reference documents all available options for both self-hosted and cloud deployments.

Core Configuration

Convex Connection

Required for all deployments:

# Deployment identifier
CONVEX_DEPLOYMENT=dev:your-deployment-slug

# Backend API endpoint
CONVEX_URL=https://your-deployment.convex.cloud

# Site proxy endpoint (for MCP and HTTP routes)
CONVEX_SITE_URL=https://your-deployment.convex.site

For self-hosted binary installations, these are auto-configured to local endpoints. For cloud deployments, use the URLs from your Convex dashboard.

Deployment Mode

Controls security defaults and storage behavior:

# Allow local storage primitives
# Default when unset
EXECUTOR_DEPLOYMENT_MODE=self-hosted

Runtime Execution

VM Mode

Control code execution environment:

# Enable local Bun VM execution (self-hosted only)
DANGEROUSLY_ALLOW_LOCAL_VM=1

Production deployments should leave this unset to default to Cloudflare Worker sandbox execution. Only enable for local development or trusted self-hosted environments.

OpenAPI Generator

Optional external endpoint for heavy OpenAPI parsing:

# External generator URL
EXECUTOR_GENERATE_URL=http://localhost:4312

# Expected API format:
# GET /api/generate?specUrl=...&sourceName=...&includeDts=0|1

Storage Backend

Storage Provider

Configure agent filesystem storage:

# Default for self-hosted installations
AGENT_STORAGE_PROVIDER=agentfs-local

# Storage root directory
AGENT_STORAGE_ROOT=/tmp/executor-agentfs

# Disable metadata writes for read-only access
AGENT_STORAGE_TOUCH_ON_READ=false

agentfs-local is only supported for self-hosted/single-host deployments. Hosted Convex deployments must use agentfs-cloudflare because local filesystem state is not shared across workers.

Authentication

WorkOS (Organization Auth)

Enable multi-organization authentication:

# WorkOS application credentials
WORKOS_CLIENT_ID=client_...
WORKOS_API_KEY=sk_test_...

# Session cookie encryption (32+ character random string)
WORKOS_COOKIE_PASSWORD=<openssl rand -base64 32>

# Webhook verification
WORKOS_WEBHOOK_SECRET=...

WorkOS is optional. Omit these variables to run in anonymous mode.

Anonymous JWT Auth

Enable anonymous bearer token authentication via Convex Auth:

# ES256 key pair (PKCS8 private + SPKI public)
ANONYMOUS_AUTH_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
ANONYMOUS_AUTH_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

# Optional: token TTL (default: 604800 = 7 days)
ANONYMOUS_AUTH_TOKEN_TTL_SECONDS=604800

Generate Key Pair

openssl ecparam -name prime256v1 -genkey -noout -out private.pem
openssl ec -in private.pem -pubout -out public.pem

Convert to Environment 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)

MCP API Keys

Configure API key signing for MCP anonymous endpoint:

# Required to issue anonymous MCP API keys
MCP_API_KEY_SECRET=change-me

# API key TTL (default: 604800 = 7 days)
MCP_API_KEY_TTL_SECONDS=604800

MCP OAuth

Enable OAuth for the /mcp endpoint:

# Authorization server URL
MCP_AUTHORIZATION_SERVER=https://your-authkit-domain.authkit.app

Credential Management

Force managed credential storage:

# Override deployment-mode defaults
EXECUTOR_ENFORCE_MANAGED_CREDENTIALS=1

Billing

Stripe Integration

Enable checkout and billing portal:

# Stripe API credentials
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID=price_...

# Redirect URLs
BILLING_SUCCESS_URL=http://localhost:4312/organization?tab=billing&success=true
BILLING_CANCEL_URL=http://localhost:4312/organization?tab=billing&canceled=true
BILLING_RETURN_URL=http://localhost:4312/organization?tab=billing

All Stripe variables are optional. Omit them to disable billing features.

Port Configuration

Backend Ports

Override default managed runtime ports:

# Backend API port (default: 5410)
EXECUTOR_BACKEND_PORT=5410

# Backend site proxy port (default: 5411)
EXECUTOR_BACKEND_SITE_PORT=5411

Web UI Port

Configure web interface port:

# Web UI port (default: 5312)
EXECUTOR_WEB_PORT=5312

# Web UI interface (default: 127.0.0.1)
EXECUTOR_WEB_INTERFACE=127.0.0.1

Assistant Port

Configure assistant server port:

# Assistant server port (default: 3002)
ASSISTANT_PORT=3002

Installation Paths

Runtime Directories

Customize installation locations:

# Binary install directory (default: ~/.executor/bin)
EXECUTOR_INSTALL_DIR=$HOME/.executor/bin

# Runtime root directory (default: ~/.executor/runtime)
EXECUTOR_RUNTIME_DIR=$HOME/.executor/runtime

# Web bundle directory (default: ~/.executor/runtime/web)
EXECUTOR_WEB_INSTALL_DIR=$HOME/.executor/runtime/web

# Home directory (default: ~/.executor)
EXECUTOR_HOME_DIR=$HOME/.executor

Instance Configuration

Managed backend instance settings:

# Instance name (default: anonymous-executor)
EXECUTOR_INSTANCE_NAME=anonymous-executor

# Instance secret (auto-generated if unset)
EXECUTOR_INSTANCE_SECRET=<random-hex>

# Backend interface (default: 127.0.0.1)
EXECUTOR_BACKEND_INTERFACE=127.0.0.1

Web UI Configuration

Convex URL Overrides

Override Convex URLs for web UI:

# Custom Convex URL for web UI
EXECUTOR_WEB_CONVEX_URL=http://localhost:5410

# Custom Convex site URL for web UI
EXECUTOR_WEB_CONVEX_SITE_URL=http://localhost:5411

These override the default managed runtime endpoints. Useful for proxying or custom network configurations.

Assistant Configuration

Configure assistant server integration:

# Executor URL for assistant
OPENASSISTANT_EXECUTOR_URL=http://localhost:3001

# Assistant callback base URL
OPENASSISTANT_CALLBACK_BASE_URL=http://localhost:3002

Discord Bot

Enable Discord bot integration:

# Discord bot token (omit to skip bot startup)
DISCORD_BOT_TOKEN=...

Tool Source API Keys

Optional API keys for tool source integrations:

# PostHog
POSTHOG_PERSONAL_API_KEY=...
POSTHOG_PROJECT_ID=...

# GitHub (for assistant)
OPENASSISTANT_GITHUB_TOKEN=...

# Vercel
VERCEL_TOKEN=...

Advanced Options

Skip Runtime Image

Skip runtime image installation during setup:

# Skip runtime image download
EXECUTOR_SKIP_RUNTIME_IMAGE=1

Custom Repository

Use a custom GitHub repository for releases:

# Custom release repository (default: RhysSullivan/executor)
EXECUTOR_REPO=your-org/executor-fork

Install URL Override

Custom installer script URL:

# Custom installer URL (default: https://executor.sh/install)
EXECUTOR_INSTALL_URL=https://your-domain.com/install

Environment File Structure

A complete .env file for cloud deployment:

.env

# ── Convex (required) ──
CONVEX_DEPLOYMENT=dev:your-deployment-slug
CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_SITE_URL=https://your-deployment.convex.site

# ── Runtime execution mode ──
EXECUTOR_DEPLOYMENT_MODE=cloud
# Leave unset for cloud deployments:
# DANGEROUSLY_ALLOW_LOCAL_VM=1

# ── Agent storage backend ──
AGENT_STORAGE_PROVIDER=agentfs-cloudflare
CLOUDFLARE_SANDBOX_RUN_URL=https://your-worker.workers.dev
CLOUDFLARE_SANDBOX_AUTH_TOKEN=your-auth-token

# ── WorkOS (optional) ──
WORKOS_CLIENT_ID=client_...
WORKOS_API_KEY=sk_test_...
WORKOS_COOKIE_PASSWORD=<32+ char random string>
WORKOS_WEBHOOK_SECRET=...

# ── Anonymous JWT Auth (optional) ──
ANONYMOUS_AUTH_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
ANONYMOUS_AUTH_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
MCP_API_KEY_SECRET=change-me

# ── Stripe Billing (optional) ──
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID=price_...
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

# ── MCP OAuth (optional) ──
MCP_AUTHORIZATION_SERVER=https://your-authkit-domain.authkit.app

A complete .env file for self-hosted deployment:

.env

# ── Convex (auto-configured by binary) ──
# CONVEX_URL=http://127.0.0.1:5410
# CONVEX_SITE_URL=http://127.0.0.1:5411

# ── Runtime execution mode ──
EXECUTOR_DEPLOYMENT_MODE=self-hosted
DANGEROUSLY_ALLOW_LOCAL_VM=1

# ── Agent storage backend ──
AGENT_STORAGE_PROVIDER=agentfs-local
AGENT_STORAGE_ROOT=/tmp/executor-agentfs

# ── Anonymous JWT Auth (auto-generated by binary) ──
# ANONYMOUS_AUTH_PRIVATE_KEY_PEM=...
# ANONYMOUS_AUTH_PUBLIC_KEY_PEM=...
# MCP_API_KEY_SECRET=...

# ── Local port overrides (optional) ──
EXECUTOR_BACKEND_PORT=5410
EXECUTOR_BACKEND_SITE_PORT=5411
EXECUTOR_WEB_PORT=5312

Credential Providers

Executor supports multiple credential storage backends:

Managed (Convex)

Store credential payloads directly in Convex:

{
  provider: "managed",
  secretJson: { apiKey: "sk_..." }
}

WorkOS Vault

Store encrypted payloads in WorkOS Vault:

{
  provider: "workos-vault",
  secretJson: { objectId: "vault_obj_..." }
}

WorkOS Vault requires WORKOS_API_KEY for vault reads. Existing objects can be imported by reference.

Configuration Precedence

Environment variables are loaded with the following precedence:

Process environment - Variables set in the current shell
Managed runtime config - Auto-generated for binary installations
Convex environment - Variables set in Convex dashboard
Default values - Built-in defaults

For cloud deployments, set variables in the Convex dashboard. Local .env files are only used during development.

Get Started

Core Features

Deployment

Integrations

​Core Configuration

​Convex Connection

​Deployment Mode

​Runtime Execution

​VM Mode

​OpenAPI Generator

​Storage Backend

​Storage Provider

​Authentication

​WorkOS (Organization Auth)

​Anonymous JWT Auth

​MCP API Keys

​MCP OAuth

​Credential Management

​Billing

​Stripe Integration

​Port Configuration

​Backend Ports

​Web UI Port

​Assistant Port

​Installation Paths

​Runtime Directories

​Instance Configuration

​Web UI Configuration

​Convex URL Overrides

​Assistant Configuration

​Discord Bot

​Tool Source API Keys

​Advanced Options

​Skip Runtime Image

​Custom Repository

​Install URL Override

​Environment File Structure

​Credential Providers

​Managed (Convex)

​WorkOS Vault

​Configuration Precedence

​Next Steps

Self-Hosting

Cloud Deployment

Build docs developers (and LLMs) love

Core Configuration

Convex Connection

Deployment Mode

Runtime Execution

VM Mode

OpenAPI Generator

Storage Backend

Storage Provider

Authentication

WorkOS (Organization Auth)

Anonymous JWT Auth

MCP API Keys

MCP OAuth

Credential Management

Billing

Stripe Integration

Port Configuration

Backend Ports

Web UI Port

Assistant Port

Installation Paths

Runtime Directories

Instance Configuration

Web UI Configuration

Convex URL Overrides

Assistant Configuration

Discord Bot

Tool Source API Keys

Advanced Options

Skip Runtime Image

Custom Repository

Install URL Override

Environment File Structure

Credential Providers

Managed (Convex)

WorkOS Vault

Configuration Precedence

Next Steps