Autopilot Runners

Autopilot runners are coding agents that execute on your infrastructure. Claude Code and OpenCode can stay live as persistent capacity; Cursor is interactive; Antigravity and Grok Build are on-demand. Runtime shape changes presence and invocation, not implementation authority. No runner receives routed action-item work merely because it is online.

One work-entry contract for every runner

Implementation begins only from a current explicit user request, a server-authorized exact-target canonical conversation command from the connection owner or an authorized delegate, or a direct user invocation naming the work. The agent never infers permission from backlog discovery.

For requested action items every provider follows the same sequence:

1. reserve_work_items with the requested ids in order;
2. claim_work_item for one reserved item at a time;
3. implement in an isolated branch/worktree and run configured checks;
4. commit with [devspec:<id>]; and
5. call record_implementation with the final commit and evidence.

The database still contains internal assignment/reservation names for compatibility. Those records coordinate claims only; they are not delivery messages or implementation authority. Automation runs are a separate owner-scoped surface.

Runner types

Prerequisites

• A DevSpec project with the repository connected.
• A local checkout with Git authentication.
• A read-write MCP token from You → Connections.
• The provider's DevSpec plugin, extension, or skills.
• Project settings for target branch, branch prefix, checks, and protected paths.

MCP connection

Use the provider's HTTP MCP configuration with your DevSpec bearer token.

Claude Code / compatible clients

{
  "mcpServers": {
    "devspec": {
      "type": "http",
      "url": "https://devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Antigravity uses serverUrl:

{
  "mcpServers": {
    "devspec": {
      "type": "http",
      "serverUrl": "https://devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Use the URL for the environment where the token was created.

Claude Code and OpenCode persistent capacity

Start the installed Autopilot workflow from the repository. To request a known batch, name the ids explicitly:

/autopilot.start --items=ID1,ID2,ID3

The direct invocation is the user request. The runner reserves exactly those ids in that order and claims them one at a time. It must report unavailable ids rather than replace them with unrelated backlog items.

A no-item launch may keep the connection present/listening, depending on the host version, but presence alone grants no implementation authority. Use DevSpec Send to issue a server-authorized exact-target command that names the work, or invoke the named-item surface locally.

For OpenCode, /devspec.remote --session <uuid> attaches the connection to a room. Commands are per-message server decisions: exact target plus the connection's current command_authority. An authorized delegated human command is actionable; ordinary room posts remain advisory.

Cursor interactive runner

Use classic Cursor IDE Agent chat and invoke DevSpec: Work on action item or the equivalent skill prompt with the item id. For a batch, include the ordered ids explicitly. The user invocation is authority; the agent still calls reserve_work_items and then claim_work_item rather than treating the prompt as a claim.

After changing MCP configuration, open a new Agent chat so Cursor loads the current server tools. The Agents Window is a separate host surface and should not be assumed to share the classic chat's MCP/wake behavior.

Antigravity on-demand runner

From the project directory, invoke the installed work skill with a named item:

/devspec-work <action-item-id>

For several items, ask the skill to process the explicit ordered list. Each invocation reserves only the requested ids, claims one at a time, records its result, and exits. Do not ask it for an unspecified "next" item.

Grok Build on-demand runner

Run the installed DevSpec work skill interactively or headlessly with named item ids:

grok --always-approve -p 'Use the DevSpec work skill for item <action-item-id>'

For a batch, put the explicit ordered ids in the prompt. --always-approve is host tool-approval behavior; it does not create DevSpec implementation authority beyond the user's named request.

Remote control and delegated commands

A connection can be sessionless or attached. A sessionless connection is available capacity for conversation/control/automations, not an action-item inbox. An attached connection receives shared room context plus commands addressed to its exact identity.

The server sets remote_control.is_controller_instruction=true only when:

• the message is an explicit command;
• its target matches this connection; and
• its human author is currently authorized by the connection's command_authority as owner, project member, or named allowlist delegate.

The actual requester is preserved in server-stamped provenance. Hosts must not reclassify delegated requests as owner requests.

Project settings

All runners consume the same post-authority constraints:

• target branch and branch prefix;
• auto-push / auto-merge;
• typecheck, unit, E2E, and other configured checks;
• protected paths;
• project agent instructions.

These settings shape implementation after a request is authoritative. They do not select or send work.

Troubleshooting

• No implementation request: name the item ids through the provider's direct work surface or an authorized exact-target Send command.
• Item unavailable: another agent may hold it or a dependency/conflict/assignee guard may reject the claim. Follow the returned reason; never substitute unrelated work.
• Command remains advisory: verify exact target, current project membership/grant, and the connection's command_authority.
• MCP unavailable: verify the token, URL, and provider config; reopen/restart the host where required.
• Repository mismatch: align the local repository and target branch or use an explicit accepted override.
• No merge/push: inspect project settings and Git credentials after tests pass.

Historical note

Older plugins exposed filters for a staged backlog and commands labelled "process next staged item." Those labels and old database states may appear in historical releases, but they are not the current work-entry contract. Current hosts need an explicit user request and must reserve the named ids before claiming them.