# Quickstart

> Run `executor install`, open the web UI, add a first integration, search and call a tool, and resume a paused execution.

- Repository: RhysSullivan/executor
- GitHub: https://github.com/RhysSullivan/executor
- Human docs: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052
- Complete Markdown: https://grok-wiki.com/public/docs/rhyssullivan-executor-564383868052/llms-full.txt

## Source Files

- `README.md`
- `apps/docs/local/cli.mdx`
- `apps/cli/src/main.ts`
- `apps/local/package.json`
- `packages/core/api/src/tools/api.ts`
- `packages/core/api/src/executions/api.ts`

---

---
title: "Quickstart"
description: "Run `executor install`, open the web UI, add a first integration, search and call a tool, and resume a paused execution."
---

`executor install` registers a loopback HTTP runtime as an OS-supervised background service (launchd on macOS, systemd user unit on Linux, Task Scheduler on Windows). The supervised daemon binds `127.0.0.1` on port `4789` by default, persists state under `~/.executor`, and publishes a `server.json` manifest that CLI commands and `executor web` read for the live origin and bearer token.

<Note>
Requires Node.js 20 or newer and the published `executor` npm package. `executor install` needs the compiled binary; in a dev checkout, run `executor daemon run --foreground` instead.
</Note>

## What you will set up

| Step | Command or surface | Outcome |
| --- | --- | --- |
| Install | `executor install` | Durable local daemon with web UI and HTTP API |
| Browse | `executor web` | Signed-in browser session at `{origin}/?_token=…` |
| Integrate | Web **Connect** dialog or `executor call … addSource` | First OpenAPI, GraphQL, or MCP integration indexed |
| Invoke | `executor tools search`, `executor call` | Tool discovery and execution via QuickJS sandbox |
| Resume | Web `/resume/{id}` or `executor resume` | Continue a paused auth or approval execution |

## Install the background service

<Tabs>
  <Tab title="npm">
    ```bash
    npm install -g executor
    executor install
    ```
  </Tab>
  <Tab title="pnpm">
    ```bash
    pnpm add -g executor
    executor install
    ```
  </Tab>
  <Tab title="bun">
    ```bash
    bun add -g executor
    executor install
    ```
  </Tab>
</Tabs>

<Steps>
  <Step title="Run install">
    ```bash
    executor install
    ```

    Optional: pick a different loopback port.

    ```bash
    executor install --port 4790
    ```

    <ParamField body="--port" type="integer" default="4789">
      Port the supervised daemon binds on loopback. Clients discover the live port from `~/.executor/server-control/server.json` when it differs.
    </ParamField>

    Expected output includes the service manager name, web UI origin, data directory, and log path:

    ```text
    Installing Executor as a background service...
    Service manager: launchd
    Web UI:          http://127.0.0.1:4789
    Data directory:  /Users/you/.executor
    Logs:            /Users/you/.executor/logs
    ...
    Executor is now running as a background service at http://127.0.0.1:4789.
    Open it in your browser, already signed in, with:  executor web
    ```
  </Step>

  <Step title="Verify the service">
    ```bash
    executor service status
    ```

    A healthy install reports `Registered: yes`, `Running: yes`, and a `Serving:` line with the manifest origin.

    The unauthenticated liveness probe is `GET /api/health` returning `ok`.
  </Step>
</Steps>

<Warning>
If the default port is taken during auto-started daemon boot (for example when `executor call` spawns a foreground daemon), the CLI selects the next available port and prints a notice. Always read the origin from `server.json` or `executor service status` when ports may differ.
</Warning>

## Open the web UI

```bash
executor web
```

By default, `executor web` does not start a new server. It reads the active local `server.json` manifest and opens `{origin}/?_token={bearer}` in your default browser so you arrive already authenticated.

| Command | Behavior |
| --- | --- |
| `executor web` | Open the installed background service |
| `executor open` | Same as `executor web` |
| `executor web --foreground` | Start a temporary server in the current terminal (default port `4788`) |

