Skip to main content
Executor provides a fully self-contained binary installation that manages its own runtime, including a local Convex backend, Node.js runtime, and packaged web UI. No global dependencies required.

​
Quick Install

Install Executor with a single command: 
curl -fsSL https://executor.sh/install | bash
The installer will:
  • Download the executor binary to ~/.executor/bin/
  • Install the managed runtime to ~/.executor/runtime/
  • Start background services automatically
  • Add executor to your PATH

​
Managed Runtime

The binary manages a complete runtime environment under ~/.executor/runtime/:
  • Convex Local Backend: Managed convex-local-backend binary
  • Node.js Runtime: Bundled Node.js v22.22.0 for the web UI
  • Web UI: Packaged Next.js production build
  • Local Data: SQLite database and file storage
  • Configuration: Instance credentials and port settings
The managed runtime provides local-first operation without requiring cloud dependencies or internet connectivity during execution.

​
Binary CLI Commands

After installation, use these commands to manage your Executor instance:
1

Check Status

Run a health check to verify all services are running:
executor doctor
For detailed diagnostics:
executor doctor --verbose
2

Start Services

Start the managed backend manually:
executor up
Start the web UI:
executor web
Both services start automatically during installation.
3

Stop Services

Stop all background services:
executor down
4

Access Backend Directly

Pass arguments to the managed backend:
executor backend --help
executor backend --version

​
Default Ports

The managed runtime uses these local ports:
ServicePortDescription
Backend API5410Convex backend HTTP endpoint
Backend Site5411Site proxy for MCP and HTTP routes
Web UI5312Next.js dashboard
Override default ports by setting EXECUTOR_BACKEND_PORT, EXECUTOR_BACKEND_SITE_PORT, or EXECUTOR_WEB_PORT environment variables before running the installer.

​
Data Storage

All runtime data is stored in ~/.executor/runtime/convex-data/:
  • convex_local_backend.sqlite3 - Main database
  • storage/ - File storage for tasks and artifacts
This directory persists across upgrades. To reset your local instance: 
executor down
rm -rf ~/.executor/runtime/convex-data
executor up

​
MCP Endpoint

The self-hosted instance exposes MCP endpoints at: 
http://127.0.0.1:5411/v1/mcp/anonymous
Authenticate using the API key from your workspace settings in the web UI.

​
Integration with Claude Code

Executor includes built-in Claude Code integration: 
executor claude
This command:
  1. Generates a temporary MCP configuration
  2. Bootstraps an anonymous workspace session
  3. Launches Claude Code with the mcp__executor__execute tool
executor claude
Claude Code CLI must be installed first: curl -fsSL https://claude.ai/install.sh | bash

​
Upgrade

Update to the latest release: 
executor upgrade
Install a specific version: 
executor upgrade --version v0.1.5

​
Uninstall

Remove the executor binary and managed runtime: 
executor uninstall --yes
Manually remove the PATH entry from your shell rc file if needed: 
# Remove this line from ~/.zshrc, ~/.bashrc, or ~/.profile
export PATH=$HOME/.executor/bin:$PATH

​
Advanced: Custom Installation Paths

Customize installation directories with environment variables: 
# Custom binary location
export EXECUTOR_INSTALL_DIR="$HOME/bin"

# Custom runtime location
export EXECUTOR_RUNTIME_DIR="$HOME/.local/share/executor"

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

​
Advanced: Local Development Build

Install from a local source build: 
# From the executor/ directory
bun run build:binary
bash install --binary dist/executor

​
Troubleshooting

Check logs for errors:
cat ~/.executor/runtime/logs/backend.log
cat ~/.executor/runtime/logs/web.log
Verify ports are not in use:
lsof -ti tcp:5410
lsof -ti tcp:5312
Ensure the backend is running:
curl http://127.0.0.1:5410/version
If not running:
executor down
executor up
Run with verbose output:
executor doctor --verbose
Skip function checks if only testing runtime:
executor doctor --runtime-only
Manually stop services first:
executor down
executor upgrade

​
Next Steps

Configuration

Configure environment variables and runtime options

Cloud Deployment

Deploy to hosted Convex for production use

Build docs developers (and LLMs) love

Get started for freeTalk to us