Spaces:
Paused
Paused
File size: 5,334 Bytes
cf9339a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 | # Agent Runtime Guide
Status: User-facing guide
Last updated: 2026-02-17
Audience: Operators setting up and running agents in Paperclip
## 1. What this system does
Agents in Paperclip do not run continuously.
They run in **heartbeats**: short execution windows triggered by a wakeup.
Each heartbeat:
1. Starts the configured agent adapter (for example, Claude CLI or Codex CLI)
2. Gives it the current prompt/context
3. Lets it work until it exits, times out, or is cancelled
4. Stores results (status, token usage, errors, logs)
5. Updates the UI live
## 2. When an agent wakes up
An agent can be woken up in four ways:
- `timer`: scheduled interval (for example every 5 minutes)
- `assignment`: when work is assigned/checked out to that agent
- `on_demand`: manual wakeup (button/API)
- `automation`: system-triggered wakeup for future automations
If an agent is already running, new wakeups are merged (coalesced) instead of launching duplicate runs.
## 3. What to configure per agent
## 3.1 Adapter choice
Common choices:
- `claude_local`: runs your local `claude` CLI
- `codex_local`: runs your local `codex` CLI
- `process`: generic shell command adapter
- `http`: calls an external HTTP endpoint
For `claude_local` and `codex_local`, Paperclip assumes the CLI is already installed and authenticated on the host machine.
## 3.2 Runtime behavior
In agent runtime settings, configure heartbeat policy:
- `enabled`: allow scheduled heartbeats
- `intervalSec`: timer interval (0 = disabled)
- `wakeOnAssignment`: wake when assigned work
- `wakeOnOnDemand`: allow ping-style on-demand wakeups
- `wakeOnAutomation`: allow system automation wakeups
## 3.3 Working directory and execution limits
For local adapters, set:
- `cwd` (working directory)
- `timeoutSec` (max runtime per heartbeat)
- `graceSec` (time before force-kill after timeout/cancel)
- optional env vars and extra CLI args
- use **Test environment** in agent configuration to run adapter-specific diagnostics before saving
## 3.4 Prompt templates
You can set:
- `promptTemplate`: used for every run (first run and resumed sessions)
Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values.
## 4. Session resume behavior
Paperclip stores session IDs for resumable adapters.
- Next heartbeat reuses the saved session automatically.
- This gives continuity across heartbeats.
- You can reset a session if context gets stale or confused.
Use session reset when:
- you significantly changed prompt strategy
- the agent is stuck in a bad loop
- you want a clean restart
## 5. Logs, status, and run history
For each heartbeat run you get:
- run status (`queued`, `running`, `succeeded`, `failed`, `timed_out`, `cancelled`)
- error text and stderr/stdout excerpts
- token usage/cost when available from the adapter
- full logs (stored outside core run rows, optimized for large output)
In local/dev setups, full logs are stored on disk under the configured run-log path.
## 6. Live updates in the UI
Paperclip pushes runtime/activity updates to the browser in real time.
You should see live changes for:
- agent status
- heartbeat run status
- task/activity updates caused by agent work
- dashboard/cost/activity panels as relevant
If the connection drops, the UI reconnects automatically.
## 7. Common operating patterns
## 7.1 Simple autonomous loop
1. Enable timer wakeups (for example every 300s)
2. Keep assignment wakeups on
3. Use a focused prompt template
4. Watch run logs and adjust prompt/config over time
## 7.2 Event-driven loop (less constant polling)
1. Disable timer or set a long interval
2. Keep wake-on-assignment enabled
3. Use on-demand wakeups for manual nudges
## 7.3 Safety-first loop
1. Short timeout
2. Conservative prompt
3. Monitor errors + cancel quickly when needed
4. Reset sessions when drift appears
## 8. Troubleshooting
If runs fail repeatedly:
1. Check adapter command availability (`claude`/`codex` installed and logged in).
2. Verify `cwd` exists and is accessible.
3. Inspect run error + stderr excerpt, then full log.
4. Confirm timeout is not too low.
5. Reset session and retry.
6. Pause agent if it is causing repeated bad updates.
Typical failure causes:
- CLI not installed/authenticated
- bad working directory
- malformed adapter args/env
- prompt too broad or missing constraints
- process timeout
Claude-specific note:
- If `ANTHROPIC_API_KEY` is set in adapter env or host environment, Claude uses API-key auth instead of subscription login. Paperclip surfaces this as a warning in environment tests, not a hard error.
## 9. Security and risk notes
Local CLI adapters run unsandboxed on the host machine.
That means:
- prompt instructions matter
- configured credentials/env vars are sensitive
- working directory permissions matter
Start with least privilege where possible, and avoid exposing secrets in broad reusable prompts unless intentionally required.
## 10. Minimal setup checklist
1. Choose adapter (`claude_local` or `codex_local`).
2. Set `cwd` to the target workspace.
3. Add bootstrap + normal prompt templates.
4. Configure heartbeat policy (timer and/or assignment wakeups).
5. Trigger a manual wakeup.
6. Confirm run succeeds and session/token usage is recorded.
7. Watch live updates and iterate prompt/config.
|