<Tip>
If nothing is running, `executor web` prints install instructions. For a one-off session without OS registration, use `executor web --foreground`.
</Tip>

From the web UI you can browse **Integrations**, inspect **Tools**, configure policies, and use the **Connect** card to wire MCP clients.

## Add a first integration

Executor registers tenant-scoped integrations (OpenAPI specs, GraphQL endpoints, MCP servers) and indexes their tools per connection. Add one from the web UI or CLI.

<Steps>
  <Step title="Add from the web UI">
    1. Open the **Integrations** page.
    2. Click **Connect** (or use the command palette: **Add integration**).
    3. In the **Connect an integration** dialog, paste a spec or endpoint URL, or pick a preset.
    4. Executor auto-detects the type (OpenAPI, GraphQL, MCP, Google Discovery) and routes you to the plugin add form with the URL prefilled.
    5. Submit the form. On success you land on the integration detail page with indexed tools.

    Supported detection kinds map to plugins: `openapi`, `graphql`, `mcp`, and `googleDiscovery`.
  </Step>

  <Step title="Add from the CLI (Petstore example)">
    Register the Swagger Petstore OpenAPI spec:

    ```bash
    executor call executor openapi addSource '{
      "spec": "https://petstore3.swagger.io/api/v3/openapi.json",
      "namespace": "petstore",
      "baseUrl": "https://petstore3.swagger.io/api/v3"
    }'
    ```

    Use `baseUrl` when the OpenAPI document declares relative `servers` entries (for example `"/api/v3"`).

    Confirm the integration is live:

    ```bash
    executor tools sources
    ```

    Expected output lists configured sources with tool counts for each integration slug.
  </Step>
</Steps>

<Info>
Integrations are catalog identities; connections bind owner-scoped credentials to them. The Petstore demo needs no auth template. Integrations that require OAuth or API keys need a connection before tools can run. See [Configure credentials](/configure-credentials).
</Info>

## Search and call a tool

CLI tool commands compile TypeScript snippets and run them through `POST /executions`. `executor call`, `executor resume`, and `executor tools …` auto-start a localhost daemon when no supervised service is reachable and no explicit remote credential is configured.

### Search by intent

```bash
executor tools search "list pets"
```

Optional filters:

<ParamField body="--namespace" type="string">
  Restrict search to one integration slug (for example `petstore`).
</ParamField>

<ParamField body="--limit" type="integer" default="12">
  Maximum matches returned.
</ParamField>

### Browse namespaces

```bash
executor call petstore --help
executor tools describe petstore.org.main.pets.listPets
```

`executor call <path…> --help` walks the tool tree. Add `--match "<text>"` and `--limit <n>` to narrow large namespaces.

### Invoke a tool

```bash
executor call petstore org main pets listPets '{}'
```

Path segments map to the sandbox `tools` proxy (`tools.petstore.org.main.pets.listPets`). Pass a JSON object as the final argument.

<RequestExample>
```bash
executor call petstore org main pets listPets '{}'
```
</RequestExample>

<ResponseExample>
```json
[
  { "id": 1, "name": "doggie", "status": "available" }
]
```
</ResponseExample>

### Tool addresses

Persisted tools use connection-aware addresses:

```text
tools.<integration>.<owner>.<connection>.<tool>
```

Example: `tools.petstore.org.main.pets.listPets`. The HTTP catalog exposes these via `GET /tools` and `GET /tools/schema?address=…`.

## Resume a paused execution

Tool calls that need user auth, form input, or policy approval suspend inside the QuickJS sandbox. The executions API returns `status: "paused"` with an `executionId` and interaction metadata. Resume through the web UI or CLI.

```mermaid
stateDiagram-v2
  [*] --> Running: POST /executions
  Running --> Paused: tool elicitation or approval
  Paused --> Running: POST /executions/:id/resume
  Running --> Completed: sandbox finishes
  Paused --> Completed: decline or cancel
  Completed --> [*]
```

