Installation

Executor supports three installation methods: binary install (recommended for local use), building from source (for development), and hosted SaaS (for production).

Binary Install (Recommended)

The binary installer provides a self-contained Executor runtime with no global dependencies required.

One-Command Install

curl -fsSL https://executor.sh/install | bash

This installs:

executor CLI binary at ~/.executor/bin/executor
Managed Convex local backend
Packaged web UI
Node runtime for web server
Background service management

The installer automatically adds ~/.executor/bin to your shell PATH. Restart your terminal or run source ~/.bashrc (or ~/.zshrc) to use the executor command.

What Gets Installed

Binary Location

Installed at: ~/.executor/bin/executorThe CLI binary is compiled for your platform (Linux or macOS, x64 or ARM64) and requires no runtime dependencies.

Runtime Directory

Location: ~/.executor/runtime/Contains:

convex-backend/: Managed Convex local backend binary
web/: Packaged Next.js web application
node-v*/: Managed Node.js runtime
convex-data/: Local SQLite database and file storage
services/: PID files for background services
logs/: Backend and web server logs

Default Ports

Backend API: 5410
Backend Site (MCP endpoints): 5411
Web UI: 5312

Override with environment variables:

export EXECUTOR_BACKEND_PORT=5410
export EXECUTOR_BACKEND_SITE_PORT=5411
export EXECUTOR_WEB_PORT=5312

Data Persistence

Local data is stored in ~/.executor/runtime/convex-data/:

SQLite database files
File storage for agent filesystem operations
Anonymous session credentials

This data is preserved across upgrades. Back up this directory before uninstalling.

Install Options

curl -fsSL https://executor.sh/install | bash -s -- --version v1.2.3

Verify Installation

Check that Executor is installed and services are healthy:

executor doctor

Expected output:

