Paperclip Runner

Use paperclip_runner when you want Paperclip's native run lifecycle, durable session recovery, and built-in task tools. You select the provider separately from the adapter, then configure model access and the execution environment.

Paperclip Runner is experimental. Its enableNativeRunner setting is on by default for self-hosted instances and off by default for Cloud-managed instances. Deployment settings can override those defaults. An enabled flag does not convert your existing agents: onboarding and direct adapters keep their own execution paths.

Before you start

• An instance with Paperclip Runner enabled under Settings → Experimental.
• An active agent and a task in standard, planning, or ask work mode.
• A prepared execution environment and compatible model credential.
• The pinned runtime required by the selected provider.

For source development, an enabled Runner requires a Rust toolchain or PAPERCLIP_RUNNER_BINARY; the development launcher builds the daemon when needed. Published distributions and execution images provide their own runtime assets.

Choose a provider

Cursor, GitHub Copilot, and Pi appear as qualification-pending ACP choices and are disabled for production runs. The Provider list also offers Grok Build directly, which saves the same acpx provider with acpxAgent: "grok". Selecting an arbitrary executable does not create a qualified profile. Historical ACP Codex settings normalize to the native Codex provider when saved.

Managed providers need operator-prepared profiles; they are not configured by pasting a general model API key into the provider selector. See Managed and remote agent profiles.

Configure an agent

1. Create or edit the agent and choose Paperclip Runner.
2. Select Provider. For ACP agents, select the ACP agent too.
3. Select a model. When you edit a saved agent, choose a compatible Connection for Codex, OpenCode, Claude, or Grok.
4. Choose the execution environment and review permissions.
5. Save and use Test Environment before assigning work.

A minimal Codex configuration uses:

{
  "adapterType": "paperclip_runner",
  "adapterConfig": {
    "provider": "codex",
    "model": "gpt-5.6-sol",
    "codexPermissionMode": "never"
  }
}

The credential binding is configured separately, through the agent's Connection.

Permissions

Company permissions, governed approvals, and budgets still apply. Grok cannot automatically approve Paperclip tool calls under the narrower ACP modes; those requests wait for approval.

Sessions and task modes

The Runner records native session identity and recovers through the provider's supported session-load path. Recovery rechecks the saved provider, environment, credential, and task authority; a durable run is not a guarantee that every interrupted provider operation can resume.

Standard, planning, and ask tasks are supported.

Existing cursor, grok_local, claude_local, codex_local, and opencode_local agents remain direct adapters until you explicitly choose Runner. A saved obsolete native-runner toggle on a direct adapter does not switch fresh runs to this path.

Current limits

• Grok's native Runner usage accounting is not qualified. Do not infer zero spend from a missing cost.
• ACP live steering is unsupported. Follow-up work uses the controller's queue instead of claiming provider-native queueing.
• Native session capabilities differ by provider. Session load does not imply native fork or resume methods are available.
• Environment readiness and model access are separate. A successful installation check does not prove that the provider accepts a paid run.

Sandbox images and runtime versions

When native Codex runs in a remote sandbox, the Runner checks the Codex version installed there before it starts. Any stable release from 0.149.0 up to but excluding 0.161.0 is accepted, so an image doesn't have to match the 0.160.0 install pin exactly; a compatible version that differs from the pin is noted in the run log. A version outside that window, or a prerelease, stops the run with runner_remote_provider_artifact_incompatible. The message tells you to install a supported stable Codex release or set PAPERCLIP_RUNNER_REMOTE_CODEX_NPM_SPEC to the pinned package.

If you build your own sandbox images, keep two things in mind when you upgrade:

• Deploy first, then promote the image. Upgrade the Paperclip controller and Runner before you promote a sandbox image that carries the new runtime pins. Older controllers reject the new provider-pack pins.
• Rebuild old Claude Code images for Sonnet 5.5. An image built with Claude Code older than 2.1.284 must be rebuilt before Claude Sonnet 5.5 works on the CLI path. See the Claude Code model requirements.

Running several Runners on one machine

When a sandbox provider starts the Runner daemon (paperclip-runnerd) in listener mode, it listens on port 43127 by default. If you run more than one listening Runner on the same machine, give each its own port with --listen-port — any value from 1 to 65535. The Runner still binds to 0.0.0.0, accepts connections only on its run-specific path, and keeps the same authentication. A warm Runner that's reattached keeps the port it started with; asking it to switch ports is rejected.

Next steps

• Grok Local and native Grok
• Adapters overview