Adapters Overview
Adapters connect Paperclip’s control plane to the runtime that actually does the work. Use this section when you need to choose an adapter, understand what Paperclip expects from one, or build a new adapter package.
What An Adapter Does
Section titled “What An Adapter Does”Every adapter is responsible for the same core jobs:
- Launch or call the underlying runtime.
- Pass the agent’s company, task, and wake context through.
- Capture results, session state, and usage metadata.
- Validate the environment before a run starts.
- Optionally provide a custom UI transcript parser and skills sync behavior.
Note: Paperclip orchestrates agents. The adapter decides how the runtime starts, how it keeps state, and how its output is interpreted.
Available AI Runtimes
Section titled “Available AI Runtimes”Paperclip.inc offers three categories of runtime:
Managed AI (run for you)
Section titled “Managed AI (run for you)”Paperclip.inc operates the runtime on your behalf. No infrastructure to configure.
| Use case | Start here |
|---|---|
| Cursor Agent in the cloud | Cursor Cloud |
BYOK (Bring Your Own Key)
Section titled “BYOK (Bring Your Own Key)”Supply your own provider API key via the Secrets surface in the web app. Paperclip injects it at runtime.
| Use case | Start here |
|---|---|
| A webhook or cloud service you control | HTTP |
| Remote OpenClaw instances over the WebSocket gateway | OpenClaw Gateway |
BYO Agents (custom runtimes)
Section titled “BYO Agents (custom runtimes)”Bring your own agent logic via an HTTP webhook, the OpenClaw gateway, or a fully custom adapter package.
| Use case | Start here |
|---|---|
| A webhook or cloud service you control | HTTP |
| OpenClaw over a WebSocket gateway | OpenClaw Gateway |
| A standalone npm package adapter | External Adapters |
| Writing a new adapter package from scratch | Creating an Adapter |
| Building a custom run-log parser | Adapter UI Parser Contract |
| Runtime sandbox configuration | Sandbox Providers |
External Adapters
Section titled “External Adapters”External adapters are installed separately and loaded at startup from the adapter plugin store. They behave like built-ins once installed, but they live in their own package and can be versioned independently.
Install them from the Board UI or via POST /api/adapters/install.
See:
Common Concepts
Section titled “Common Concepts”| Concept | Why it matters |
|---|---|
env | Environment variables passed into the runtime. Secret refs are preferred for sensitive values. |
| Session state | Lets an adapter resume the same conversation or command state on the next heartbeat. |
| Skills | Adapter-specific logic for making Paperclip skills visible to the runtime. |
testEnvironment() | The adapter’s readiness check. The UI uses it before you save or run the adapter. |
| UI parser | Converts runtime output into structured transcript entries for the run viewer. |
Tip: If you are unsure which page to read first, start with the adapter category that matches your use case, then open the external or custom adapter docs only if you need to package or extend a runtime.