Quick Start

This guide walks you through installing Executor and running your first task execution.

Prerequisites

You’ll need a terminal with curl and bash available. Works on Linux and macOS.

Step 1: Install Executor

Install the Executor binary with one command:

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

The installer will:

Download the executor binary for your platform
Install the managed runtime (Convex backend + web UI)
Start services in the background
Add executor to your PATH

The install takes 30-60 seconds. Grab some coffee while it sets up!

Verify Installation

Restart your terminal or source your shell rc:

source ~/.bashrc  # or ~/.zshrc for zsh users

Check that Executor is healthy:

executor doctor

You should see:

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

If services aren’t running, try executor up to start the backend manually.

Step 2: Open the Dashboard

Open the web UI in your browser:

open http://localhost:5312

Or navigate to http://localhost:5312 manually. The dashboard shows:

Tasks: Recent and running task executions
Approvals: Pending approval requests
Tools: Configured tool sources and available tools
Settings: Workspace configuration

On first launch, Executor creates an anonymous workspace. This workspace is tied to your local installation and persists across restarts.

Step 3: Execute Your First Task

Let’s run a simple task using Claude Code (or any MCP client).

Option A: Using Claude Code

If you have Claude Code installed:

executor claude -- "write a simple hello world script"

This command:

Bootstraps an anonymous MCP session
Generates temporary API credentials
Starts Claude Code with Executor’s MCP endpoint pre-configured
Disables Claude’s native Bash tool (use --allow-bash to keep it)

What does 'executor claude' do?

The executor claude command is a convenience wrapper that:

Checks if Claude Code CLI is installed
Ensures the managed backend is running
Creates an anonymous workspace session (or reuses existing)
Generates an MCP API key
Writes a temporary MCP config at /tmp/executor-claude-*/mcp.json
Launches Claude Code with:
- --mcp-config pointing to the temp config
- --strict-mcp-config to prevent config conflicts
- --append-system-prompt with Executor-specific guidance
- --disallowedTools Bash (unless --allow-bash is passed)

The temporary config looks like:

{
  "mcpServers": {
    "executor": {
      "type": "http",
      "url": "http://127.0.0.1:5411/v1/mcp/anonymous?workspaceId=...",
      "headers": {
        "x-api-key": "ek_..."
      }
    }
  }
}

Claude will use Executor’s execute tool to run code:

// Claude sends this to executor via MCP
const greeting = "Hello, World!";
console.log(greeting);
return { message: greeting };

Option B: Manual MCP Configuration

For other MCP clients, configure manually:

Get your MCP credentials

Run this to bootstrap an anonymous session and get credentials:

executor doctor --verbose

Note the MCP endpoint URL.

Configure your MCP client

Add Executor as an MCP server in your client’s config:

mcp.json

{
  "mcpServers": {
    "executor": {
      "type": "http",
      "url": "http://127.0.0.1:5411/v1/mcp/anonymous?workspaceId=<your-workspace-id>",
      "headers": {
        "x-api-key": "<your-api-key>"
      }
    }
  }
}

Use the execute tool

Call the execute tool from your agent:

// Tool call parameters
{
  "code": "return 'Hello from Executor!';",
  "description": "Test execution"
}

Option C: API Direct Call

You can also call the MCP endpoint directly via HTTP:

curl -X POST http://127.0.0.1:5411/v1/mcp/anonymous?workspaceId=<workspace-id> \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "execute",
      "arguments": {
        "code": "console.log('Hello!'); return { success: true };",
        "description": "Test task"
      }
    },
    "id": 1
  }'

Step 4: View Task in Dashboard

Switch to your browser and refresh the dashboard. You should see your task execution:

Status: Completed (green) or Running (blue)
Code: The TypeScript that was executed
Output: Console logs and return value
Duration: How long the task took

Step 5: Try Tool Invocation

Now let’s execute code that calls external tools.

Add a Tool Source

Go to Tools page

Click Tools in the dashboard sidebar

Add a tool source

Click Add Tool Source and enter:

Type: openapi
URL: https://api.github.com/openapi.json
Name: github-api

Save and sync

Click Save. Executor will fetch and parse the OpenAPI spec, creating tools for each endpoint.

Tool discovery happens asynchronously. Refresh the page after a few seconds to see discovered tools.

Execute Code Using Tools

Now use Claude Code to call GitHub API:

executor claude -- "use the github api to fetch my user profile"

Claude will:

Discover the github__get_user tool (auto-generated from OpenAPI)
Execute code that invokes the tool:

// Claude generates something like:
const profile = await tools.github__get_user({
  username: 'your-username'
});

return profile;

Executor runs the code, intercepts the tool call, and executes it
Returns the API response to your code

Step 6: Set Up Approval Workflows

For sensitive operations, you can require manual approval.

Create an Approval Policy

Go to Tools

Open the Tools page in the dashboard

Find a tool

Locate a sensitive tool (e.g., github__delete_repo)

Set policy

Click the tool and set policy to Require Approval

Trigger an Approval