### When a call pauses

A paused CLI invocation prints the pause reason, a browser approval URL, and CLI fallback commands:

```text
Approval required for tools.petstore.org.main.pets.addPet.

Approve in browser:
  http://127.0.0.1:4789/resume/exec_abc123

CLI fallback:
  executor resume --execution-id exec_abc123 --action accept
  executor resume --execution-id exec_abc123 --action decline
  executor resume --execution-id exec_abc123 --action cancel
```

Form elicitation also prints a `--content` JSON template when the interaction carries a `requestedSchema`.

### Resume in the browser

Open `/resume/{executionId}` on your Executor origin. The approval page loads the paused execution via `GET /executions/:executionId` and submits `POST /executions/:executionId/resume` when you approve, decline, or cancel.

### Resume from the CLI

```bash
executor resume --execution-id exec_abc123 --action accept
```

<ParamField body="--execution-id" type="string" required>
  Execution ID from the paused response.
</ParamField>

<ParamField body="--action" type="accept | decline | cancel" default="accept">
  Interaction response sent to the executions resume endpoint.
</ParamField>

<ParamField body="--content" type="string">
  JSON object for `action=accept` when the pause requested structured input.
</ParamField>

:::endpoint POST /executions/:executionId/resume
Resume a paused sandbox execution.

**Payload**

| Field | Type | Description |
| --- | --- | --- |
| `action` | `"accept"` \| `"decline"` \| `"cancel"` | User decision |
| `content` | object (optional) | Structured input when accepting a form elicitation |

**Response**: Same union as execute: `completed` with `text`, `structured`, `isError`, or another `paused` result if a subsequent approval is required.
:::

<Check>
After resume completes, the CLI prints the final tool output and exits `0`. If another approval gate appears, it prints the next `/resume/{id}` URL.
</Check>

## Quick reference

| Task | Command |
| --- | --- |
| Install service | `executor install` |
| Open UI | `executor web` |
| List integrations | `executor tools sources` |
| Search tools | `executor tools search "<query>"` |
| Call tool | `executor call <path…> '<json>'` |
| Resume pause | `executor resume --execution-id <id>` |
| Service health | `executor service status` |
| Foreground dev server | `executor web --foreground` |

<AccordionGroup>
  <Accordion title="executor web says Executor is not running">
    Run `executor install`, then `executor web` again. For a throwaway session, use `executor web --foreground`.
  </Accordion>
  <Accordion title="Install fails in a dev checkout">
    `executor install` requires the compiled binary. From source, run `executor daemon run --foreground` and open the printed origin manually.
  </Accordion>
  <Accordion title="Resume says execution not found">
    Paused executions are session-scoped. The pause may have already been resolved, or the daemon restarted. Re-run the original tool call to generate a fresh execution ID.
  </Accordion>
  <Accordion title="Override data directory or auth">
    Set `EXECUTOR_DATA_DIR` before install to relocate `~/.executor`. Remote targets accept `EXECUTOR_API_KEY` or `EXECUTOR_AUTH_TOKEN`. See [Configuration reference](/configuration-reference).
  </Accordion>
</AccordionGroup>

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Global install paths, dev bootstrap, ports, and data directory layout.
  </Card>
  <Card title="Add integrations" href="/add-integrations">
    OpenAPI, GraphQL, and MCP registration from the UI and CLI with post-add verification.
  </Card>
  <Card title="Tools" href="/tools">
    Tool addresses, discovery, schema inspection, and invocation across surfaces.
  </Card>
  <Card title="Executions" href="/executions">
    Code-mode execution, pause reasons, HTTP routes, and MCP elicitation handling.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full `executor` subcommands, flags, and auto-start behavior.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Port conflicts, unreachable servers, OAuth behind proxies, and recovery commands.
  </Card>
</CardGroup>