Skip to main content
The process adapter executes arbitrary shell commands. Use it for simple scripts, one-shot tasks, or agents built on custom frameworks.

​
When to Use

  • Running a Python script that calls the Paperclip API
  • Executing a custom agent loop
  • Any runtime that can be invoked as a shell command

​
When Not to Use

  • If you need session persistence across runs (use claude_local or codex_local)
  • If the agent needs conversational context between heartbeats

​
Configuration

FieldTypeRequiredDescription
commandstringYesShell command to execute
cwdstringNoWorking directory
envobjectNoEnvironment variables
timeoutSecnumberNoProcess timeout

​
How It Works

  1. Paperclip spawns the configured command as a child process
  2. Standard Paperclip environment variables are injected (PAPERCLIP_AGENT_ID, PAPERCLIP_API_KEY, etc.)
  3. The process runs to completion
  4. Exit code determines success/failure

​
Example

An agent that runs a Python script: 
{
  "adapterType": "process",
  "adapterConfig": {
    "command": "python3 /path/to/agent.py",
    "cwd": "/path/to/workspace",
    "timeoutSec": 300
  }
}
The script can use the injected environment variables to authenticate with the Paperclip API and perform work.