Developer reference

The pieces you touch when you build on Warpdrive: the engine's HTTP API, the Orchestrator manifest, how MCP servers reach an Instance, and what publishing to the Store involves. Everything here is drawn from the current source.

What the engine is#

The engine is the program that runs Instances: it creates the container for each one, runs agents and Orchestrators inside it, and streams what happens. The Warpdrive CLI starts it, and the desktop app ships the same engine. It is an HTTP API on port 7777.

warpdrive serve              # headless engine on 127.0.0.1:7777
curl -s localhost:7777/api/health

In the API an Instance is a sandbox, so Instance routes live under /api/sandboxes. The port can be moved with WARPDRIVE_API_PORT.

How requests authenticate#

The engine does not have user accounts. It is protected by where it listens and, when it is shared, by one shared token:

• Local by default. It binds to 127.0.0.1, so only programs on the same computer can reach it. Browser requests are accepted only from localhost, 127.0.0.1, or [::1] origins.
• Token when shared. If WARPDRIVE_INTERNAL_API_TOKEN is set, every request must send it in the x-warpdrive-internal-token header. A missing or wrong token gets 401 with the code INTERNAL_RUNTIME_TOKEN_REQUIRED.
• No token, no network. Binding to anything other than loopback (with WARPDRIVE_API_HOST) needs that token. Without it the engine refuses to start.
• Hosted. A hosted engine is never exposed to browsers. The app reaches it through the authenticated Gateway.

GET /api/health always answers without a token, so monitors can check that the engine is up.

Main routes#

These are the main routes. :id is the Instance id returned when the Instance is created. GET /api/docs/routes lists every route.

Engine and discovery

Instances

Orchestrator

MCP servers, snapshots, and settings

Internal routes

Some routes are not for you to call directly. POST /api/shutdown and the image cleanup routes (POST /api/images/prune, DELETE /api/images/:imageId) are for administering the engine. The Orchestrator state routes under /api/orchestrator/state/* answer only requests from inside an Instance. The Sealed App broker and shared-data routes take a separate token for each App, so an App never holds the engine token.

Orchestrator manifest#

An Orchestrator lives in a Git repository. The engine clones the repository and reads warpdrive.manifest.yml from its root. Scripts and schema files named in the manifest are paths relative to that root. Point an Instance at it with { "repo": "...", "branch": "..." }, either when you create the Instance or with orchestrator/setup.

my-orchestrator/
├── warpdrive.manifest.yml   # must sit at the repository root
└── scripts/
    ├── setup.sh
    └── start-review.sh

A minimal manifest, with what each field does:

manifest: 3                        # required. Only version 3 is accepted.
name: review-crew                  # required
description: One agent writes, one reviews
version: '0.1.0'

infrastructure:
  requires: [bash, tmux, git]      # commands the Instance must have
  mcp: [serena]                    # MCP servers to start with the Instance
  environment:
    - name: GITHUB_TOKEN
      required: true               # every entry says whether it is required
      description: Used to open pull requests

setup:
  command: './scripts/setup.sh'    # required. A string or a list.

sessions:
  - name: lead
    pattern: 'lead-session'
    role: primary                  # primary | support | worker

actions:
  - id: start-review
    name: Start review
    command: './scripts/start-review.sh'
    session: lead                  # must name a declared session
    params:
      - name: branch
        type: string               # string | enum | number | boolean
        required: true

Only manifest, name, and setup.command are required. If the manifest is not valid, setup stops and the error names the field.

Studio. You do not have to write this file by hand. Studio in the app builds Orchestrators too. Use a Git repository when you want the Orchestrator versioned alongside its scripts.

Manifest fields#

MCP servers#

MCP servers give an Instance's agents extra tools. An Instance can use a server three ways: turned on for that Instance, provided by its Orchestrator, or added to your catalog as a remote server.

Turn one on for an Instance

Each Instance keeps its own list, mcpEnabled, and does not inherit it from anywhere. Send the whole list; servers you leave out are stopped.

PATCH /api/sandboxes/:id/mcp
{ "mcpEnabled": ["serena", "context7"] }

Ids come from GET /api/sandboxes/:id/mcp/catalog. If the Instance is running, new servers start right away. An unknown id is rejected with MCP_UNKNOWN. Through the Gateway (PATCH /api/warpdrive/instances/:instanceId/mcp) you send catalog GUIDs instead, and Warpdrive maps them to server ids for you.

Let the Orchestrator bring it

List server ids under infrastructure.mcp in the manifest. Setup adds them for that Instance, so anyone who uses the Orchestrator gets them.

How a server is defined

The engine's built-in servers come from the mcp-servers.yml file that ships with it. You do not edit this file; it shows the shape of an entry:

servers:
  serena:
    image: warpdrive-mcp-serena          # required
    execCommand: [serena, start-mcp-server, --project, /workspaces/sandbox]  # required
    networkType: internal                # internal (no internet) | external
    requiresWorkspace: true              # runs per Instance, with its workspace
    defaultEnabled: false                # on for new Instances?
    volumes:
      - source: '${WORKSPACE_DIR}'
        target: /workspaces/sandbox
        readOnly: false

Each entry sets exactly one of networkType or networkMode. environment, port, and shmSize are optional.

Add a remote server

You can add your own server to the catalog through the Gateway, with POST /api/warpdrive/mcp/catalog. A remote server needs a public HTTPS address with no credentials in it:

{
  "serverId": "my-tools",            // lowercase letters, digits, . _ -
  "name": "My tools",
  "url": "https://tools.example.com/mcp",
  "transport": "http",               // http | sse
  "authKind": "bearer"               // none | bearer | header (header also needs authHeaderName)
}

Store its secret separately with PUT /api/warpdrive/mcp/catalog/:recordId/credential. The app shows it only as a masked label afterwards. Then attach it to an Instance with POST /api/warpdrive/instances/:instanceId/mcp-apps/:recordId. Adding servers needs edit access to the Workspace.

Publishing to the Store#

You publish from inside the app, from the App or the Space it lives in. The app packages the App and sends:

• The package and its SHA-256 digest and size. The Store checks the digest and size before it keeps anything.
• A source revision and a lockfile digest, which pin the exact code and dependencies.
• A title, optional description and license, and the device capabilities the App may ask for (Bluetooth, location, camera, microphone).
• Dependencies: up to 32 other Store App versions, each already public, reviewed, and installable.
• Visibility: private or unlisted. The Store rejects a request to go straight to public.

An App built from a Space's own folder publishes to its owner's private Store only. A Space can also be shared as a template. You save a draft with its required and optional Apps, license, remix policy, setup needs, and supported devices, then submit it for review.

What review checks#

A new version waits for checks before anyone else can install it. Two kinds of review happen:

1. Automated checks

   Warpdrive builds the exact package and runs it. It records whether dependencies restore, the build passes, the App starts and reloads, and it meets the safety, embedding, and remote-service rules. It also checks that the App can be reached when hosted.

2. A person reviews it for the public Store

   A Warpdrive reviewer promotes a version to public only after a secret scan and a personal-data scan pass on that exact package. Space templates go through the same scans, plus a dependency check, and the reviewer must have passed a recent MFA check.

Listings stay open to reports afterwards: people can review, comment, and report an App, and moderators can archive a version.