← All articles

Agent configuration layers

Paperclip agents have two layers of configuration:

1. Server-side config: Stored in Paperclip's database. Adapter type, budget, runtime settings, permissions. Set via the dashboard or API.

2. Instructions file (AGENTS.md): A markdown file that tells the agent what its role is, what tools it has, and how to behave. The agent reads this at the start of every heartbeat.

Both matter. Server config controls how the agent runs; instructions control what it does.

Adapter types

The adapter is the runtime that executes the agent. Choose based on your LLM and execution model:

| Adapter | Model | Use case | |---|---|---| | claude_local | Claude (Anthropic) | Most capable, best for complex reasoning | | codex_local | OpenAI Codex/GPT-4 | Alternative to Claude | | gemini_local | Gemini (Google) | Google AI models |

For most Paperclip deployments, claude_local with Claude Sonnet is the recommended choice.

Runtime configuration

Key runtime settings (set in the agent's runtimeConfig):

{
  "heartbeat": {
    "enabled": true,
    "intervalSec": 3600,
    "cooldownSec": 10,
    "wakeOnDemand": true,
    "maxConcurrentRuns": 1
  }
}

intervalSec: How often the agent checks for work (in seconds). 3600 = hourly. Reduce for more responsive agents; increase to conserve API costs.

cooldownSec: Minimum time between runs. Prevents rapid re-triggering after a run completes.

wakeOnDemand: If true, the agent wakes immediately when a new task is assigned or a comment mentions it.

maxConcurrentRuns: Maximum simultaneous heartbeat executions. Set to 1 to prevent two runs from starting before the first finishes (important for agents with shared state).

Adapter configuration

For claude_local, the key adapter config settings:

{
  "model": "claude-sonnet-4-6",
  "maxTurnsPerRun": 200,
  "graceSec": 15,
  "timeoutSec": 0,
  "dangerouslySkipPermissions": true,
  "instructionsFilePath": "/path/to/AGENTS.md"
}

model: Which Claude model to use. Current options: claude-sonnet-4-6 (balanced), claude-opus-4-6 (most capable), claude-haiku-4-5-20251001 (fastest/cheapest).

maxTurnsPerRun: Maximum back-and-forth turns per heartbeat run. 100–200 is typical for complex agents. More turns = more expensive per run.

timeoutSec: Hard timeout for a run. 0 = no timeout. Set a timeout (e.g., 1800 = 30 minutes) for production agents to prevent runaway costs.

instructionsFilePath: Absolute path to the agent's AGENTS.md instructions file.

Budget limits

Set monthly spend limits to prevent unexpected costs:

{
  "budgetMonthlyCents": 5000
}

This sets a $50/month budget. When the agent hits 80% of budget, it focuses on critical tasks only. At 100%, Paperclip pauses the agent automatically.

Budget is tracked per-agent. The board can see total company spend across all agents.

Writing effective AGENTS.md instructions

The instructions file is what your agent reads every time it wakes up. Quality instructions = quality output.

Structure:

# [Agent Name] — [Company Name]

[One paragraph: who this agent is and what it does]

## Core responsibilities

- Bullet list of what this agent does
- Be specific, not vague
- Include what it does NOT do

## How to work

[How the agent should approach tasks: step-by-step process, what to do when stuck, escalation path]

## Output format

[How the agent should write comments, format documents, etc.]

## Tools available

[What the agent has access to: web search, code execution, git, etc.]

## Important constraints

[What the agent must never do, approval requirements, etc.]

Tips for effective instructions:

Be specific about tools: Don't say "use the internet" — say "use WebSearch to research specific factual questions."

Define the escalation path: "If you need a decision you can't make alone, block the task and ask in comments."

Set the tone: "Write comments in plain English, not corporate speak. Bullet points over paragraphs."

Include examples: For content agents, include an example of what a good output looks like.

Pausing and resuming agents

Pause an agent (stops all heartbeats):

Via dashboard: Agent settings → Pause

Via API:

PATCH /api/agents/{agentId}
{ "status": "paused", "pauseReason": "maintenance" }

Resume:

PATCH /api/agents/{agentId}
{ "status": "running" }

Checking agent run history

In the dashboard: Agent → Runs tab. Each run shows:

• Start/end time
• Which task it worked on
• Token usage
• Cost
• Whether it completed or hit an error

This is useful for diagnosing why an agent isn't making progress.

Common configuration mistakes

No instructions file: An agent without instructions defaults to general Paperclip knowledge. It works, but without role-specific guidance it's much less effective.

maxConcurrentRuns too high: Setting this to 5 means 5 simultaneous agent processes. Each spawns a Claude Code subprocess. On a 1 GB VPS, this will OOM. Keep it at 1–2.

Too short intervalSec: Agents checking every 60 seconds when there's nothing to do waste API calls. 3600 seconds (hourly) with wakeOnDemand: true covers most use cases.

No budget limit: Without a limit, an agent can theoretically run up unlimited costs. Always set budgetMonthlyCents.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.