Run code that uses the restricted tool:

executor claude -- "delete the test repository"

The task will:

Start executing
Pause when it reaches the github__delete_repo tool call
Create an approval request

Review and Approve

Check Approvals page

Click Approvals in the dashboard

Review the request

See:

What tool is being called
What arguments are being passed
The full task code and context

Approve or Deny

Click Approve to allow execution, or Deny to cancel

The task resumes immediately after approval and completes.

Set tools to Deny to completely block them, or Auto-allow to skip approval gates.

What’s Next?

Task Execution

Learn about task lifecycle and management

Tool Sources

Add MCP servers, OpenAPI specs, and GraphQL schemas

Access Policies

Configure fine-grained approval rules

Credentials

Store API keys and secrets for tools

Common Tasks

Stop Services

Stop the background backend and web UI:

executor down

Restart Services

Restart if services crashed or you changed config:

executor down
executor up &
executor web &

View Logs

Tail service logs:

# Backend logs
tail -f ~/.executor/runtime/logs/backend.log

# Web UI logs
tail -f ~/.executor/runtime/logs/web.log

Upgrade Executor

Update to the latest version:

executor upgrade

Check Health

Run diagnostics:

executor doctor --verbose

Troubleshooting

Claude Command Not Found

If executor claude says Claude is not installed:

# Install Claude Code CLI
curl -fsSL https://claude.ai/install.sh | bash

Services Not Running

If executor doctor shows services aren’t running:

# Start backend
executor up

# Start web in another terminal
executor web

Port Already in Use

Change ports if defaults conflict:

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

Task Execution Failed

Check the task detail in the dashboard for:

Error messages in output
Tool call failures (auth errors, rate limits)
Timeout issues (increase with timeoutMs parameter)

Can’t Access Dashboard

If web UI doesn’t load:

Check web service is running:
```
curl http://127.0.0.1:5312
```
Check logs:
```
cat ~/.executor/runtime/logs/web.log
```
Restart web UI:
```
executor web
```

Tips and Tricks

Use --allow-bash for system commands

Keep Claude’s Bash tool enabled while using Executor:

executor claude --allow-bash -- "list files and analyze them"

Claude can now use both Bash and Executor’s execute tool.

Pass arguments to Claude

Pass any Claude Code flags after --:

executor claude -- --model sonnet "write a parser"

Run backend in foreground for debugging

See real-time backend logs:

executor up  # runs in foreground, Ctrl+C to stop

Preserve data across reinstalls

Your workspace data lives in ~/.executor/runtime/convex-data/.Back it up before uninstalling:

cp -r ~/.executor/runtime/convex-data ~/executor-backup

Use multiple workspaces

The binary install creates one anonymous workspace by default.For multiple workspaces, use the hosted version at executor.sh or run from source with multiple Convex deployments.

Next Steps

You now have Executor running and executing tasks! Here’s what to explore next:

Configure tool sources

Add MCP servers, OpenAPI specs, and GraphQL schemas to expand available tools.

Set up credentials

Store API keys and authentication secrets for tools that need them.

Invite team members

Add collaborators to your workspace (hosted version only).

Integrate with your agent

Wire up Executor’s MCP endpoint to your AI agent or automation workflow.

Join the Community

Get help, share workflows, and connect with other Executor users.

Get Started

Core Features

Deployment

Integrations

​Quick Start

​Prerequisites

​Step 1: Install Executor

​Verify Installation

​Step 2: Open the Dashboard

​Step 3: Execute Your First Task

​Option A: Using Claude Code

​Option B: Manual MCP Configuration

​Option C: API Direct Call

​Step 4: View Task in Dashboard

​Step 5: Try Tool Invocation

​Add a Tool Source

​Execute Code Using Tools

​Step 6: Set Up Approval Workflows

​Create an Approval Policy

​Trigger an Approval

​Review and Approve

​What’s Next?

Task Execution

Tool Sources

Access Policies

Credentials

​Common Tasks

​Stop Services

​Restart Services

​View Logs

​Upgrade Executor

​Check Health

​Troubleshooting

​Claude Command Not Found

​Services Not Running

​Port Already in Use

​Task Execution Failed

​Can’t Access Dashboard

​Tips and Tricks

​Next Steps

Join the Community

Build docs developers (and LLMs) love

Quick Start

Prerequisites

Step 1: Install Executor

Verify Installation

Step 2: Open the Dashboard

Step 3: Execute Your First Task

Option A: Using Claude Code

Option B: Manual MCP Configuration

Option C: API Direct Call

Step 4: View Task in Dashboard

Step 5: Try Tool Invocation

Add a Tool Source

Execute Code Using Tools

Step 6: Set Up Approval Workflows

Create an Approval Policy

Trigger an Approval

Review and Approve

What’s Next?

Common Tasks

Stop Services

Restart Services

View Logs

Upgrade Executor

Check Health

Troubleshooting

Claude Command Not Found

Services Not Running

Port Already in Use

Task Execution Failed

Can’t Access Dashboard

Tips and Tricks

Next Steps