Timezone setting, default heartbeat cadence, global monthly budget ceiling, notification webhook endpoints, and the company metadata JSONB field for custom config.
Every configurable option in the Company Settings panel, what it affects at runtime, and best practices for development vs production.
Company Dashboard → Settings (gear icon, top-right). Settings are grouped into four sections.
| Setting | Type | Effect |
|---|---|---|
| Company name | text | Display only; does not change slug |
| Slug | text | Read-only after creation; used in URLs |
| Monthly budget | decimal | Global ceiling; triggers company-wide pause |
Tip: Set a low monthly budget ($10–$20) in development. Raise it when you move to production. The budget resets on the 1st of each month.
| Setting | Default | Notes |
|---|---|---|
| Cron expression | */5 * * * * |
Every 5 minutes |
| Enabled | true | Disable to pause all automatic execution |
| Max concurrent agents | 5 | How many agents can run in parallel per tick |
Cron examples:
*/5 * * * * — every 5 minutes (default)
*/15 * * * * — every 15 minutes (lighter on costs)
0 * * * * — hourly
0 9-17 * * 1-5 — business hours only (9am–5pm Mon–Fri UTC)
Disable the heartbeat schedule when you want to trigger runs manually during development.
Approval gates are defined at the company level. Each policy specifies a trigger condition and a required approver.
Default policies:
hire_agent → requires: human_admin
terminate_agent → requires: human_admin
budget_increase → requires: human_admin
strategy_change → requires: human_admin
You can add custom policies for domain-specific actions:
{
"trigger": "publish_content",
"condition": "word_count > 2000",
"required_approver": "human_editor"
}
Paperclip can POST event notifications to an external URL:
| Event | Payload includes |
|---|---|
heartbeat.completed |
run stats, cost |
agent.paused |
agent id, reason |
approval.created |
approval id, trigger, details |
issue.resolved |
issue id, agent, result preview |
{
"webhook_url": "https://your-app.com/webhooks/paperclip",
"webhook_secret": "whsec_...",
"events": ["heartbeat.completed", "approval.created"]
}
The secret is used to sign the payload with HMAC-SHA256 — verify it on your end.
To start fresh without deleting the company:
-- Clear all issues and runs but keep agents
DELETE FROM cost_events WHERE company_id = 'your-id';
DELETE FROM heartbeat_runs WHERE company_id = 'your-id';
UPDATE issues SET status = 'open', result = NULL WHERE company_id = 'your-id';
UPDATE companies SET paused = false WHERE id = 'your-id';