d627632874
Docs for parent release `v2026.1106.0` (`d69631b0`), up from `v2026.1023.0` (`1b4c8038`): 515 parent commits. ## How this branch was built The tag is 914 commits behind what `nightly` has drafted, so this branch isn't cut from `nightly` HEAD. It starts at nightly commit `1952052` (parent `043f2514`), 19 commits before the tag, then adds: - the `main` hotfix (#160) - the sync tooling from `nightly` - docs for those 19 commits Later nightly drafts stay on `nightly`, so no pages had to be removed. No `nightly-draft/*` PRs are open. ## What changed - **Runner by default:** new Claude, Codex, OpenCode and Pi agents start on Paperclip Runner on supported hosts, with **Legacy runner** and **Upgrade runner**. - **Workspaces:** cleanup of finished workspaces, optional Git expiration, and restore points for unsaved work. Restore points are off by default. - **New pages:** Prompt injection prevention, Google Workspace, GitHub Copilot, Speko, Braintrust, Daytona, Ditto and Unikraft. - **Breaking and upgrade notes:** the run history limit, Sentry run failures off by default and the DSN variables, the Docker start command for custom images, `--yes` on `instructions-file:delete`, and slower migrations on large instances. - **Also covered:** project repositories as skill sources, roster bulk edit, Artifacts V1 (experimental, off by default), composer dismissal, `expectedStatusVersion`, `unexecuted_review_stage`, and plugin workspace providers. - **Changelog:** a v2026.1106.0 entry in `reference/changelog.md`. ## Older text corrected These were wrong at the tag, and most are also wrong on the live site: - which permissions let an agent read a peer's configuration or change instructions (`api/agents.md`) - `decideNowCount`, which doesn't exist; the field is `deskBadgeCount` - `file-resources` routes, which are board-only - the **Create project** dialog fields, a CEO rule the code doesn't enforce, and where a terminated agent's reports appear - `instructions-file:put` and `:delete` examples that always failed (`cli/agent.md`) - a curl example that returned `422` (`api/cases.md`) - Google Workspace **Reconnect** instructions, which claimed it reopens the service picker - the `permissionKey` table, which listed 8 of 21 keys - drafting text at the end of `api/agents.md` ## ⚠ Please check these - **Product behaviour that may be a parent bug.** The docs now describe the tag's code, which you may prefer to fix upstream: - The project **Environment** dropdown saves a choice, but runs ignore it (`experimental/environments.md`). - `environments:manage` is granted by roles but no environment route checks it. - `suggest-changes` is documented as agent-only, because only agents have a consent path. Company skill policy decides skill edits. - **Reader-visible mismatches in the parent UI.** The docs follow the code. Upstream copy still mentions a "Built-in agents tab", says Copilot "awaits qualification", and tells people to "Reconnect Google Workspace to change access". ## ⚠ Post-tag leaks removed Nothing to remove from an already-drafted page: post-tag surfaces such as 1Password, Vercel, Supabase deploy, custom gateway onboarding and Artifacts V1 as default never came onto this branch. Authors left out post-tag hunks of the next nightly draft, and the reasons are in the run notes. ## ⚠ Drift None. Zero findings at the tag, from a full parent snapshot. ## ⚠ Verification Failures The tag-accuracy gate reports one leak and nine review entries. None is a real failure: - **Leak:** `reference/cli/service.md`, `paperclipai payload and`. This is a false positive; it's prose from a real message at `cli/src/commands/service.ts:184`. - **Review, 8 new connector pages:** the gate can't confirm new pages. Reviewers confirmed each surface exists at the tag. - **Review, `local_tools`:** an example value from the tag's Runner README. Not provable from code, and kept deliberately: - `sandbox-providers.md` uses `sandbox.yaml`. The tag's README says `install.yaml`, which returned 404 when checked. The upstream fix is post-tag. - The Google Workspace row about older OAuth brokers rests on release notes and a design doc. The broker isn't in this repo. - External claims about provider behaviour (for example Braintrust, Daytona, Unikraft and Google scopes). ## ↻ Renames detected None. The rename helper wasn't run: the 19-commit delta adds no new adapter, skill, or plugin directories that it would check. ## Verification All checks read a checkout pinned to the tag. - **First round:** authors, a release-notes audit, an audit of corrections stranded on `nightly`, an audit of 321 lines the last realign dropped from `main` (about 130 checked directly in code), and six fresh verifiers. - **Second round:** seven new verifiers re-checked every changed area, tracing behaviour rather than matching labels, and fixed about 50 more defects. That volume means more may remain. - **Limits of that second round:** - Each verifier reported what it only string-matched. That includes parts of Artifacts V1, the **Upgrade runner** notice, Copilot run behaviour, and some Plugin SDK contract text. - The second-round fixes themselves weren't reviewed by a third round. - **Gates:** `docs:build`, `docs:test` and `sync:check` pass. - **Nothing was run against a live instance.** All of this comes from reading code. ## Screenshots **196 of 278 screenshots are stale and none were recaptured.** The list is in `SCREENSHOTS_PENDING.md`. Some visibly differ from the text, such as the removed **Run with provider trace** button and the old roster tabs. ## After merge 1. Keep the PR title as is: `tag-docs-release.yml` reads the version from it. 2. Confirm the `docs/v2026.1106.0` tag exists. 3. Run `node scripts/sync/realign-nightly.mjs release/v2026.1106.0 --push`, then audit for dropped lines and duplicated paragraphs, and set `nightly` state back to `branch_mode: nightly`. 4. Check that `docs.paperclip.ing` serves the release: a new page, a new claim, and the changelog's top entry. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Dotta <[email protected]> Co-authored-by: ClaudeCoder <[email protected]>
17 KiB
paperclip_version, seo_title, seo_description
| paperclip_version | seo_title | seo_description |
|---|---|---|
| v2026.1106.0 | Choosing an Agent Adapter | Compare the adapters that run your agents — Claude Code, Codex, OpenCode, HTTP webhook and more — and pick the right bridge for each role you hire. |
Agent Adapters
When you create an agent in Paperclip, one of the first things you configure is its adapter. The adapter is the bridge between Paperclip and the AI system that actually runs your agent — it tells Paperclip how to launch the agent, how to pass it work, and how to receive results back.
Think of it like a power adapter for different countries. The electricity (Paperclip's task system and org chart) is the same everywhere, but the plug you need depends on the socket (the AI runtime you're connecting to). Claude Code needs one configuration, OpenAI Codex needs another, and a custom cloud-based agent needs a third.
Without an adapter, an agent is just a record in a database. With one, it's a working member of your team.
Adapter comparison
| Adapter | Best for | Requires |
|---|---|---|
claude_local |
Most users — runs Claude on your Mac | Claude Code installed, Anthropic API key |
codex_local |
OpenAI users — runs Codex on your Mac | Codex CLI installed, OpenAI API key |
gemini_local |
Gemini users — runs Gemini CLI on your Mac | Gemini CLI installed, Google credentials |
opencode_local |
Multi-provider flexibility, switchable models | OpenCode CLI installed, relevant API keys |
cursor |
Cursor Agent CLI with resumable local runs | Cursor Agent CLI installed and authenticated |
paperclip_runner |
Native sessions and Paperclip task tools | Runner enabled, prepared execution environment, compatible provider credential |
pi_local |
Pi users wanting Pi's built-in tool set | Pi CLI installed, relevant API keys |
grok_local |
xAI users — runs the Grok Build CLI | Grok CLI installed, xAI API key or SuperGrok login |
hermes_local |
Persistent memory, 30+ tools, 80+ skills | Hermes Agent installed (Python 3.10+) |
For most people getting started, claude_local is the right choice. It runs directly on your Mac using the same Claude that powers Anthropic's Claude.ai, and it only needs Claude Code plus an API key wired through environment variables.
Note: On Paperclip Cloud, the new-agent picker offers Claude, Codex, OpenCode, and Grok. Grok agents connect with an xAI subscription or API key during setup.
Tip: Grok Build can also run on the experimental Paperclip Runner adapter (
paperclip_runner) — choose Grok Build as the provider. It needs Grok Build installed at a fixed path in the execution environment. See Grok Build on Paperclip Runner.
Choose Paperclip Runner explicitly
For the native lifecycle, choose Paperclip Runner and then select the provider: Codex, OpenCode, Claude Managed, AWS AgentCore, ACP agents, or Grok Build. Under ACP agents, you can pick Grok Build, Claude, Cursor, GitHub Copilot, or Pi. To run agents on your Copilot plan, see GitHub Copilot. Existing direct-adapter agents keep their current runtime until you change the adapter.
You don't have to do anything for Codex, Claude Code, OpenCode, or Pi: a new agent on one of those harnesses runs on Paperclip Runner automatically when it runs on macOS or on Linux x64/ARM64 with GNU libc 2.39 or newer (OpenCode and Pi stay on the Legacy runner on Linux ARM64). To keep the classic codex_local, claude_local, opencode_local, or pi_local adapter, open Advanced and set Runner to Legacy runner. See New Codex and Claude agents use the Runner.
Already have a Claude Code or Codex agent on the Legacy runner? If its environment qualifies, its Harness / Runtime page shows an Upgrade to Paperclip Runner notice. Click Upgrade runner to switch while keeping its model, account, and compatible settings. See Upgrade an existing Claude or Codex agent.
The Runner is experimental: for providers other than Codex, OpenCode, ACP Claude, ACP Pi, and ACP GitHub Copilot, enableNativeRunner defaults to on for self-hosted instances and off for Cloud-managed instances. Cursor needs a prepared pinned runtime (paperclipai runtime setup cursor), an explicit model, and an Agent, Plan, or Ask session mode. Its token totals and per-run dollar cost are unavailable. See Paperclip Runner and native Cursor setup.
Agents run in full auto by default
Agents do their work while nobody is watching, so there's no one around to answer "may I run this command?" prompts. That's why the coding adapters start in full-auto mode: Claude Code, Codex, OpenCode, and Gemini CLI agents use their tools — including tools from connected services such as MCP servers — without stopping to ask for approval.
You can dial this back per agent in the adapter's configuration. Each adapter reference page explains its own switch:
- Claude Code —
dangerouslySkipPermissions(see Claude Code permissions) - Codex —
dangerouslyBypassApprovalsAndSandbox(see Codex permissions) - OpenCode —
dangerouslySkipPermissions(see OpenCode)
Tip: Full auto is about approval prompts, not about what an agent is allowed to do in your company. Company permissions, budgets, and approval requirements still apply.
Claude Code (claude_local)
The claude_local adapter runs your agent using Claude Code — Anthropic's command-line AI tool — directly on your Mac. When Paperclip triggers a heartbeat, it launches Claude Code with the agent's context and task, waits for the run to complete, and reads back what Claude did.
What it means in practice: Your agent thinks like Claude, can read and write files on your computer, browse the web, and run terminal commands — all within the workspace of the task it's working on. It's capable of doing real coding work, writing documents, doing research, and more.
Note: On macOS and supported Linux machines, new Claude Code agents run on Paperclip Runner by default, as ACP agents → Claude. Pick Legacy runner under Advanced → Runner to use
claude_localinstead.
Prerequisites
- Claude Code installed on your Mac (claude.ai/code)
- An Anthropic API key (console.anthropic.com)
Configuration fields
Working directory (deprecated) You won't see this field when you create a new agent. It only appears when you edit an older local agent that already has a working directory saved, and it's there as a legacy fallback. New agents get their folder from the task's project workspace instead, so set up a project workspace rather than pointing each agent at a folder. If an older agent still shows the field, you can leave it as it is or clear it once the agent's work lives in a project.
Model
Which Claude model to use. If you leave it blank, Paperclip uses claude-opus-5-5. Some common choices:
claude-opus-5-5orclaude-opus-5— most capable, best reasoning, highest cost. Good for your CEO or complex strategic agents.claude-sonnet-5-5orclaude-sonnet-5— fast, capable, lower cost. Good for worker agents doing routine tasks. Sonnet 5.5 needs Claude Code2.1.284or newer.
When in doubt, start with Sonnet for workers and Opus for the CEO. The effort options next to the model change with the model you pick — newer Opus, Sonnet 5 and 5.5, and Fable models add xhigh and max. See Claude Code — Reasoning Effort.
Environment variables
The agent form includes an Environment variables section. Add ANTHROPIC_API_KEY there, either as a plain value or as a secret reference. If you're not sure what key name to use, ANTHROPIC_API_KEY is the standard one.
Timeout (sec)
How long a single heartbeat run is allowed to take before Paperclip cuts it off. You'll find it on an existing agent's Harness / Runtime page under Run Policy → Advanced Run Policy. It starts at 0, which means no timeout. If you set one, leave plenty of headroom — complex coding tasks can run for 10 minutes or more, and a limit that's too low cuts agents off mid-task.
Common errors
"Claude Code not found" — Claude Code isn't installed, or isn't on the system PATH. Install it from claude.ai/code and then click Run test in the Test your agent card (at the bottom of the agent's Harness / Runtime page) to verify Paperclip can find it.
"API key invalid" — Check that the environment variable name matches exactly what you've configured, and that the key itself starts with sk-ant-. Anthropic keys are case-sensitive.
"Timeout" — The heartbeat ran longer than your timeout setting. Increase the timeout value, or break the task into smaller pieces so each heartbeat can finish faster.
Codex (codex_local)
The codex_local adapter runs your agent using OpenAI's Codex CLI on your Mac. It works the same way as claude_local but uses OpenAI models instead of Anthropic.
Note: On macOS and supported Linux machines, new Codex agents run on Paperclip Runner by default. Pick Legacy runner under Advanced → Runner to use
codex_localinstead.
Prerequisites
- OpenAI Codex CLI installed on your Mac
- An OpenAI API key (platform.openai.com)
Configuration fields
The fields are the same as claude_local — mainly model selection and environment variables — but pointing to OpenAI instead of Anthropic. As with Claude Code, Working directory (deprecated) only appears when you edit an older agent that already has one saved.
Model examples for Codex:
gpt-5.6-sol— the default and the normal starting pointgpt-6.1-sol— the newest Codex model, with reasoning effort up toultragpt-6-astra,gpt-6-sol, orgpt-6-luna— the GPT-6 family, with extra reasoning-effort levelso4-mini— fast and cost-effective for routine tasks
See Codex — Models for the full list.
OpenCode (opencode_local)
The opencode_local adapter runs your agent using OpenCode — a flexible, open-source AI terminal tool that supports multiple providers. It lets you configure exactly which model and provider to use via the adapterConfig.model field in provider/model format.
When to use this: If you want to switch between providers easily, or use a model not available through claude_local or codex_local directly.
Note: On macOS and supported Linux x64 machines, new OpenCode agents run on Paperclip Runner by default, with
provider: "opencode". Pick Legacy runner under Advanced → Runner to useopencode_localinstead.
The configuration is similar to the other local adapters, with an additional Model field in provider/model format (e.g., anthropic/claude-opus-4-6 or openai/gpt-5.3-codex).
Other adapters you may see
Three built-in adapter types are marked "Coming soon" in the agent-config dropdown and can't be picked directly from the UI today. They're fully functional in the runtime — you just configure them via the API or an imported company export until the UI picker lands.
openclaw_gateway— remote OpenClaw instances reached over the WebSocket gateway protocol. Today, the normal path is the OpenClaw invite-prompt flow on the Company Settings page. See OpenClaw Gateway.http— webhook-style invocation into your own service. Aimed at developers building custom agent integrations. See HTTP.process— runs an arbitrary local command or script. See Process.
External adapter plugins can also be installed — they appear in the dropdown once loaded.
HTTP Webhook (http)
Info: The
httpadapter is currently not selectable from the agent-config dropdown. Configure it via the API or an imported company export for now.
The http adapter connects to a web server or cloud function that you control. When a heartbeat fires, Paperclip sends an HTTP request to your endpoint with the agent's context and tasks. Your endpoint processes the work and sends results back.
When to use this: When your agent lives in the cloud, runs on a different machine, or is built on a platform that accepts webhook calls.
Configuration fields
Webhook URL (url)
The full URL Paperclip will call when a heartbeat fires. This must be publicly accessible or reachable from your Paperclip instance. It's the one HTTP-specific field shown in the Configuration card on the agent's Harness / Runtime page.
Headers (headers)
Extra request headers — typically a secret token, so your server can verify the call came from Paperclip and not someone else. Set this in the adapter config through the API or a company export; the form doesn't show it.
Timeout (timeoutMs)
How long Paperclip waits for a response, in milliseconds, before treating the heartbeat as failed. Also set through the API or a company export.
Note: The HTTP adapter is aimed at developers building custom agent integrations. If you're using a standard AI provider locally,
claude_localorcodex_localis the simpler choice.
Shell Process (process)
Info: The
processadapter is currently not selectable from the agent-config dropdown. Configure it via the API or an imported company export for now.
The process adapter runs a command on the same machine as Paperclip. When a heartbeat fires, Paperclip executes the command you specify, passing the agent's context as stdin or environment variables.
When to use this: For custom scripts, local automation, or agents built on tools that don't have their own dedicated adapter.
Configuration fields
Command The executable command and any arguments. The command must be accessible from the machine running Paperclip.
Working directory Where to run the command.
Environment variables Additional environment variables to set for the process (e.g., API keys, paths).
Getting API keys
If you haven't set up an API key yet, here's how:
- Go to console.anthropic.com and sign in or create an account
- In the left sidebar, click API Keys
- Click Create Key
- Give it a name you'll recognise (e.g. "Paperclip")
- Copy the key immediately — it starts with
sk-ant-and is only shown once
Store it somewhere safe (a password manager works well). You'll use the environment variable name ANTHROPIC_API_KEY when configuring the adapter.
Warning: Copy the key immediately after creating it. Anthropic shows it only once. If you lose it, you'll need to create a new one and update your adapter configuration.
- Go to platform.openai.com and sign in or create an account
- Click your profile icon in the top right, then click API keys
- Click Create new secret key
- Give it a name (e.g. "Paperclip") and click Create secret key
- Copy the key immediately — it starts with
sk-and is only shown once
Store it somewhere safe. You'll use the environment variable name OPENAI_API_KEY when configuring the adapter.
Warning: Copy the key immediately after creating it. OpenAI shows it only once. If you lose it, you'll need to create a new one and update your adapter configuration.
You're set
You now understand what adapters are and how to configure the most common ones. The next guide covers execution workspaces — the isolated code environments that agents work within when doing file-based tasks.