Skip to main content

​
Introduction to Executor

Executor is a Convex-native execution platform for MCP-driven agents that provides secure task execution, approval workflows, and comprehensive workspace management.

Quick Start

Get up and running with Executor in minutes

Installation

Install Executor via binary or build from source

Deploy Self-Hosted

Run Executor with the binary CLI

MCP Integration

Connect agents via MCP protocol

​
What is Executor?

Executor enables AI agents to execute code safely and efficiently with built-in approval gates, workspace-scoped policies, and comprehensive tool management. It bridges the gap between AI capabilities and secure code execution.

​
Key Features

Task Execution

Execute TypeScript code in a secure sandbox with tool invocation support

Approval Workflows

Configurable approval gates for sensitive operations with workspace-level policies

MCP Endpoints

Native MCP protocol support for seamless agent integration

Tool Discovery

Automatic tool discovery from MCP, OpenAPI, and GraphQL sources

Workspace Management

Multi-tenant workspaces with member roles and access controls

Self-Hosted & Cloud

Deploy as SaaS or run locally with the binary CLI

​
Core Components

​
Task Execution Engine

Executor runs TypeScript code in a secure Cloudflare Worker sandbox with full tool access. Tasks can invoke tools, request approvals, and stream output in real-time. 
// Example: Execute code via MCP
const result = await execute({
  code: `
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();
    return data;
  `,
  workspace: 'my-workspace'
});

​
Approval System

Tool policies control execution flow:
  • Auto-allow: Execute immediately without approval
  • Require approval: Pause execution until approved by workspace admin
  • Deny: Block execution of sensitive operations

​
MCP Integration

Executor provides MCP endpoints for agent integration: 
# OAuth-protected endpoint
https://your-deployment.convex.site/mcp

​
Deployment Options

​
Architecture Overview

​
Control Plane (Convex)

Convex functions manage:
  • Tasks: Queued, running, and completed execution records
  • Approvals: Pending approval requests and audit logs
  • Policies: Workspace-scoped tool access rules
  • Credentials: Encrypted secrets for tool authentication
  • Organizations: Multi-tenant workspace hierarchy

​
Execution Runtime

Two runtime adapters:
  • Cloudflare Worker: Production sandbox (default for hosted deployments)
  • Local Bun: Development runtime (requires DANGEROUSLY_ALLOW_LOCAL_VM=1)

​
Web Application

Next.js dashboard for:
  • Task monitoring and logs
  • Approval management
  • Tool source configuration
  • Workspace settings
  • Member management
  • Billing (when Stripe is configured)
The web UI runs on port 5312 by default for binary installs and 4312 for source development.

​
Use Cases

​
AI Agent Execution

Enable AI agents like Claude Code to execute arbitrary TypeScript with safety controls: 
executor claude -- "analyze the codebase and fix type errors"

​
CI/CD Integration

Run tasks as part of continuous integration pipelines with approval gates for deployments.

​
API Workflow Automation

Combine multiple API calls with business logic in a single executable task: 
// Fetch from multiple sources and aggregate
const users = await fetch('/api/users');
const orders = await fetch('/api/orders');
return aggregateData(users, orders);

​
Self-Service Tooling

Provide non-technical team members with safe access to data operations via approval workflows.

​
Security Model

Executor executes untrusted code. Always review approval requests carefully and configure tool policies appropriately.

​
Sandbox Isolation

Code runs in isolated Cloudflare Worker environments with:
  • No filesystem access
  • No network access except via approved tools
  • Limited CPU and memory
  • Automatic timeout enforcement

​
Authentication & Authorization

  • WorkOS: Enterprise SSO for hosted deployments
  • Anonymous sessions: Temporary workspaces for local/development use
  • API keys: Scoped credentials for MCP clients
  • RBAC: Workspace admins and members with distinct permissions

​
Credential Management

Two storage backends:
  • Managed: Encrypted storage in Convex
  • WorkOS Vault: External encrypted credential storage

​
Next Steps

1

Install Executor

Follow the installation guide to set up Executor locally or via binary.
2

Complete the Quick Start

Execute your first task with the quick start guide.
3

Configure Your Workspace

Set up tool sources, policies, and team members in the dashboard.
4

Integrate with Your Agent

Connect your AI agent to Executor’s MCP endpoints.

​
Getting Help

GitHub

Report issues and contribute

Discord

Join the community

Build docs developers (and LLMs) love

Get started for freeTalk to us