Executor status: ready
Dashboard: http://127.0.0.1:5312 (running)
Backend: running (http://127.0.0.1:5410)
Functions: available
MCP endpoint: http://127.0.0.1:5411/v1/mcp

Use executor doctor --verbose to see detailed runtime information including paths, versions, and configuration.

Post-Install

The installer automatically:

Stops any existing Executor services
Installs/updates the binary and runtime
Starts the backend and web UI in the background
Waits for services to become healthy

Access the dashboard at http://localhost:5312

From Source

Build and run Executor from the monorepo for development or to integrate with an existing Convex deployment.

Prerequisites

Install Bun

Executor uses Bun as its runtime and package manager:

curl -fsSL https://bun.sh/install | bash

Convex Account

Create a Convex account and project at convex.dev.You’ll need:

Deployment URL (e.g., https://happy-animal-123.convex.cloud)
Deployment name (e.g., happy-animal-123)

Clone and Install

# Clone the repository
git clone https://github.com/RhysSullivan/executor.git
cd executor

# Install dependencies
bun install

Configure Environment

Copy environment template

cp .env.example .env

Set required variables

Edit .env and set at minimum:

.env

CONVEX_DEPLOYMENT=happy-animal-123
CONVEX_URL=https://happy-animal-123.convex.cloud

Optional: Configure services

For full functionality, also configure:

.env

# Storage (required for file operations in cloud deployments)
AGENT_STORAGE_PROVIDER=agentfs-cloudflare
CLOUDFLARE_SANDBOX_RUN_URL=https://your-worker.workers.dev
CLOUDFLARE_SANDBOX_AUTH_TOKEN=your-token

# Authentication (for WorkOS-based auth)
WORKOS_CLIENT_ID=client_...
WORKOS_API_KEY=sk_...
WORKOS_COOKIE_PASSWORD=complex-secret-at-least-32-chars

# Billing (for Stripe integration)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID=price_...

Run Development Services

Full Stack (Recommended)
Executor Only
Manual Services

Start all services with a single command:

bun run dev

This starts:

Convex dev watcher (functions hot reload)
Web UI at http://localhost:4312
MCP endpoints at <CONVEX_SITE_URL>/mcp
Assistant server (if configured)
Discord bot (if DISCORD_BOT_TOKEN is set)

PIDs are tracked in .dev.pids. Stop all with:

bun run kill:all

Run just the Executor components (separate terminals):

Terminal 1: Convex

bun run dev:executor:convex

Terminal 2: Web UI

bun run dev:executor:web

Web UI runs at http://localhost:4312

Run services individually:

Convex Dev

cd executor/packages/convex
bunx convex dev

Web App

cd executor/apps/web
bun run dev

Local Runtime vs Cloud

When running from source, you can use either a local Bun runtime or Cloudflare Workers.

Local Bun Runtime (development only):

.env

DANGEROUSLY_ALLOW_LOCAL_VM=1
AGENT_STORAGE_PROVIDER=agentfs-local

Cloudflare Workers (production-ready):

.env

# DANGEROUSLY_ALLOW_LOCAL_VM not set
AGENT_STORAGE_PROVIDER=agentfs-cloudflare
CLOUDFLARE_SANDBOX_RUN_URL=https://your-worker.workers.dev
CLOUDFLARE_SANDBOX_AUTH_TOKEN=your-token

Build Binary from Source

Compile a native binary for distribution:

cd executor
bun run build:binary

Output:

Binary: executor/dist/executor
Runtime bundle: executor/dist/release/executor-runtime-{os}-{arch}.tar.gz

Install locally:

bash executor/install --binary executor/dist/executor --no-modify-path

Hosted SaaS

Use Executor without any installation at executor.sh.

Features

Automatic Updates

Always on the latest version with zero maintenance

WorkOS Auth

Enterprise SSO and organization management

Managed Infrastructure

Scalable Convex backend and Cloudflare Workers

Stripe Billing

Integrated usage-based billing

Getting Started

Visit executor.sh and create an account

Create an organization

Set up your organization and invite team members

Configure workspace

Add tool sources, credentials, and access policies

Get MCP credentials

Generate an API key for your MCP client from the dashboard

MCP Endpoint

Hosted endpoint:

https://app.executor.sh/mcp

Authenticate with WorkOS OAuth or API key.

System Requirements

Binary Install

Linux
macOS

OS: Linux (glibc 2.31+)
Architecture: x86_64 or ARM64
Disk: 500 MB free space
RAM: 512 MB minimum
Dependencies: curl, tar, sha256sum or shasum

From Source

Bun: 1.0.0 or later
Node.js: 18+ (only for Next.js build)
Git: Any recent version
Disk: 2 GB for dependencies and builds
RAM: 2 GB minimum (4 GB recommended for development)

Upgrade

Upgrade an existing binary installation:

executor upgrade

This:

Downloads the latest installer
Stops running services
Upgrades binary and runtime
Restarts services
Preserves local data

Use executor upgrade --version v1.2.3 to install a specific version.

Uninstall

Remove Executor and all runtime files:

executor uninstall --yes

This removes:

~/.executor/bin/executor
~/.executor/runtime/ (including local data)
Background services

Uninstall does not remove the PATH entry from your shell rc file. Remove it manually:

# Remove this line from ~/.bashrc or ~/.zshrc
export PATH=$HOME/.executor/bin:$PATH

Troubleshooting

Services Not Starting

Check status:

executor doctor --verbose

View logs:

tail -f ~/.executor/runtime/logs/backend.log
tail -f ~/.executor/runtime/logs/web.log

Restart services:

executor down
executor up
executor web &

Port Conflicts

Change default ports if they’re already in use:

export EXECUTOR_BACKEND_PORT=6410
export EXECUTOR_BACKEND_SITE_PORT=6411
export EXECUTOR_WEB_PORT=6312
executor down
executor up

Binary Not Found

If executor command is not found after install:

# Manually add to PATH (bash)
echo 'export PATH=$HOME/.executor/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Or use full path
~/.executor/bin/executor doctor

Functions Not Available

If executor doctor shows “Functions: unavailable”:

Check backend logs:

cat ~/.executor/runtime/logs/backend.log

Verify backend is running:
```
curl http://127.0.0.1:5410/version
```

Restart and watch logs:

executor down
executor up  # runs in foreground

Permission Denied

If you get permission errors:

# Fix binary permissions
chmod +x ~/.executor/bin/executor

# Fix runtime directory permissions
chmod -R u+rw ~/.executor/runtime

Get Started

Core Features

Deployment

Integrations

​Installation

​Binary Install (Recommended)

​One-Command Install

​What Gets Installed

​Install Options

​Verify Installation

​Post-Install

​From Source

​Prerequisites

​Clone and Install

​Configure Environment

​Run Development Services

​Local Runtime vs Cloud

​Build Binary from Source

​Hosted SaaS

​Features

Automatic Updates

WorkOS Auth

Managed Infrastructure

Stripe Billing

​Getting Started

​MCP Endpoint

​System Requirements

​Binary Install

​From Source

​Upgrade

​Uninstall

​Troubleshooting

​Services Not Starting

​Port Conflicts

​Binary Not Found

​Functions Not Available

​Permission Denied

​Next Steps

Quick Start

Configuration

Build docs developers (and LLMs) love

Installation

Binary Install (Recommended)

One-Command Install

What Gets Installed

Install Options

Verify Installation

Post-Install

From Source

Prerequisites

Clone and Install

Configure Environment

Run Development Services

Local Runtime vs Cloud

Build Binary from Source

Hosted SaaS

Features

Getting Started

MCP Endpoint

System Requirements

Binary Install

From Source

Upgrade

Uninstall

Troubleshooting

Services Not Starting

Port Conflicts

Binary Not Found

Functions Not Available

Permission Denied

Next Steps