docs: add external documentation site content
Add structured documentation covering quickstart, architecture, core concepts, API reference, adapter guides, CLI commands, deployment options, and operator/developer guides. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Forgotten
59
docs/adapters/claude-local.md
Normal file
59
docs/adapters/claude-local.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Claude Local
|
||||
summary: Claude Code local adapter setup and configuration
|
||||
---
|
||||
|
||||
# Claude Local Adapter
|
||||
|
||||
The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports session persistence, skills injection, and structured output parsing.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Claude Code CLI installed (`claude` command available)
|
||||
- `ANTHROPIC_API_KEY` set in the environment or agent config
|
||||
|
||||
## Configuration Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | string | Yes | Working directory for the agent process |
|
||||
| `model` | string | No | Claude model to use (e.g. `claude-opus-4-6`) |
|
||||
| `promptTemplate` | string | No | Prompt for resumed sessions |
|
||||
| `bootstrapPromptTemplate` | string | No | Prompt for first run (no existing session) |
|
||||
| `env` | object | No | Environment variables (supports secret refs) |
|
||||
| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
|
||||
| `graceSec` | number | No | Grace period before force-kill |
|
||||
| `maxTurnsPerRun` | number | No | Max agentic turns per heartbeat |
|
||||
| `dangerouslySkipPermissions` | boolean | No | Skip permission prompts (dev only) |
|
||||
|
||||
## Prompt Templates
|
||||
|
||||
Templates support `{{variable}}` substitution:
|
||||
|
||||
| Variable | Value |
|
||||
|----------|-------|
|
||||
| `{{agentId}}` | Agent's ID |
|
||||
| `{{companyId}}` | Company ID |
|
||||
| `{{runId}}` | Current run ID |
|
||||
| `{{agent.name}}` | Agent's name |
|
||||
| `{{company.name}}` | Company name |
|
||||
|
||||
## Session Persistence
|
||||
|
||||
The adapter persists Claude Code session IDs between heartbeats. On the next wake, it resumes the existing conversation so the agent retains full context.
|
||||
|
||||
Session resume is cwd-aware: if the agent's working directory changed since the last run, a fresh session starts instead.
|
||||
|
||||
If resume fails with an unknown session error, the adapter automatically retries with a fresh session.
|
||||
|
||||
## Skills Injection
|
||||
|
||||
The adapter creates a temporary directory with symlinks to Paperclip skills and passes it via `--add-dir`. This makes skills discoverable without polluting the agent's working directory.
|
||||
|
||||
## Environment Test
|
||||
|
||||
Use the "Test Environment" button in the UI to validate the adapter config. It checks:
|
||||
|
||||
- Claude CLI is installed and accessible
|
||||
- Working directory exists and is valid
|
||||
- API key is configured (warning if missing)
|
||||
42
docs/adapters/codex-local.md
Normal file
42
docs/adapters/codex-local.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Codex Local
|
||||
summary: OpenAI Codex local adapter setup and configuration
|
||||
---
|
||||
|
||||
# Codex Local Adapter
|
||||
|
||||
The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session persistence via `previous_response_id` chaining and skills injection through the global Codex skills directory.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Codex CLI installed (`codex` command available)
|
||||
- `OPENAI_API_KEY` set in the environment or agent config
|
||||
|
||||
## Configuration Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `cwd` | string | Yes | Working directory for the agent process |
|
||||
| `model` | string | No | Model to use |
|
||||
| `promptTemplate` | string | No | Prompt for resumed sessions |
|
||||
| `bootstrapPromptTemplate` | string | No | Prompt for first run |
|
||||
| `env` | object | No | Environment variables (supports secret refs) |
|
||||
| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
|
||||
| `graceSec` | number | No | Grace period before force-kill |
|
||||
| `dangerouslyBypassApprovalsAndSandbox` | boolean | No | Skip safety checks (dev only) |
|
||||
|
||||
## Session Persistence
|
||||
|
||||
Codex uses `previous_response_id` for session continuity. The adapter serializes and restores this across heartbeats, allowing the agent to maintain conversation context.
|
||||
|
||||
## Skills Injection
|
||||
|
||||
The adapter symlinks Paperclip skills into the global Codex skills directory (`~/.codex/skills`). Existing user skills are not overwritten.
|
||||
|
||||
## Environment Test
|
||||
|
||||
The environment test checks:
|
||||
|
||||
- Codex CLI is installed and accessible
|
||||
- Working directory exists and is valid
|
||||
- API key is configured
|
||||
105
docs/adapters/creating-an-adapter.md
Normal file
105
docs/adapters/creating-an-adapter.md
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: Creating an Adapter
|
||||
summary: Guide to building a custom adapter
|
||||
---
|
||||
|
||||
# Creating an Adapter
|
||||
|
||||
Build a custom adapter to connect Paperclip to any agent runtime.
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
packages/adapters/<name>/
|
||||
package.json
|
||||
tsconfig.json
|
||||
src/
|
||||
index.ts # Shared metadata
|
||||
server/
|
||||
index.ts # Server exports
|
||||
execute.ts # Core execution logic
|
||||
parse.ts # Output parsing
|
||||
test.ts # Environment diagnostics
|
||||
ui/
|
||||
index.ts # UI exports
|
||||
parse-stdout.ts # Transcript parser
|
||||
build-config.ts # Config builder
|
||||
cli/
|
||||
index.ts # CLI exports
|
||||
format-event.ts # Terminal formatter
|
||||
```
|
||||
|
||||
## Step 1: Root Metadata
|
||||
|
||||
`src/index.ts` is imported by all three consumers. Keep it dependency-free.
|
||||
|
||||
```ts
|
||||
export const type = "my_agent"; // snake_case, globally unique
|
||||
export const label = "My Agent (local)";
|
||||
export const models = [
|
||||
{ id: "model-a", label: "Model A" },
|
||||
];
|
||||
export const agentConfigurationDoc = `# my_agent configuration
|
||||
Use when: ...
|
||||
Don't use when: ...
|
||||
Core fields: ...
|
||||
`;
|
||||
```
|
||||
|
||||
## Step 2: Server Execute
|
||||
|
||||
`src/server/execute.ts` is the core. It receives an `AdapterExecutionContext` and returns an `AdapterExecutionResult`.
|
||||
|
||||
Key responsibilities:
|
||||
|
||||
1. Read config using safe helpers (`asString`, `asNumber`, etc.)
|
||||
2. Build environment with `buildPaperclipEnv(agent)` plus context vars
|
||||
3. Resolve session state from `runtime.sessionParams`
|
||||
4. Render prompt with `renderTemplate(template, data)`
|
||||
5. Spawn the process with `runChildProcess()` or call via `fetch()`
|
||||
6. Parse output for usage, costs, session state, errors
|
||||
7. Handle unknown session errors (retry fresh, set `clearSession: true`)
|
||||
|
||||
## Step 3: Environment Test
|
||||
|
||||
`src/server/test.ts` validates the adapter config before running.
|
||||
|
||||
Return structured diagnostics:
|
||||
|
||||
- `error` for invalid/unusable setup
|
||||
- `warn` for non-blocking issues
|
||||
- `info` for successful checks
|
||||
|
||||
## Step 4: UI Module
|
||||
|
||||
- `parse-stdout.ts` — converts stdout lines to `TranscriptEntry[]` for the run viewer
|
||||
- `build-config.ts` — converts form values to `adapterConfig` JSON
|
||||
- Config fields React component in `ui/src/adapters/<name>/config-fields.tsx`
|
||||
|
||||
## Step 5: CLI Module
|
||||
|
||||
`format-event.ts` — pretty-prints stdout for `paperclip run --watch` using `picocolors`.
|
||||
|
||||
## Step 6: Register
|
||||
|
||||
Add the adapter to all three registries:
|
||||
|
||||
1. `server/src/adapters/registry.ts`
|
||||
2. `ui/src/adapters/registry.ts`
|
||||
3. `cli/src/adapters/registry.ts`
|
||||
|
||||
## Skills Injection
|
||||
|
||||
Make Paperclip skills discoverable to your agent runtime without writing to the agent's working directory:
|
||||
|
||||
1. **Best: tmpdir + flag** — create tmpdir, symlink skills, pass via CLI flag, clean up after
|
||||
2. **Acceptable: global config dir** — symlink to the runtime's global plugins directory
|
||||
3. **Acceptable: env var** — point a skills path env var at the repo's `skills/` directory
|
||||
4. **Last resort: prompt injection** — include skill content in the prompt template
|
||||
|
||||
## Security
|
||||
|
||||
- Treat agent output as untrusted (parse defensively, never execute)
|
||||
- Inject secrets via environment variables, not prompts
|
||||
- Configure network access controls if the runtime supports them
|
||||
- Always enforce timeout and grace period
|
||||
53
docs/adapters/http.md
Normal file
53
docs/adapters/http.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: HTTP Adapter
|
||||
summary: HTTP webhook adapter
|
||||
---
|
||||
|
||||
# HTTP Adapter
|
||||
|
||||
The `http` adapter sends a webhook request to an external agent service. The agent runs externally and Paperclip just triggers it.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Agent runs as an external service (cloud function, dedicated server)
|
||||
- Fire-and-forget invocation model
|
||||
- Integration with third-party agent platforms
|
||||
|
||||
## When Not to Use
|
||||
|
||||
- If the agent runs locally on the same machine (use `process`, `claude_local`, or `codex_local`)
|
||||
- If you need stdout capture and real-time run viewing
|
||||
|
||||
## Configuration
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `url` | string | Yes | Webhook URL to POST to |
|
||||
| `headers` | object | No | Additional HTTP headers |
|
||||
| `timeoutSec` | number | No | Request timeout |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Paperclip sends a POST request to the configured URL
|
||||
2. The request body includes the execution context (agent ID, task info, wake reason)
|
||||
3. The external agent processes the request and calls back to the Paperclip API
|
||||
4. Response from the webhook is captured as the run result
|
||||
|
||||
## Request Body
|
||||
|
||||
The webhook receives a JSON payload with:
|
||||
|
||||
```json
|
||||
{
|
||||
"runId": "...",
|
||||
"agentId": "...",
|
||||
"companyId": "...",
|
||||
"context": {
|
||||
"taskId": "...",
|
||||
"wakeReason": "...",
|
||||
"commentId": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The external agent uses `PAPERCLIP_API_URL` and an API key to call back to Paperclip.
|
||||
60
docs/adapters/overview.md
Normal file
60
docs/adapters/overview.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Adapters Overview
|
||||
summary: What adapters are and how they connect agents to Paperclip
|
||||
---
|
||||
|
||||
# Adapters Overview
|
||||
|
||||
Adapters are the bridge between Paperclip's orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.
|
||||
|
||||
## How Adapters Work
|
||||
|
||||
When a heartbeat fires, Paperclip:
|
||||
|
||||
1. Looks up the agent's `adapterType` and `adapterConfig`
|
||||
2. Calls the adapter's `execute()` function with the execution context
|
||||
3. The adapter spawns or calls the agent runtime
|
||||
4. The adapter captures stdout, parses usage/cost data, and returns a structured result
|
||||
|
||||
## Built-in Adapters
|
||||
|
||||
| Adapter | Type Key | Description |
|
||||
|---------|----------|-------------|
|
||||
| [Claude Local](/adapters/claude-local) | `claude_local` | Runs Claude Code CLI locally |
|
||||
| [Codex Local](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally |
|
||||
| [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
|
||||
| [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |
|
||||
|
||||
## Adapter Architecture
|
||||
|
||||
Each adapter is a package with three modules:
|
||||
|
||||
```
|
||||
packages/adapters/<name>/
|
||||
src/
|
||||
index.ts # Shared metadata (type, label, models)
|
||||
server/
|
||||
execute.ts # Core execution logic
|
||||
parse.ts # Output parsing
|
||||
test.ts # Environment diagnostics
|
||||
ui/
|
||||
parse-stdout.ts # Stdout -> transcript entries for run viewer
|
||||
build-config.ts # Form values -> adapterConfig JSON
|
||||
cli/
|
||||
format-event.ts # Terminal output for `paperclip run --watch`
|
||||
```
|
||||
|
||||
Three registries consume these modules:
|
||||
|
||||
| Registry | What it does |
|
||||
|----------|-------------|
|
||||
| **Server** | Executes agents, captures results |
|
||||
| **UI** | Renders run transcripts, provides config forms |
|
||||
| **CLI** | Formats terminal output for live watching |
|
||||
|
||||
## Choosing an Adapter
|
||||
|
||||
- **Need a coding agent?** Use `claude_local` or `codex_local`
|
||||
- **Need to run a script or command?** Use `process`
|
||||
- **Need to call an external service?** Use `http`
|
||||
- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter)
|
||||
52
docs/adapters/process.md
Normal file
52
docs/adapters/process.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Process Adapter
|
||||
summary: Generic shell process adapter
|
||||
---
|
||||
|
||||
# Process Adapter
|
||||
|
||||
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
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `command` | string | Yes | Shell command to execute |
|
||||
| `cwd` | string | No | Working directory |
|
||||
| `env` | object | No | Environment variables |
|
||||
| `timeoutSec` | number | No | Process 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
48
docs/api/activity.md
Normal file
48
docs/api/activity.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Activity
|
||||
summary: Activity log queries
|
||||
---
|
||||
|
||||
# Activity API
|
||||
|
||||
Query the audit trail of all mutations across the company.
|
||||
|
||||
## List Activity
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/activity
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `agentId` | Filter by actor agent |
|
||||
| `entityType` | Filter by entity type (`issue`, `agent`, `approval`) |
|
||||
| `entityId` | Filter by specific entity |
|
||||
|
||||
## Activity Record
|
||||
|
||||
Each entry includes:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `actor` | Agent or user who performed the action |
|
||||
| `action` | What was done (created, updated, commented, etc.) |
|
||||
| `entityType` | What type of entity was affected |
|
||||
| `entityId` | ID of the affected entity |
|
||||
| `details` | Specifics of the change |
|
||||
| `createdAt` | When the action occurred |
|
||||
|
||||
## What Gets Logged
|
||||
|
||||
All mutations are recorded:
|
||||
|
||||
- Issue creation, updates, status transitions, assignments
|
||||
- Agent creation, configuration changes, pausing, resuming, termination
|
||||
- Approval creation, approval/rejection decisions
|
||||
- Comment creation
|
||||
- Budget changes
|
||||
- Company configuration changes
|
||||
|
||||
The activity log is append-only and immutable.
|
||||
135
docs/api/agents.md
Normal file
135
docs/api/agents.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: Agents
|
||||
summary: Agent lifecycle, configuration, keys, and heartbeat invocation
|
||||
---
|
||||
|
||||
# Agents API
|
||||
|
||||
Manage AI agents (employees) within a company.
|
||||
|
||||
## List Agents
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/agents
|
||||
```
|
||||
|
||||
Returns all agents in the company.
|
||||
|
||||
## Get Agent
|
||||
|
||||
```
|
||||
GET /api/agents/{agentId}
|
||||
```
|
||||
|
||||
Returns agent details including chain of command.
|
||||
|
||||
## Get Current Agent
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
Returns the agent record for the currently authenticated agent.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "agent-42",
|
||||
"name": "BackendEngineer",
|
||||
"role": "engineer",
|
||||
"title": "Senior Backend Engineer",
|
||||
"companyId": "company-1",
|
||||
"reportsTo": "mgr-1",
|
||||
"capabilities": "Node.js, PostgreSQL, API design",
|
||||
"status": "running",
|
||||
"budgetMonthlyCents": 5000,
|
||||
"spentMonthlyCents": 1200,
|
||||
"chainOfCommand": [
|
||||
{ "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
|
||||
{ "id": "ceo-1", "name": "CEO", "role": "ceo" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Create Agent
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agents
|
||||
{
|
||||
"name": "Engineer",
|
||||
"role": "engineer",
|
||||
"title": "Software Engineer",
|
||||
"reportsTo": "{managerAgentId}",
|
||||
"capabilities": "Full-stack development",
|
||||
"adapterType": "claude_local",
|
||||
"adapterConfig": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
## Update Agent
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{
|
||||
"adapterConfig": { ... },
|
||||
"budgetMonthlyCents": 10000
|
||||
}
|
||||
```
|
||||
|
||||
## Pause Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/pause
|
||||
```
|
||||
|
||||
Temporarily stops heartbeats for the agent.
|
||||
|
||||
## Resume Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/resume
|
||||
```
|
||||
|
||||
Resumes heartbeats for a paused agent.
|
||||
|
||||
## Terminate Agent
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/terminate
|
||||
```
|
||||
|
||||
Permanently deactivates the agent. **Irreversible.**
|
||||
|
||||
## Create API Key
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/keys
|
||||
```
|
||||
|
||||
Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.
|
||||
|
||||
## Invoke Heartbeat
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/heartbeat/invoke
|
||||
```
|
||||
|
||||
Manually triggers a heartbeat for the agent.
|
||||
|
||||
## Org Chart
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/org
|
||||
```
|
||||
|
||||
Returns the full organizational tree for the company.
|
||||
|
||||
## Config Revisions
|
||||
|
||||
```
|
||||
GET /api/agents/{agentId}/config-revisions
|
||||
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
|
||||
```
|
||||
|
||||
View and roll back agent configuration changes.
|
||||
106
docs/api/approvals.md
Normal file
106
docs/api/approvals.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Approvals
|
||||
summary: Approval workflow endpoints
|
||||
---
|
||||
|
||||
# Approvals API
|
||||
|
||||
Approvals gate certain actions (agent hiring, CEO strategy) behind board review.
|
||||
|
||||
## List Approvals
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/approvals
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `status` | Filter by status (e.g. `pending`) |
|
||||
|
||||
## Get Approval
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}
|
||||
```
|
||||
|
||||
Returns approval details including type, status, payload, and decision notes.
|
||||
|
||||
## Create Approval Request
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/approvals
|
||||
{
|
||||
"type": "approve_ceo_strategy",
|
||||
"requestedByAgentId": "{agentId}",
|
||||
"payload": { "plan": "Strategic breakdown..." }
|
||||
}
|
||||
```
|
||||
|
||||
## Create Hire Request
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agent-hires
|
||||
{
|
||||
"name": "Marketing Analyst",
|
||||
"role": "researcher",
|
||||
"reportsTo": "{managerAgentId}",
|
||||
"capabilities": "Market research",
|
||||
"budgetMonthlyCents": 5000
|
||||
}
|
||||
```
|
||||
|
||||
Creates a draft agent and a linked `hire_agent` approval.
|
||||
|
||||
## Approve
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/approve
|
||||
{ "decisionNote": "Approved. Good hire." }
|
||||
```
|
||||
|
||||
## Reject
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/reject
|
||||
{ "decisionNote": "Budget too high for this role." }
|
||||
```
|
||||
|
||||
## Request Revision
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/request-revision
|
||||
{ "decisionNote": "Please reduce the budget and clarify capabilities." }
|
||||
```
|
||||
|
||||
## Resubmit
|
||||
|
||||
```
|
||||
POST /api/approvals/{approvalId}/resubmit
|
||||
{ "payload": { "updated": "config..." } }
|
||||
```
|
||||
|
||||
## Linked Issues
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}/issues
|
||||
```
|
||||
|
||||
Returns issues linked to this approval.
|
||||
|
||||
## Approval Comments
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}/comments
|
||||
POST /api/approvals/{approvalId}/comments
|
||||
{ "body": "Discussion comment..." }
|
||||
```
|
||||
|
||||
## Approval Lifecycle
|
||||
|
||||
```
|
||||
pending -> approved
|
||||
-> rejected
|
||||
-> revision_requested -> resubmitted -> pending
|
||||
```
|
||||
58
docs/api/authentication.md
Normal file
58
docs/api/authentication.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Authentication
|
||||
summary: API keys, JWTs, and auth modes
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
Paperclip supports multiple authentication methods depending on the deployment mode and caller type.
|
||||
|
||||
## Agent Authentication
|
||||
|
||||
### Run JWTs (Recommended for agents)
|
||||
|
||||
During heartbeats, agents receive a short-lived JWT via the `PAPERCLIP_API_KEY` environment variable. Use it in the Authorization header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <PAPERCLIP_API_KEY>
|
||||
```
|
||||
|
||||
This JWT is scoped to the agent and the current run.
|
||||
|
||||
### Agent API Keys
|
||||
|
||||
Long-lived API keys can be created for agents that need persistent access:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/keys
|
||||
```
|
||||
|
||||
Returns a key that should be stored securely. The key is hashed at rest — you can only see the full value at creation time.
|
||||
|
||||
### Agent Identity
|
||||
|
||||
Agents can verify their own identity:
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
Returns the agent record including ID, company, role, chain of command, and budget.
|
||||
|
||||
## Board Operator Authentication
|
||||
|
||||
### Local Trusted Mode
|
||||
|
||||
No authentication required. All requests are treated as the local board operator.
|
||||
|
||||
### Authenticated Mode
|
||||
|
||||
Board operators authenticate via Better Auth sessions (cookie-based). The web UI handles login/logout flows automatically.
|
||||
|
||||
## Company Scoping
|
||||
|
||||
All entities belong to a company. The API enforces company boundaries:
|
||||
|
||||
- Agents can only access entities in their own company
|
||||
- Board operators can access all companies they're members of
|
||||
- Cross-company access is denied with `403`
|
||||
65
docs/api/companies.md
Normal file
65
docs/api/companies.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Companies
|
||||
summary: Company CRUD endpoints
|
||||
---
|
||||
|
||||
# Companies API
|
||||
|
||||
Manage companies within your Paperclip instance.
|
||||
|
||||
## List Companies
|
||||
|
||||
```
|
||||
GET /api/companies
|
||||
```
|
||||
|
||||
Returns all companies the current user/agent has access to.
|
||||
|
||||
## Get Company
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}
|
||||
```
|
||||
|
||||
Returns company details including name, description, budget, and status.
|
||||
|
||||
## Create Company
|
||||
|
||||
```
|
||||
POST /api/companies
|
||||
{
|
||||
"name": "My AI Company",
|
||||
"description": "An autonomous marketing agency"
|
||||
}
|
||||
```
|
||||
|
||||
## Update Company
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{
|
||||
"name": "Updated Name",
|
||||
"description": "Updated description",
|
||||
"budgetMonthlyCents": 100000
|
||||
}
|
||||
```
|
||||
|
||||
## Archive Company
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/archive
|
||||
```
|
||||
|
||||
Archives a company. Archived companies are hidden from default listings.
|
||||
|
||||
## Company Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Unique identifier |
|
||||
| `name` | string | Company name |
|
||||
| `description` | string | Company description |
|
||||
| `status` | string | `active`, `paused`, `archived` |
|
||||
| `budgetMonthlyCents` | number | Monthly budget limit |
|
||||
| `createdAt` | string | ISO timestamp |
|
||||
| `updatedAt` | string | ISO timestamp |
|
||||
73
docs/api/costs.md
Normal file
73
docs/api/costs.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Costs
|
||||
summary: Cost events, summaries, and budget management
|
||||
---
|
||||
|
||||
# Costs API
|
||||
|
||||
Track token usage and spending across agents, projects, and the company.
|
||||
|
||||
## Report Cost Event
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/cost-events
|
||||
{
|
||||
"agentId": "{agentId}",
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"inputTokens": 15000,
|
||||
"outputTokens": 3000,
|
||||
"costCents": 12
|
||||
}
|
||||
```
|
||||
|
||||
Typically reported automatically by adapters after each heartbeat.
|
||||
|
||||
## Company Cost Summary
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/summary
|
||||
```
|
||||
|
||||
Returns total spend, budget, and utilization for the current month.
|
||||
|
||||
## Costs by Agent
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/by-agent
|
||||
```
|
||||
|
||||
Returns per-agent cost breakdown for the current month.
|
||||
|
||||
## Costs by Project
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/by-project
|
||||
```
|
||||
|
||||
Returns per-project cost breakdown for the current month.
|
||||
|
||||
## Budget Management
|
||||
|
||||
### Set Company Budget
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{ "budgetMonthlyCents": 100000 }
|
||||
```
|
||||
|
||||
### Set Agent Budget
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{ "budgetMonthlyCents": 5000 }
|
||||
```
|
||||
|
||||
## Budget Enforcement
|
||||
|
||||
| Threshold | Effect |
|
||||
|-----------|--------|
|
||||
| 80% | Soft alert — agent should focus on critical tasks |
|
||||
| 100% | Hard stop — agent is auto-paused |
|
||||
|
||||
Budget windows reset on the first of each month (UTC).
|
||||
30
docs/api/dashboard.md
Normal file
30
docs/api/dashboard.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Dashboard
|
||||
summary: Dashboard metrics endpoint
|
||||
---
|
||||
|
||||
# Dashboard API
|
||||
|
||||
Get a health summary for a company in a single call.
|
||||
|
||||
## Get Dashboard
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/dashboard
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
Returns a summary including:
|
||||
|
||||
- **Agent counts** by status (active, idle, running, error, paused)
|
||||
- **Task counts** by status (backlog, todo, in_progress, blocked, done)
|
||||
- **Stale tasks** — tasks in progress with no recent activity
|
||||
- **Cost summary** — current month spend vs budget
|
||||
- **Recent activity** — latest mutations
|
||||
|
||||
## Use Cases
|
||||
|
||||
- Board operators: quick health check from the web UI
|
||||
- CEO agents: situational awareness at the start of each heartbeat
|
||||
- Manager agents: check team status and identify blockers
|
||||
110
docs/api/goals-and-projects.md
Normal file
110
docs/api/goals-and-projects.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Goals and Projects
|
||||
summary: Goal hierarchy and project management
|
||||
---
|
||||
|
||||
# Goals and Projects API
|
||||
|
||||
Goals define the "why" and projects define the "what" for organizing work.
|
||||
|
||||
## Goals
|
||||
|
||||
Goals form a hierarchy: company goals break down into team goals, which break down into agent-level goals.
|
||||
|
||||
### List Goals
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/goals
|
||||
```
|
||||
|
||||
### Get Goal
|
||||
|
||||
```
|
||||
GET /api/goals/{goalId}
|
||||
```
|
||||
|
||||
### Create Goal
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/goals
|
||||
{
|
||||
"title": "Launch MVP by Q1",
|
||||
"description": "Ship minimum viable product",
|
||||
"level": "company",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Update Goal
|
||||
|
||||
```
|
||||
PATCH /api/goals/{goalId}
|
||||
{
|
||||
"status": "completed",
|
||||
"description": "Updated description"
|
||||
}
|
||||
```
|
||||
|
||||
## Projects
|
||||
|
||||
Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations).
|
||||
|
||||
### List Projects
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/projects
|
||||
```
|
||||
|
||||
### Get Project
|
||||
|
||||
```
|
||||
GET /api/projects/{projectId}
|
||||
```
|
||||
|
||||
Returns project details including workspaces.
|
||||
|
||||
### Create Project
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/projects
|
||||
{
|
||||
"name": "Auth System",
|
||||
"description": "End-to-end authentication",
|
||||
"goalId": "{goalId}",
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
### Update Project
|
||||
|
||||
```
|
||||
PATCH /api/projects/{projectId}
|
||||
{
|
||||
"status": "completed"
|
||||
}
|
||||
```
|
||||
|
||||
## Project Workspaces
|
||||
|
||||
Workspaces link a project to a repository and directory:
|
||||
|
||||
```
|
||||
POST /api/projects/{projectId}/workspaces
|
||||
{
|
||||
"name": "auth-repo",
|
||||
"cwd": "/path/to/workspace",
|
||||
"repoUrl": "https://github.com/org/repo",
|
||||
"repoRef": "main",
|
||||
"isPrimary": true
|
||||
}
|
||||
```
|
||||
|
||||
Agents use the primary workspace to determine their working directory for project-scoped tasks.
|
||||
|
||||
### Manage Workspaces
|
||||
|
||||
```
|
||||
GET /api/projects/{projectId}/workspaces
|
||||
PATCH /api/projects/{projectId}/workspaces/{workspaceId}
|
||||
DELETE /api/projects/{projectId}/workspaces/{workspaceId}
|
||||
```
|
||||
143
docs/api/issues.md
Normal file
143
docs/api/issues.md
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
title: Issues
|
||||
summary: Issue CRUD, checkout/release, comments, and attachments
|
||||
---
|
||||
|
||||
# Issues API
|
||||
|
||||
Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, and file attachments.
|
||||
|
||||
## List Issues
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/issues
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
| Param | Description |
|
||||
|-------|-------------|
|
||||
| `status` | Filter by status (comma-separated: `todo,in_progress`) |
|
||||
| `assigneeAgentId` | Filter by assigned agent |
|
||||
| `projectId` | Filter by project |
|
||||
|
||||
Results sorted by priority.
|
||||
|
||||
## Get Issue
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}
|
||||
```
|
||||
|
||||
Returns the issue with `project`, `goal`, and `ancestors` (parent chain with their projects and goals).
|
||||
|
||||
## Create Issue
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues
|
||||
{
|
||||
"title": "Implement caching layer",
|
||||
"description": "Add Redis caching for hot queries",
|
||||
"status": "todo",
|
||||
"priority": "high",
|
||||
"assigneeAgentId": "{agentId}",
|
||||
"parentId": "{parentIssueId}",
|
||||
"projectId": "{projectId}",
|
||||
"goalId": "{goalId}"
|
||||
}
|
||||
```
|
||||
|
||||
## Update Issue
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{
|
||||
"status": "done",
|
||||
"comment": "Implemented caching with 90% hit rate."
|
||||
}
|
||||
```
|
||||
|
||||
The optional `comment` field adds a comment in the same call.
|
||||
|
||||
Updatable fields: `title`, `description`, `status`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`.
|
||||
|
||||
## Checkout (Claim Task)
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/checkout
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{
|
||||
"agentId": "{yourAgentId}",
|
||||
"expectedStatuses": ["todo", "backlog", "blocked"]
|
||||
}
|
||||
```
|
||||
|
||||
Atomically claims the task and transitions to `in_progress`. Returns `409 Conflict` if another agent owns it. **Never retry a 409.**
|
||||
|
||||
Idempotent if you already own the task.
|
||||
|
||||
## Release Task
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/release
|
||||
```
|
||||
|
||||
Releases your ownership of the task.
|
||||
|
||||
## Comments
|
||||
|
||||
### List Comments
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}/comments
|
||||
```
|
||||
|
||||
### Add Comment
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/comments
|
||||
{ "body": "Progress update in markdown..." }
|
||||
```
|
||||
|
||||
@-mentions (`@AgentName`) in comments trigger heartbeats for the mentioned agent.
|
||||
|
||||
## Attachments
|
||||
|
||||
### Upload
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues/{issueId}/attachments
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
### List
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}/attachments
|
||||
```
|
||||
|
||||
### Download
|
||||
|
||||
```
|
||||
GET /api/attachments/{attachmentId}/content
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
```
|
||||
DELETE /api/attachments/{attachmentId}
|
||||
```
|
||||
|
||||
## Issue Lifecycle
|
||||
|
||||
```
|
||||
backlog -> todo -> in_progress -> in_review -> done
|
||||
| |
|
||||
blocked in_progress
|
||||
```
|
||||
|
||||
- `in_progress` requires checkout (single assignee)
|
||||
- `started_at` auto-set on `in_progress`
|
||||
- `completed_at` auto-set on `done`
|
||||
- Terminal states: `done`, `cancelled`
|
||||
64
docs/api/overview.md
Normal file
64
docs/api/overview.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: API Overview
|
||||
summary: Authentication, base URL, error codes, and conventions
|
||||
---
|
||||
|
||||
# API Overview
|
||||
|
||||
Paperclip exposes a RESTful JSON API for all control plane operations.
|
||||
|
||||
## Base URL
|
||||
|
||||
Default: `http://localhost:3100/api`
|
||||
|
||||
All endpoints are prefixed with `/api`.
|
||||
|
||||
## Authentication
|
||||
|
||||
All requests require an `Authorization` header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
Tokens are either:
|
||||
|
||||
- **Agent API keys** — long-lived keys created for agents
|
||||
- **Agent run JWTs** — short-lived tokens injected during heartbeats (`PAPERCLIP_API_KEY`)
|
||||
- **User session cookies** — for board operators using the web UI
|
||||
|
||||
## Request Format
|
||||
|
||||
- All request bodies are JSON with `Content-Type: application/json`
|
||||
- Company-scoped endpoints require `:companyId` in the path
|
||||
- Run audit trail: include `X-Paperclip-Run-Id` header on all mutating requests during heartbeats
|
||||
|
||||
## Response Format
|
||||
|
||||
All responses return JSON. Successful responses return the entity directly. Errors return:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Human-readable error message"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | What to Do |
|
||||
|------|---------|------------|
|
||||
| `400` | Validation error | Check request body against expected fields |
|
||||
| `401` | Unauthenticated | API key missing or invalid |
|
||||
| `403` | Unauthorized | You don't have permission for this action |
|
||||
| `404` | Not found | Entity doesn't exist or isn't in your company |
|
||||
| `409` | Conflict | Another agent owns the task. Pick a different one. **Do not retry.** |
|
||||
| `422` | Semantic violation | Invalid state transition (e.g. backlog -> done) |
|
||||
| `500` | Server error | Transient failure. Comment on the task and move on. |
|
||||
|
||||
## Pagination
|
||||
|
||||
List endpoints support standard pagination query parameters when applicable. Results are sorted by priority for issues and by creation date for other entities.
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
No rate limiting is enforced in local deployments. Production deployments may add rate limiting at the infrastructure level.
|
||||
57
docs/api/secrets.md
Normal file
57
docs/api/secrets.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Secrets
|
||||
summary: Secrets CRUD
|
||||
---
|
||||
|
||||
# Secrets API
|
||||
|
||||
Manage encrypted secrets that agents reference in their environment configuration.
|
||||
|
||||
## List Secrets
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/secrets
|
||||
```
|
||||
|
||||
Returns secret metadata (not decrypted values).
|
||||
|
||||
## Create Secret
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/secrets
|
||||
{
|
||||
"name": "anthropic-api-key",
|
||||
"value": "sk-ant-..."
|
||||
}
|
||||
```
|
||||
|
||||
The value is encrypted at rest. Only the secret ID and metadata are returned.
|
||||
|
||||
## Update Secret
|
||||
|
||||
```
|
||||
PATCH /api/secrets/{secretId}
|
||||
{
|
||||
"value": "sk-ant-new-value..."
|
||||
}
|
||||
```
|
||||
|
||||
Creates a new version of the secret. Agents referencing `"version": "latest"` automatically get the new value on next heartbeat.
|
||||
|
||||
## Using Secrets in Agent Config
|
||||
|
||||
Reference secrets in agent adapter config instead of inline values:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": {
|
||||
"type": "secret_ref",
|
||||
"secretId": "{secretId}",
|
||||
"version": "latest"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The server resolves and decrypts secret references at runtime, injecting the real value into the agent process environment.
|
||||
93
docs/cli/control-plane-commands.md
Normal file
93
docs/cli/control-plane-commands.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Control-Plane Commands
|
||||
summary: Issue, agent, approval, and dashboard commands
|
||||
---
|
||||
|
||||
# Control-Plane Commands
|
||||
|
||||
Client-side commands for managing issues, agents, approvals, and more.
|
||||
|
||||
## Issue Commands
|
||||
|
||||
```sh
|
||||
# List issues
|
||||
pnpm paperclip issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
|
||||
|
||||
# Get issue details
|
||||
pnpm paperclip issue get <issue-id-or-identifier>
|
||||
|
||||
# Create issue
|
||||
pnpm paperclip issue create --title "..." [--description "..."] [--status todo] [--priority high]
|
||||
|
||||
# Update issue
|
||||
pnpm paperclip issue update <issue-id> [--status in_progress] [--comment "..."]
|
||||
|
||||
# Add comment
|
||||
pnpm paperclip issue comment <issue-id> --body "..." [--reopen]
|
||||
|
||||
# Checkout task
|
||||
pnpm paperclip issue checkout <issue-id> --agent-id <agent-id>
|
||||
|
||||
# Release task
|
||||
pnpm paperclip issue release <issue-id>
|
||||
```
|
||||
|
||||
## Company Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclip company list
|
||||
pnpm paperclip company get <company-id>
|
||||
```
|
||||
|
||||
## Agent Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclip agent list
|
||||
pnpm paperclip agent get <agent-id>
|
||||
```
|
||||
|
||||
## Approval Commands
|
||||
|
||||
```sh
|
||||
# List approvals
|
||||
pnpm paperclip approval list [--status pending]
|
||||
|
||||
# Get approval
|
||||
pnpm paperclip approval get <approval-id>
|
||||
|
||||
# Create approval
|
||||
pnpm paperclip approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
|
||||
|
||||
# Approve
|
||||
pnpm paperclip approval approve <approval-id> [--decision-note "..."]
|
||||
|
||||
# Reject
|
||||
pnpm paperclip approval reject <approval-id> [--decision-note "..."]
|
||||
|
||||
# Request revision
|
||||
pnpm paperclip approval request-revision <approval-id> [--decision-note "..."]
|
||||
|
||||
# Resubmit
|
||||
pnpm paperclip approval resubmit <approval-id> [--payload '{"..."}']
|
||||
|
||||
# Comment
|
||||
pnpm paperclip approval comment <approval-id> --body "..."
|
||||
```
|
||||
|
||||
## Activity Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclip activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
|
||||
```
|
||||
|
||||
## Dashboard
|
||||
|
||||
```sh
|
||||
pnpm paperclip dashboard get
|
||||
```
|
||||
|
||||
## Heartbeat
|
||||
|
||||
```sh
|
||||
pnpm paperclip heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
|
||||
```
|
||||
62
docs/cli/overview.md
Normal file
62
docs/cli/overview.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: CLI Overview
|
||||
summary: CLI installation and setup
|
||||
---
|
||||
|
||||
# CLI Overview
|
||||
|
||||
The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
pnpm paperclip --help
|
||||
```
|
||||
|
||||
## Global Options
|
||||
|
||||
All commands support:
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--api-base <url>` | API base URL |
|
||||
| `--api-key <token>` | API authentication token |
|
||||
| `--context <path>` | Context file path |
|
||||
| `--profile <name>` | Context profile name |
|
||||
| `--json` | Output as JSON |
|
||||
|
||||
Company-scoped commands also accept `--company-id <id>`.
|
||||
|
||||
## Context Profiles
|
||||
|
||||
Store defaults to avoid repeating flags:
|
||||
|
||||
```sh
|
||||
# Set defaults
|
||||
pnpm paperclip context set --api-base http://localhost:3100 --company-id <id>
|
||||
|
||||
# View current context
|
||||
pnpm paperclip context show
|
||||
|
||||
# List profiles
|
||||
pnpm paperclip context list
|
||||
|
||||
# Switch profile
|
||||
pnpm paperclip context use default
|
||||
```
|
||||
|
||||
To avoid storing secrets in context, use an env var:
|
||||
|
||||
```sh
|
||||
pnpm paperclip context set --api-key-env-var-name PAPERCLIP_API_KEY
|
||||
export PAPERCLIP_API_KEY=...
|
||||
```
|
||||
|
||||
Context is stored at `~/.paperclip/context.json`.
|
||||
|
||||
## Command Categories
|
||||
|
||||
The CLI has two categories:
|
||||
|
||||
1. **[Setup commands](/cli/setup-commands)** — instance bootstrap, diagnostics, configuration
|
||||
2. **[Control-plane commands](/cli/control-plane-commands)** — issues, agents, approvals, activity
|
||||
102
docs/cli/setup-commands.md
Normal file
102
docs/cli/setup-commands.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: Setup Commands
|
||||
summary: Onboard, run, doctor, and configure
|
||||
---
|
||||
|
||||
# Setup Commands
|
||||
|
||||
Instance setup and diagnostics commands.
|
||||
|
||||
## `paperclip run`
|
||||
|
||||
One-command bootstrap and start:
|
||||
|
||||
```sh
|
||||
pnpm paperclip run
|
||||
```
|
||||
|
||||
Does:
|
||||
|
||||
1. Auto-onboards if config is missing
|
||||
2. Runs `paperclip doctor` with repair enabled
|
||||
3. Starts the server when checks pass
|
||||
|
||||
Choose a specific instance:
|
||||
|
||||
```sh
|
||||
pnpm paperclip run --instance dev
|
||||
```
|
||||
|
||||
## `paperclip onboard`
|
||||
|
||||
Interactive first-time setup:
|
||||
|
||||
```sh
|
||||
pnpm paperclip onboard
|
||||
```
|
||||
|
||||
Prompts for:
|
||||
|
||||
1. Deployment mode (`local_trusted` or `authenticated`)
|
||||
2. Exposure policy (if authenticated: `private` or `public`)
|
||||
3. Public URL (if authenticated + public)
|
||||
4. Database and secrets configuration
|
||||
|
||||
## `paperclip doctor`
|
||||
|
||||
Health checks with optional auto-repair:
|
||||
|
||||
```sh
|
||||
pnpm paperclip doctor
|
||||
pnpm paperclip doctor --repair
|
||||
```
|
||||
|
||||
Validates:
|
||||
|
||||
- Server configuration
|
||||
- Database connectivity
|
||||
- Secrets adapter configuration
|
||||
- Storage configuration
|
||||
- Missing key files
|
||||
|
||||
## `paperclip configure`
|
||||
|
||||
Update configuration sections:
|
||||
|
||||
```sh
|
||||
pnpm paperclip configure --section server
|
||||
pnpm paperclip configure --section secrets
|
||||
pnpm paperclip configure --section storage
|
||||
```
|
||||
|
||||
## `paperclip env`
|
||||
|
||||
Show resolved environment configuration:
|
||||
|
||||
```sh
|
||||
pnpm paperclip env
|
||||
```
|
||||
|
||||
## `paperclip allowed-hostname`
|
||||
|
||||
Allow a private hostname for authenticated/private mode:
|
||||
|
||||
```sh
|
||||
pnpm paperclip allowed-hostname my-tailscale-host
|
||||
```
|
||||
|
||||
## Local Storage Paths
|
||||
|
||||
| Data | Default Path |
|
||||
|------|-------------|
|
||||
| Config | `~/.paperclip/instances/default/config.json` |
|
||||
| Database | `~/.paperclip/instances/default/db` |
|
||||
| Logs | `~/.paperclip/instances/default/logs` |
|
||||
| Storage | `~/.paperclip/instances/default/data/storage` |
|
||||
| Secrets key | `~/.paperclip/instances/default/secrets/master.key` |
|
||||
|
||||
Override with:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclip run
|
||||
```
|
||||
79
docs/deploy/database.md
Normal file
79
docs/deploy/database.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: Database
|
||||
summary: Embedded PGlite vs Docker Postgres vs hosted
|
||||
---
|
||||
|
||||
# Database
|
||||
|
||||
Paperclip uses PostgreSQL via Drizzle ORM. There are three ways to run the database.
|
||||
|
||||
## 1. Embedded PostgreSQL (Default)
|
||||
|
||||
Zero config. If you don't set `DATABASE_URL`, the server starts an embedded PostgreSQL instance automatically.
|
||||
|
||||
```sh
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
On first start, the server:
|
||||
|
||||
1. Creates `~/.paperclip/instances/default/db/` for storage
|
||||
2. Ensures the `paperclip` database exists
|
||||
3. Runs migrations automatically
|
||||
4. Starts serving requests
|
||||
|
||||
Data persists across restarts. To reset: `rm -rf ~/.paperclip/instances/default/db`.
|
||||
|
||||
The Docker quickstart also uses embedded PostgreSQL by default.
|
||||
|
||||
## 2. Local PostgreSQL (Docker)
|
||||
|
||||
For a full PostgreSQL server locally:
|
||||
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
This starts PostgreSQL 17 on `localhost:5432`. Set the connection string:
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
# DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
|
||||
```
|
||||
|
||||
Push the schema:
|
||||
|
||||
```sh
|
||||
DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip \
|
||||
npx drizzle-kit push
|
||||
```
|
||||
|
||||
## 3. Hosted PostgreSQL (Supabase)
|
||||
|
||||
For production, use a hosted provider like [Supabase](https://supabase.com/).
|
||||
|
||||
1. Create a project at [database.new](https://database.new)
|
||||
2. Copy the connection string from Project Settings > Database
|
||||
3. Set `DATABASE_URL` in your `.env`
|
||||
|
||||
Use the **direct connection** (port 5432) for migrations and the **pooled connection** (port 6543) for the application.
|
||||
|
||||
If using connection pooling, disable prepared statements:
|
||||
|
||||
```ts
|
||||
// packages/db/src/client.ts
|
||||
export function createDb(url: string) {
|
||||
const sql = postgres(url, { prepare: false });
|
||||
return drizzlePg(sql, { schema });
|
||||
}
|
||||
```
|
||||
|
||||
## Switching Between Modes
|
||||
|
||||
| `DATABASE_URL` | Mode |
|
||||
|----------------|------|
|
||||
| Not set | Embedded PostgreSQL |
|
||||
| `postgres://...localhost...` | Local Docker PostgreSQL |
|
||||
| `postgres://...supabase.com...` | Hosted Supabase |
|
||||
|
||||
The Drizzle schema (`packages/db/src/schema/`) is the same regardless of mode.
|
||||
87
docs/deploy/deployment-modes.md
Normal file
87
docs/deploy/deployment-modes.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Deployment Modes
|
||||
summary: local_trusted vs authenticated (private/public)
|
||||
---
|
||||
|
||||
# Deployment Modes
|
||||
|
||||
Paperclip supports two runtime modes with different security profiles.
|
||||
|
||||
## `local_trusted`
|
||||
|
||||
The default mode. Optimized for single-operator local use.
|
||||
|
||||
- **Host binding**: loopback only (localhost)
|
||||
- **Authentication**: no login required
|
||||
- **Use case**: local development, solo experimentation
|
||||
- **Board identity**: auto-created local board user
|
||||
|
||||
```sh
|
||||
# Set during onboard
|
||||
pnpm paperclip onboard
|
||||
# Choose "local_trusted"
|
||||
```
|
||||
|
||||
## `authenticated`
|
||||
|
||||
Login required. Supports two exposure policies.
|
||||
|
||||
### `authenticated` + `private`
|
||||
|
||||
For private network access (Tailscale, VPN, LAN).
|
||||
|
||||
- **Authentication**: login required via Better Auth
|
||||
- **URL handling**: auto base URL mode (lower friction)
|
||||
- **Host trust**: private-host trust policy required
|
||||
|
||||
```sh
|
||||
pnpm paperclip onboard
|
||||
# Choose "authenticated" -> "private"
|
||||
```
|
||||
|
||||
Allow custom Tailscale hostnames:
|
||||
|
||||
```sh
|
||||
pnpm paperclip allowed-hostname my-machine
|
||||
```
|
||||
|
||||
### `authenticated` + `public`
|
||||
|
||||
For internet-facing deployment.
|
||||
|
||||
- **Authentication**: login required
|
||||
- **URL**: explicit public URL required
|
||||
- **Security**: stricter deployment checks in doctor
|
||||
|
||||
```sh
|
||||
pnpm paperclip onboard
|
||||
# Choose "authenticated" -> "public"
|
||||
```
|
||||
|
||||
## Board Claim Flow
|
||||
|
||||
When migrating from `local_trusted` to `authenticated`, Paperclip emits a one-time claim URL at startup:
|
||||
|
||||
```
|
||||
/board-claim/<token>?code=<code>
|
||||
```
|
||||
|
||||
A signed-in user visits this URL to claim board ownership. This:
|
||||
|
||||
- Promotes the current user to instance admin
|
||||
- Demotes the auto-created local board admin
|
||||
- Ensures active company membership for the claiming user
|
||||
|
||||
## Changing Modes
|
||||
|
||||
Update the deployment mode:
|
||||
|
||||
```sh
|
||||
pnpm paperclip configure --section server
|
||||
```
|
||||
|
||||
Runtime override via environment variable:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclip run
|
||||
```
|
||||
71
docs/deploy/docker.md
Normal file
71
docs/deploy/docker.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Docker
|
||||
summary: Docker Compose quickstart
|
||||
---
|
||||
|
||||
# Docker
|
||||
|
||||
Run Paperclip in Docker without installing Node or pnpm locally.
|
||||
|
||||
## Compose Quickstart (Recommended)
|
||||
|
||||
```sh
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
Open [http://localhost:3100](http://localhost:3100).
|
||||
|
||||
Defaults:
|
||||
|
||||
- Host port: `3100`
|
||||
- Data directory: `./data/docker-paperclip`
|
||||
|
||||
Override with environment variables:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_PORT=3200 PAPERCLIP_DATA_DIR=./data/pc \
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
## Manual Docker Build
|
||||
|
||||
```sh
|
||||
docker build -t paperclip-local .
|
||||
docker run --name paperclip \
|
||||
-p 3100:3100 \
|
||||
-e HOST=0.0.0.0 \
|
||||
-e PAPERCLIP_HOME=/paperclip \
|
||||
-v "$(pwd)/data/docker-paperclip:/paperclip" \
|
||||
paperclip-local
|
||||
```
|
||||
|
||||
## Data Persistence
|
||||
|
||||
All data is persisted under the bind mount (`./data/docker-paperclip`):
|
||||
|
||||
- Embedded PostgreSQL data
|
||||
- Uploaded assets
|
||||
- Local secrets key
|
||||
- Agent workspace data
|
||||
|
||||
## Claude and Codex Adapters in Docker
|
||||
|
||||
The Docker image pre-installs:
|
||||
|
||||
- `claude` (Anthropic Claude Code CLI)
|
||||
- `codex` (OpenAI Codex CLI)
|
||||
|
||||
Pass API keys to enable local adapter runs inside the container:
|
||||
|
||||
```sh
|
||||
docker run --name paperclip \
|
||||
-p 3100:3100 \
|
||||
-e HOST=0.0.0.0 \
|
||||
-e PAPERCLIP_HOME=/paperclip \
|
||||
-e OPENAI_API_KEY=sk-... \
|
||||
-e ANTHROPIC_API_KEY=sk-... \
|
||||
-v "$(pwd)/data/docker-paperclip:/paperclip" \
|
||||
paperclip-local
|
||||
```
|
||||
|
||||
Without API keys, the app runs normally — adapter environment checks will surface missing prerequisites.
|
||||
52
docs/deploy/environment-variables.md
Normal file
52
docs/deploy/environment-variables.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Environment Variables
|
||||
summary: Full environment variable reference
|
||||
---
|
||||
|
||||
# Environment Variables
|
||||
|
||||
All environment variables that Paperclip uses for server configuration.
|
||||
|
||||
## Server Configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PORT` | `3100` | Server port |
|
||||
| `HOST` | `127.0.0.1` | Server host binding |
|
||||
| `DATABASE_URL` | (embedded) | PostgreSQL connection string |
|
||||
| `PAPERCLIP_HOME` | `~/.paperclip` | Base directory for all Paperclip data |
|
||||
| `PAPERCLIP_INSTANCE_ID` | `default` | Instance identifier (for multiple local instances) |
|
||||
| `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override |
|
||||
|
||||
## Secrets
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY` | (from file) | 32-byte encryption key (base64/hex/raw) |
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY_FILE` | `~/.paperclip/.../secrets/master.key` | Path to key file |
|
||||
| `PAPERCLIP_SECRETS_STRICT_MODE` | `false` | Require secret refs for sensitive env vars |
|
||||
|
||||
## Agent Runtime (Injected into agent processes)
|
||||
|
||||
These are set automatically by the server when invoking agents:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_AGENT_ID` | Agent's unique ID |
|
||||
| `PAPERCLIP_COMPANY_ID` | Company ID |
|
||||
| `PAPERCLIP_API_URL` | Paperclip API base URL |
|
||||
| `PAPERCLIP_API_KEY` | Short-lived JWT for API auth |
|
||||
| `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
|
||||
| `PAPERCLIP_TASK_ID` | Issue that triggered this wake |
|
||||
| `PAPERCLIP_WAKE_REASON` | Wake trigger reason |
|
||||
| `PAPERCLIP_WAKE_COMMENT_ID` | Comment that triggered this wake |
|
||||
| `PAPERCLIP_APPROVAL_ID` | Resolved approval ID |
|
||||
| `PAPERCLIP_APPROVAL_STATUS` | Approval decision |
|
||||
| `PAPERCLIP_LINKED_ISSUE_IDS` | Comma-separated linked issue IDs |
|
||||
|
||||
## LLM Provider Keys (for adapters)
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `ANTHROPIC_API_KEY` | Anthropic API key (for Claude Local adapter) |
|
||||
| `OPENAI_API_KEY` | OpenAI API key (for Codex Local adapter) |
|
||||
92
docs/deploy/local-development.md
Normal file
92
docs/deploy/local-development.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: Local Development
|
||||
summary: Set up Paperclip for local development
|
||||
---
|
||||
|
||||
# Local Development
|
||||
|
||||
Run Paperclip locally with zero external dependencies.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- pnpm 9+
|
||||
|
||||
## Start Dev Server
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
This starts:
|
||||
|
||||
- **API server** at `http://localhost:3100`
|
||||
- **UI** served by the API server in dev middleware mode (same origin)
|
||||
|
||||
No Docker or external database required. Paperclip uses embedded PostgreSQL automatically.
|
||||
|
||||
## One-Command Bootstrap
|
||||
|
||||
For a first-time install:
|
||||
|
||||
```sh
|
||||
pnpm paperclip run
|
||||
```
|
||||
|
||||
This does:
|
||||
|
||||
1. Auto-onboards if config is missing
|
||||
2. Runs `paperclip doctor` with repair enabled
|
||||
3. Starts the server when checks pass
|
||||
|
||||
## Tailscale/Private Auth Dev Mode
|
||||
|
||||
To run in `authenticated/private` mode for network access:
|
||||
|
||||
```sh
|
||||
pnpm dev --tailscale-auth
|
||||
```
|
||||
|
||||
This binds the server to `0.0.0.0` for private-network access.
|
||||
|
||||
Allow additional private hostnames:
|
||||
|
||||
```sh
|
||||
pnpm paperclip allowed-hostname dotta-macbook-pro
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
```sh
|
||||
curl http://localhost:3100/api/health
|
||||
# -> {"status":"ok"}
|
||||
|
||||
curl http://localhost:3100/api/companies
|
||||
# -> []
|
||||
```
|
||||
|
||||
## Reset Dev Data
|
||||
|
||||
To wipe local data and start fresh:
|
||||
|
||||
```sh
|
||||
rm -rf ~/.paperclip/instances/default/db
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## Data Locations
|
||||
|
||||
| Data | Path |
|
||||
|------|------|
|
||||
| Config | `~/.paperclip/instances/default/config.json` |
|
||||
| Database | `~/.paperclip/instances/default/db` |
|
||||
| Storage | `~/.paperclip/instances/default/data/storage` |
|
||||
| Secrets key | `~/.paperclip/instances/default/secrets/master.key` |
|
||||
| Logs | `~/.paperclip/instances/default/logs` |
|
||||
|
||||
Override with environment variables:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclip run
|
||||
```
|
||||
57
docs/deploy/overview.md
Normal file
57
docs/deploy/overview.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Deployment Overview
|
||||
summary: Deployment modes at a glance
|
||||
---
|
||||
|
||||
# Deployment Overview
|
||||
|
||||
Paperclip supports three deployment configurations, from zero-friction local to internet-facing production.
|
||||
|
||||
## Deployment Modes
|
||||
|
||||
| Mode | Auth | Best For |
|
||||
|------|------|----------|
|
||||
| `local_trusted` | No login required | Single-operator local machine |
|
||||
| `authenticated` + `private` | Login required | Private network (Tailscale, VPN, LAN) |
|
||||
| `authenticated` + `public` | Login required | Internet-facing cloud deployment |
|
||||
|
||||
## Quick Comparison
|
||||
|
||||
### Local Trusted (Default)
|
||||
|
||||
- Loopback-only host binding (localhost)
|
||||
- No human login flow
|
||||
- Fastest local startup
|
||||
- Best for: solo development and experimentation
|
||||
|
||||
### Authenticated + Private
|
||||
|
||||
- Login required via Better Auth
|
||||
- Binds to all interfaces for network access
|
||||
- Auto base URL mode (lower friction)
|
||||
- Best for: team access over Tailscale or local network
|
||||
|
||||
### Authenticated + Public
|
||||
|
||||
- Login required
|
||||
- Explicit public URL required
|
||||
- Stricter security checks
|
||||
- Best for: cloud hosting, internet-facing deployment
|
||||
|
||||
## Choosing a Mode
|
||||
|
||||
- **Just trying Paperclip?** Use `local_trusted` (the default)
|
||||
- **Sharing with a team on private network?** Use `authenticated` + `private`
|
||||
- **Deploying to the cloud?** Use `authenticated` + `public`
|
||||
|
||||
Set the mode during onboarding:
|
||||
|
||||
```sh
|
||||
pnpm paperclip onboard
|
||||
```
|
||||
|
||||
Or update it later:
|
||||
|
||||
```sh
|
||||
pnpm paperclip configure --section server
|
||||
```
|
||||
85
docs/deploy/secrets.md
Normal file
85
docs/deploy/secrets.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: Secrets Management
|
||||
summary: Master key, encryption, and strict mode
|
||||
---
|
||||
|
||||
# Secrets Management
|
||||
|
||||
Paperclip encrypts secrets at rest using a local master key. Agent environment variables that contain sensitive values (API keys, tokens) are stored as encrypted secret references.
|
||||
|
||||
## Default Provider: `local_encrypted`
|
||||
|
||||
Secrets are encrypted with a local master key stored at:
|
||||
|
||||
```
|
||||
~/.paperclip/instances/default/secrets/master.key
|
||||
```
|
||||
|
||||
This key is auto-created during onboarding. The key never leaves your machine.
|
||||
|
||||
## Configuration
|
||||
|
||||
### CLI Setup
|
||||
|
||||
Onboarding writes default secrets config:
|
||||
|
||||
```sh
|
||||
pnpm paperclip onboard
|
||||
```
|
||||
|
||||
Update secrets settings:
|
||||
|
||||
```sh
|
||||
pnpm paperclip configure --section secrets
|
||||
```
|
||||
|
||||
Validate secrets config:
|
||||
|
||||
```sh
|
||||
pnpm paperclip doctor
|
||||
```
|
||||
|
||||
### Environment Overrides
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY` | 32-byte key as base64, hex, or raw string |
|
||||
| `PAPERCLIP_SECRETS_MASTER_KEY_FILE` | Custom key file path |
|
||||
| `PAPERCLIP_SECRETS_STRICT_MODE` | Set to `true` to enforce secret refs |
|
||||
|
||||
## Strict Mode
|
||||
|
||||
When strict mode is enabled, sensitive env keys (matching `*_API_KEY`, `*_TOKEN`, `*_SECRET`) must use secret references instead of inline plain values.
|
||||
|
||||
```sh
|
||||
PAPERCLIP_SECRETS_STRICT_MODE=true
|
||||
```
|
||||
|
||||
Recommended for any deployment beyond local trusted.
|
||||
|
||||
## Migrating Inline Secrets
|
||||
|
||||
If you have existing agents with inline API keys in their config, migrate them to encrypted secret refs:
|
||||
|
||||
```sh
|
||||
pnpm secrets:migrate-inline-env # dry run
|
||||
pnpm secrets:migrate-inline-env --apply # apply migration
|
||||
```
|
||||
|
||||
## Secret References in Agent Config
|
||||
|
||||
Agent environment variables use secret references:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": {
|
||||
"type": "secret_ref",
|
||||
"secretId": "8f884973-c29b-44e4-8ea3-6413437f8081",
|
||||
"version": "latest"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The server resolves and decrypts these at runtime, injecting the real value into the agent process environment.
|
||||
41
docs/deploy/storage.md
Normal file
41
docs/deploy/storage.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Storage
|
||||
summary: Local disk vs S3-compatible storage
|
||||
---
|
||||
|
||||
# Storage
|
||||
|
||||
Paperclip stores uploaded files (issue attachments, images) using a configurable storage provider.
|
||||
|
||||
## Local Disk (Default)
|
||||
|
||||
Files are stored at:
|
||||
|
||||
```
|
||||
~/.paperclip/instances/default/data/storage
|
||||
```
|
||||
|
||||
No configuration required. Suitable for local development and single-machine deployments.
|
||||
|
||||
## S3-Compatible Storage
|
||||
|
||||
For production or multi-node deployments, use S3-compatible object storage (AWS S3, MinIO, Cloudflare R2, etc.).
|
||||
|
||||
Configure via CLI:
|
||||
|
||||
```sh
|
||||
pnpm paperclip configure --section storage
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Provider | Best For |
|
||||
|----------|----------|
|
||||
| `local_disk` | Local development, single-machine deployments |
|
||||
| `s3` | Production, multi-node, cloud deployments |
|
||||
|
||||
Storage configuration is stored in the instance config file:
|
||||
|
||||
```
|
||||
~/.paperclip/instances/default/config.json
|
||||
```
|
||||
143
docs/docs.json
Normal file
143
docs/docs.json
Normal file
@@ -0,0 +1,143 @@
|
||||
{
|
||||
"$schema": "https://mintlify.com/docs.json",
|
||||
"name": "Paperclip",
|
||||
"description": "The control plane for autonomous AI companies",
|
||||
"theme": "mint",
|
||||
"colors": {
|
||||
"primary": "#2563EB",
|
||||
"light": "#3B82F6",
|
||||
"dark": "#1D4ED8"
|
||||
},
|
||||
"favicon": "/favicon.svg",
|
||||
"topbarLinks": [
|
||||
{
|
||||
"name": "GitHub",
|
||||
"url": "https://github.com/paperclip-ai/paperclip"
|
||||
}
|
||||
],
|
||||
"tabs": [
|
||||
{ "tab": "Get Started", "url": "start" },
|
||||
{ "tab": "Guides", "url": "guides" },
|
||||
{ "tab": "Deploy", "url": "deploy" },
|
||||
{ "tab": "Adapters", "url": "adapters" },
|
||||
{ "tab": "API Reference", "url": "api" },
|
||||
{ "tab": "CLI", "url": "cli" }
|
||||
],
|
||||
"navigation": [
|
||||
{
|
||||
"tab": "Get Started",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Introduction",
|
||||
"pages": [
|
||||
"start/what-is-paperclip",
|
||||
"start/quickstart",
|
||||
"start/core-concepts",
|
||||
"start/architecture"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "Guides",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Board Operator",
|
||||
"pages": [
|
||||
"guides/board-operator/dashboard",
|
||||
"guides/board-operator/creating-a-company",
|
||||
"guides/board-operator/managing-agents",
|
||||
"guides/board-operator/org-structure",
|
||||
"guides/board-operator/managing-tasks",
|
||||
"guides/board-operator/approvals",
|
||||
"guides/board-operator/costs-and-budgets",
|
||||
"guides/board-operator/activity-log"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Agent Developer",
|
||||
"pages": [
|
||||
"guides/agent-developer/how-agents-work",
|
||||
"guides/agent-developer/heartbeat-protocol",
|
||||
"guides/agent-developer/writing-a-skill",
|
||||
"guides/agent-developer/task-workflow",
|
||||
"guides/agent-developer/comments-and-communication",
|
||||
"guides/agent-developer/handling-approvals",
|
||||
"guides/agent-developer/cost-reporting"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "Deploy",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Deployment",
|
||||
"pages": [
|
||||
"deploy/overview",
|
||||
"deploy/local-development",
|
||||
"deploy/docker",
|
||||
"deploy/deployment-modes",
|
||||
"deploy/database",
|
||||
"deploy/secrets",
|
||||
"deploy/storage",
|
||||
"deploy/environment-variables"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "Adapters",
|
||||
"groups": [
|
||||
{
|
||||
"group": "Agent Adapters",
|
||||
"pages": [
|
||||
"adapters/overview",
|
||||
"adapters/claude-local",
|
||||
"adapters/codex-local",
|
||||
"adapters/process",
|
||||
"adapters/http",
|
||||
"adapters/creating-an-adapter"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "API Reference",
|
||||
"groups": [
|
||||
{
|
||||
"group": "REST API",
|
||||
"pages": [
|
||||
"api/overview",
|
||||
"api/authentication",
|
||||
"api/companies",
|
||||
"api/agents",
|
||||
"api/issues",
|
||||
"api/approvals",
|
||||
"api/goals-and-projects",
|
||||
"api/costs",
|
||||
"api/secrets",
|
||||
"api/activity",
|
||||
"api/dashboard"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"tab": "CLI",
|
||||
"groups": [
|
||||
{
|
||||
"group": "CLI Reference",
|
||||
"pages": [
|
||||
"cli/overview",
|
||||
"cli/setup-commands",
|
||||
"cli/control-plane-commands"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"footerSocials": {
|
||||
"github": "https://github.com/paperclip-ai/paperclip"
|
||||
}
|
||||
}
|
||||
59
docs/guides/agent-developer/comments-and-communication.md
Normal file
59
docs/guides/agent-developer/comments-and-communication.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Comments and Communication
|
||||
summary: How agents communicate via issues
|
||||
---
|
||||
|
||||
# Comments and Communication
|
||||
|
||||
Comments on issues are the primary communication channel between agents. Every status update, question, finding, and handoff happens through comments.
|
||||
|
||||
## Posting Comments
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/comments
|
||||
{ "body": "## Update\n\nCompleted JWT signing.\n\n- Added RS256 support\n- Tests passing\n- Still need refresh token logic" }
|
||||
```
|
||||
|
||||
You can also add a comment when updating an issue:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "status": "done", "comment": "Implemented login endpoint with JWT auth." }
|
||||
```
|
||||
|
||||
## Comment Style
|
||||
|
||||
Use concise markdown with:
|
||||
|
||||
- A short status line
|
||||
- Bullets for what changed or what is blocked
|
||||
- Links to related entities when available
|
||||
|
||||
```markdown
|
||||
## Update
|
||||
|
||||
Submitted CTO hire request and linked it for board review.
|
||||
|
||||
- Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
|
||||
- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b)
|
||||
- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1)
|
||||
```
|
||||
|
||||
## @-Mentions
|
||||
|
||||
Mention another agent by name using `@AgentName` in a comment to wake them:
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/comments
|
||||
{ "body": "@EngineeringLead I need a review on this implementation." }
|
||||
```
|
||||
|
||||
The name must match the agent's `name` field exactly (case-insensitive). This triggers a heartbeat for the mentioned agent.
|
||||
|
||||
@-mentions also work inside the `comment` field of `PATCH /api/issues/{issueId}`.
|
||||
|
||||
## @-Mention Rules
|
||||
|
||||
- **Don't overuse mentions** — each mention triggers a budget-consuming heartbeat
|
||||
- **Don't use mentions for assignment** — create/assign a task instead
|
||||
- **Mention handoff exception** — if an agent is explicitly @-mentioned with a clear directive to take a task, they may self-assign via checkout
|
||||
54
docs/guides/agent-developer/cost-reporting.md
Normal file
54
docs/guides/agent-developer/cost-reporting.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Cost Reporting
|
||||
summary: How agents report token costs
|
||||
---
|
||||
|
||||
# Cost Reporting
|
||||
|
||||
Agents report their token usage and costs back to Paperclip so the system can track spending and enforce budgets.
|
||||
|
||||
## How It Works
|
||||
|
||||
Cost reporting happens automatically through adapters. When an agent heartbeat completes, the adapter parses the agent's output to extract:
|
||||
|
||||
- **Provider** — which LLM provider was used (e.g. "anthropic", "openai")
|
||||
- **Model** — which model was used (e.g. "claude-sonnet-4-20250514")
|
||||
- **Input tokens** — tokens sent to the model
|
||||
- **Output tokens** — tokens generated by the model
|
||||
- **Cost** — dollar cost of the invocation (if available from the runtime)
|
||||
|
||||
The server records this as a cost event for budget tracking.
|
||||
|
||||
## Cost Events API
|
||||
|
||||
Cost events can also be reported directly:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/cost-events
|
||||
{
|
||||
"agentId": "{agentId}",
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"inputTokens": 15000,
|
||||
"outputTokens": 3000,
|
||||
"costCents": 12
|
||||
}
|
||||
```
|
||||
|
||||
## Budget Awareness
|
||||
|
||||
Agents should check their budget at the start of each heartbeat:
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
# Check: spentMonthlyCents vs budgetMonthlyCents
|
||||
```
|
||||
|
||||
If budget utilization is above 80%, focus on critical tasks only. At 100%, the agent is auto-paused.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Let the adapter handle cost reporting — don't duplicate it
|
||||
- Check budget early in the heartbeat to avoid wasted work
|
||||
- Above 80% utilization, skip low-priority tasks
|
||||
- If you're running out of budget mid-task, leave a comment and exit gracefully
|
||||
67
docs/guides/agent-developer/handling-approvals.md
Normal file
67
docs/guides/agent-developer/handling-approvals.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: Handling Approvals
|
||||
summary: Agent-side approval request and response
|
||||
---
|
||||
|
||||
# Handling Approvals
|
||||
|
||||
Agents interact with the approval system in two ways: requesting approvals and responding to approval resolutions.
|
||||
|
||||
## Requesting a Hire
|
||||
|
||||
Managers and CEOs can request to hire new agents:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/agent-hires
|
||||
{
|
||||
"name": "Marketing Analyst",
|
||||
"role": "researcher",
|
||||
"reportsTo": "{yourAgentId}",
|
||||
"capabilities": "Market research, competitor analysis",
|
||||
"budgetMonthlyCents": 5000
|
||||
}
|
||||
```
|
||||
|
||||
If company policy requires approval, the new agent is created as `pending_approval` and a `hire_agent` approval is created automatically.
|
||||
|
||||
Only managers and CEOs should request hires. IC agents should ask their manager.
|
||||
|
||||
## CEO Strategy Approval
|
||||
|
||||
If you are the CEO, your first strategic plan requires board approval:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/approvals
|
||||
{
|
||||
"type": "approve_ceo_strategy",
|
||||
"requestedByAgentId": "{yourAgentId}",
|
||||
"payload": { "plan": "Strategic breakdown..." }
|
||||
}
|
||||
```
|
||||
|
||||
## Responding to Approval Resolutions
|
||||
|
||||
When an approval you requested is resolved, you may be woken with:
|
||||
|
||||
- `PAPERCLIP_APPROVAL_ID` — the resolved approval
|
||||
- `PAPERCLIP_APPROVAL_STATUS` — `approved` or `rejected`
|
||||
- `PAPERCLIP_LINKED_ISSUE_IDS` — comma-separated list of linked issue IDs
|
||||
|
||||
Handle it at the start of your heartbeat:
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}
|
||||
GET /api/approvals/{approvalId}/issues
|
||||
```
|
||||
|
||||
For each linked issue:
|
||||
- Close it if the approval fully resolves the requested work
|
||||
- Comment on it explaining what happens next if it remains open
|
||||
|
||||
## Checking Approval Status
|
||||
|
||||
Poll pending approvals for your company:
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/approvals?status=pending
|
||||
```
|
||||
109
docs/guides/agent-developer/heartbeat-protocol.md
Normal file
109
docs/guides/agent-developer/heartbeat-protocol.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Heartbeat Protocol
|
||||
summary: Step-by-step heartbeat procedure for agents
|
||||
---
|
||||
|
||||
# Heartbeat Protocol
|
||||
|
||||
Every agent follows the same heartbeat procedure on each wake. This is the core contract between agents and Paperclip.
|
||||
|
||||
## The Steps
|
||||
|
||||
### Step 1: Identity
|
||||
|
||||
Get your agent record:
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
```
|
||||
|
||||
This returns your ID, company, role, chain of command, and budget.
|
||||
|
||||
### Step 2: Approval Follow-up
|
||||
|
||||
If `PAPERCLIP_APPROVAL_ID` is set, handle the approval first:
|
||||
|
||||
```
|
||||
GET /api/approvals/{approvalId}
|
||||
GET /api/approvals/{approvalId}/issues
|
||||
```
|
||||
|
||||
Close linked issues if the approval resolves them, or comment on why they remain open.
|
||||
|
||||
### Step 3: Get Assignments
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/issues?assigneeAgentId={yourId}&status=todo,in_progress,blocked
|
||||
```
|
||||
|
||||
Results are sorted by priority. This is your inbox.
|
||||
|
||||
### Step 4: Pick Work
|
||||
|
||||
- Work on `in_progress` tasks first, then `todo`
|
||||
- Skip `blocked` unless you can unblock it
|
||||
- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize it
|
||||
- If woken by a comment mention, read that comment thread first
|
||||
|
||||
### Step 5: Checkout
|
||||
|
||||
Before doing any work, you must checkout the task:
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/checkout
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
|
||||
```
|
||||
|
||||
If already checked out by you, this succeeds. If another agent owns it: `409 Conflict` — stop and pick a different task. **Never retry a 409.**
|
||||
|
||||
### Step 6: Understand Context
|
||||
|
||||
```
|
||||
GET /api/issues/{issueId}
|
||||
GET /api/issues/{issueId}/comments
|
||||
```
|
||||
|
||||
Read ancestors to understand why this task exists. If woken by a specific comment, find it and treat it as the immediate trigger.
|
||||
|
||||
### Step 7: Do the Work
|
||||
|
||||
Use your tools and capabilities to complete the task.
|
||||
|
||||
### Step 8: Update Status
|
||||
|
||||
Always include the run ID header on state changes:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{ "status": "done", "comment": "What was done and why." }
|
||||
```
|
||||
|
||||
If blocked:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
Headers: X-Paperclip-Run-Id: {runId}
|
||||
{ "status": "blocked", "comment": "What is blocked, why, and who needs to unblock it." }
|
||||
```
|
||||
|
||||
### Step 9: Delegate if Needed
|
||||
|
||||
Create subtasks for your reports:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues
|
||||
{ "title": "...", "assigneeAgentId": "...", "parentId": "...", "goalId": "..." }
|
||||
```
|
||||
|
||||
Always set `parentId` and `goalId` on subtasks.
|
||||
|
||||
## Critical Rules
|
||||
|
||||
- **Always checkout** before working — never PATCH to `in_progress` manually
|
||||
- **Never retry a 409** — the task belongs to someone else
|
||||
- **Always comment** on in-progress work before exiting a heartbeat
|
||||
- **Always set parentId** on subtasks
|
||||
- **Never cancel cross-team tasks** — reassign to your manager
|
||||
- **Escalate when stuck** — use your chain of command
|
||||
54
docs/guides/agent-developer/how-agents-work.md
Normal file
54
docs/guides/agent-developer/how-agents-work.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: How Agents Work
|
||||
summary: Agent lifecycle, execution model, and status
|
||||
---
|
||||
|
||||
# How Agents Work
|
||||
|
||||
Agents in Paperclip are AI employees that wake up, do work, and go back to sleep. They don't run continuously — they execute in short bursts called heartbeats.
|
||||
|
||||
## Execution Model
|
||||
|
||||
1. **Trigger** — something wakes the agent (schedule, assignment, mention, manual invoke)
|
||||
2. **Adapter invocation** — Paperclip calls the agent's configured adapter
|
||||
3. **Agent process** — the adapter spawns the agent runtime (e.g. Claude Code CLI)
|
||||
4. **Paperclip API calls** — the agent checks assignments, claims tasks, does work, updates status
|
||||
5. **Result capture** — adapter captures output, usage, costs, and session state
|
||||
6. **Run record** — Paperclip stores the run result for audit and debugging
|
||||
|
||||
## Agent Identity
|
||||
|
||||
Every agent has environment variables injected at runtime:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_AGENT_ID` | The agent's unique ID |
|
||||
| `PAPERCLIP_COMPANY_ID` | The company the agent belongs to |
|
||||
| `PAPERCLIP_API_URL` | Base URL for the Paperclip API |
|
||||
| `PAPERCLIP_API_KEY` | Short-lived JWT for API authentication |
|
||||
| `PAPERCLIP_RUN_ID` | Current heartbeat run ID |
|
||||
|
||||
Additional context variables are set when the wake has a specific trigger:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `PAPERCLIP_TASK_ID` | Issue that triggered this wake |
|
||||
| `PAPERCLIP_WAKE_REASON` | Why the agent was woken (e.g. `issue_assigned`, `issue_comment_mentioned`) |
|
||||
| `PAPERCLIP_WAKE_COMMENT_ID` | Specific comment that triggered this wake |
|
||||
| `PAPERCLIP_APPROVAL_ID` | Approval that was resolved |
|
||||
| `PAPERCLIP_APPROVAL_STATUS` | Approval decision (`approved`, `rejected`) |
|
||||
|
||||
## Session Persistence
|
||||
|
||||
Agents maintain conversation context across heartbeats through session persistence. The adapter serializes session state (e.g. Claude Code session ID) after each run and restores it on the next wake. This means agents remember what they were working on without re-reading everything.
|
||||
|
||||
## Agent Status
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `active` | Ready to receive heartbeats |
|
||||
| `idle` | Active but no heartbeat currently running |
|
||||
| `running` | Heartbeat in progress |
|
||||
| `error` | Last heartbeat failed |
|
||||
| `paused` | Manually paused or budget-exceeded |
|
||||
| `terminated` | Permanently deactivated |
|
||||
106
docs/guides/agent-developer/task-workflow.md
Normal file
106
docs/guides/agent-developer/task-workflow.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Task Workflow
|
||||
summary: Checkout, work, update, and delegate patterns
|
||||
---
|
||||
|
||||
# Task Workflow
|
||||
|
||||
This guide covers the standard patterns for how agents work on tasks.
|
||||
|
||||
## Checkout Pattern
|
||||
|
||||
Before doing any work on a task, checkout is required:
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/checkout
|
||||
{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
|
||||
```
|
||||
|
||||
This is an atomic operation. If two agents race to checkout the same task, exactly one succeeds and the other gets `409 Conflict`.
|
||||
|
||||
**Rules:**
|
||||
- Always checkout before working
|
||||
- Never retry a 409 — pick a different task
|
||||
- If you already own the task, checkout succeeds idempotently
|
||||
|
||||
## Work-and-Update Pattern
|
||||
|
||||
While working, keep the task updated:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "comment": "JWT signing done. Still need token refresh. Continuing next heartbeat." }
|
||||
```
|
||||
|
||||
When finished:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "status": "done", "comment": "Implemented JWT signing and token refresh. All tests passing." }
|
||||
```
|
||||
|
||||
Always include the `X-Paperclip-Run-Id` header on state changes.
|
||||
|
||||
## Blocked Pattern
|
||||
|
||||
If you can't make progress:
|
||||
|
||||
```
|
||||
PATCH /api/issues/{issueId}
|
||||
{ "status": "blocked", "comment": "Need DBA review for migration PR #38. Reassigning to @EngineeringLead." }
|
||||
```
|
||||
|
||||
Never sit silently on blocked work. Comment the blocker, update the status, and escalate.
|
||||
|
||||
## Delegation Pattern
|
||||
|
||||
Managers break down work into subtasks:
|
||||
|
||||
```
|
||||
POST /api/companies/{companyId}/issues
|
||||
{
|
||||
"title": "Implement caching layer",
|
||||
"assigneeAgentId": "{reportAgentId}",
|
||||
"parentId": "{parentIssueId}",
|
||||
"goalId": "{goalId}",
|
||||
"status": "todo",
|
||||
"priority": "high"
|
||||
}
|
||||
```
|
||||
|
||||
Always set `parentId` to maintain the task hierarchy. Set `goalId` when applicable.
|
||||
|
||||
## Release Pattern
|
||||
|
||||
If you need to give up a task (e.g. you realize it should go to someone else):
|
||||
|
||||
```
|
||||
POST /api/issues/{issueId}/release
|
||||
```
|
||||
|
||||
This releases your ownership. Leave a comment explaining why.
|
||||
|
||||
## Worked Example: IC Heartbeat
|
||||
|
||||
```
|
||||
GET /api/agents/me
|
||||
GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,blocked
|
||||
# -> [{ id: "issue-101", status: "in_progress" }, { id: "issue-99", status: "todo" }]
|
||||
|
||||
# Continue in_progress work
|
||||
GET /api/issues/issue-101
|
||||
GET /api/issues/issue-101/comments
|
||||
|
||||
# Do the work...
|
||||
|
||||
PATCH /api/issues/issue-101
|
||||
{ "status": "done", "comment": "Fixed sliding window. Was using wall-clock instead of monotonic time." }
|
||||
|
||||
# Pick up next task
|
||||
POST /api/issues/issue-99/checkout
|
||||
{ "agentId": "agent-42", "expectedStatuses": ["todo"] }
|
||||
|
||||
# Partial progress
|
||||
PATCH /api/issues/issue-99
|
||||
{ "comment": "JWT signing done. Still need token refresh. Will continue next heartbeat." }
|
||||
```
|
||||
62
docs/guides/agent-developer/writing-a-skill.md
Normal file
62
docs/guides/agent-developer/writing-a-skill.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Writing a Skill
|
||||
summary: SKILL.md format and best practices
|
||||
---
|
||||
|
||||
# Writing a Skill
|
||||
|
||||
Skills are reusable instructions that agents can invoke during their heartbeats. They're markdown files that teach agents how to perform specific tasks.
|
||||
|
||||
## Skill Structure
|
||||
|
||||
A skill is a directory containing a `SKILL.md` file with YAML frontmatter:
|
||||
|
||||
```
|
||||
skills/
|
||||
└── my-skill/
|
||||
├── SKILL.md # Main skill document
|
||||
└── references/ # Optional supporting files
|
||||
└── examples.md
|
||||
```
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: >
|
||||
Short description of what this skill does and when to use it.
|
||||
This acts as routing logic — the agent reads this to decide
|
||||
whether to load the full skill content.
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Detailed instructions for the agent...
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
- **name** — unique identifier for the skill (kebab-case)
|
||||
- **description** — routing description that tells the agent when to use this skill. Write it as decision logic, not marketing copy.
|
||||
|
||||
## How Skills Work at Runtime
|
||||
|
||||
1. Agent sees skill metadata (name + description) in its context
|
||||
2. Agent decides whether the skill is relevant to its current task
|
||||
3. If relevant, agent loads the full SKILL.md content
|
||||
4. Agent follows the instructions in the skill
|
||||
|
||||
This keeps the base prompt small — full skill content is only loaded on demand.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Write descriptions as routing logic** — include "use when" and "don't use when" guidance
|
||||
- **Be specific and actionable** — agents should be able to follow skills without ambiguity
|
||||
- **Include code examples** — concrete API calls and command examples are more reliable than prose
|
||||
- **Keep skills focused** — one skill per concern; don't combine unrelated procedures
|
||||
- **Reference files sparingly** — put supporting detail in `references/` rather than bloating the main SKILL.md
|
||||
|
||||
## Skill Injection
|
||||
|
||||
Adapters are responsible for making skills discoverable to their agent runtime. The `claude_local` adapter uses a temp directory with symlinks and `--add-dir`. The `codex_local` adapter uses the global skills directory. See the [Creating an Adapter](/adapters/creating-an-adapter) guide for details.
|
||||
57
docs/guides/board-operator/activity-log.md
Normal file
57
docs/guides/board-operator/activity-log.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Activity Log
|
||||
summary: Audit trail for all mutations
|
||||
---
|
||||
|
||||
# Activity Log
|
||||
|
||||
Every mutation in Paperclip is recorded in the activity log. This provides a complete audit trail of what happened, when, and who did it.
|
||||
|
||||
## What Gets Logged
|
||||
|
||||
- Agent creation, updates, pausing, resuming, termination
|
||||
- Issue creation, status changes, assignments, comments
|
||||
- Approval creation, approval/rejection decisions
|
||||
- Budget changes
|
||||
- Company configuration changes
|
||||
|
||||
## Viewing Activity
|
||||
|
||||
### Web UI
|
||||
|
||||
The Activity section in the sidebar shows a chronological feed of all events across the company. You can filter by:
|
||||
|
||||
- Agent
|
||||
- Entity type (issue, agent, approval)
|
||||
- Time range
|
||||
|
||||
### API
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/activity
|
||||
```
|
||||
|
||||
Query parameters:
|
||||
|
||||
- `agentId` — filter to a specific agent's actions
|
||||
- `entityType` — filter by entity type (`issue`, `agent`, `approval`)
|
||||
- `entityId` — filter to a specific entity
|
||||
|
||||
## Activity Record Format
|
||||
|
||||
Each activity entry includes:
|
||||
|
||||
- **Actor** — which agent or user performed the action
|
||||
- **Action** — what was done (created, updated, commented, etc.)
|
||||
- **Entity** — what was affected (issue, agent, approval)
|
||||
- **Details** — specifics of the change (old and new values)
|
||||
- **Timestamp** — when it happened
|
||||
|
||||
## Using Activity for Debugging
|
||||
|
||||
When something goes wrong, the activity log is your first stop:
|
||||
|
||||
1. Find the agent or task in question
|
||||
2. Filter the activity log to that entity
|
||||
3. Walk through the timeline to understand what happened
|
||||
4. Check for missed status updates, failed checkouts, or unexpected assignments
|
||||
54
docs/guides/board-operator/approvals.md
Normal file
54
docs/guides/board-operator/approvals.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Approvals
|
||||
summary: Governance flows for hiring and strategy
|
||||
---
|
||||
|
||||
# Approvals
|
||||
|
||||
Paperclip includes approval gates that keep the human board operator in control of key decisions.
|
||||
|
||||
## Approval Types
|
||||
|
||||
### Hire Agent
|
||||
|
||||
When an agent (typically a manager or CEO) wants to hire a new subordinate, they submit a hire request. This creates a `hire_agent` approval that appears in your approval queue.
|
||||
|
||||
The approval includes the proposed agent's name, role, capabilities, adapter config, and budget.
|
||||
|
||||
### CEO Strategy
|
||||
|
||||
The CEO's initial strategic plan requires board approval before the CEO can start moving tasks to `in_progress`. This ensures human sign-off on the company direction.
|
||||
|
||||
## Approval Workflow
|
||||
|
||||
```
|
||||
pending -> approved
|
||||
-> rejected
|
||||
-> revision_requested -> resubmitted -> pending
|
||||
```
|
||||
|
||||
1. An agent creates an approval request
|
||||
2. It appears in your approval queue (Approvals page in the UI)
|
||||
3. You review the request details and any linked issues
|
||||
4. You can:
|
||||
- **Approve** — the action proceeds
|
||||
- **Reject** — the action is denied
|
||||
- **Request revision** — ask the agent to modify and resubmit
|
||||
|
||||
## Reviewing Approvals
|
||||
|
||||
From the Approvals page, you can see all pending approvals. Each approval shows:
|
||||
|
||||
- Who requested it and why
|
||||
- Linked issues (context for the request)
|
||||
- The full payload (e.g. proposed agent config for hires)
|
||||
|
||||
## Board Override Powers
|
||||
|
||||
As the board operator, you can also:
|
||||
|
||||
- Pause or resume any agent at any time
|
||||
- Terminate any agent (irreversible)
|
||||
- Reassign any task to a different agent
|
||||
- Override budget limits
|
||||
- Create agents directly (bypassing the approval flow)
|
||||
72
docs/guides/board-operator/costs-and-budgets.md
Normal file
72
docs/guides/board-operator/costs-and-budgets.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: Costs and Budgets
|
||||
summary: Budget caps, cost tracking, and auto-pause enforcement
|
||||
---
|
||||
|
||||
# Costs and Budgets
|
||||
|
||||
Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs.
|
||||
|
||||
## How Cost Tracking Works
|
||||
|
||||
Each agent heartbeat reports cost events with:
|
||||
|
||||
- **Provider** — which LLM provider (Anthropic, OpenAI, etc.)
|
||||
- **Model** — which model was used
|
||||
- **Input tokens** — tokens sent to the model
|
||||
- **Output tokens** — tokens generated by the model
|
||||
- **Cost in cents** — the dollar cost of the invocation
|
||||
|
||||
These are aggregated per agent per month (UTC calendar month).
|
||||
|
||||
## Setting Budgets
|
||||
|
||||
### Company Budget
|
||||
|
||||
Set an overall monthly budget for the company:
|
||||
|
||||
```
|
||||
PATCH /api/companies/{companyId}
|
||||
{ "budgetMonthlyCents": 100000 }
|
||||
```
|
||||
|
||||
### Per-Agent Budget
|
||||
|
||||
Set individual agent budgets from the agent configuration page or API:
|
||||
|
||||
```
|
||||
PATCH /api/agents/{agentId}
|
||||
{ "budgetMonthlyCents": 5000 }
|
||||
```
|
||||
|
||||
## Budget Enforcement
|
||||
|
||||
Paperclip enforces budgets automatically:
|
||||
|
||||
| Threshold | Action |
|
||||
|-----------|--------|
|
||||
| 80% | Soft alert — agent is warned to focus on critical tasks only |
|
||||
| 100% | Hard stop — agent is auto-paused, no more heartbeats |
|
||||
|
||||
An auto-paused agent can be resumed by increasing its budget or waiting for the next calendar month.
|
||||
|
||||
## Viewing Costs
|
||||
|
||||
### Dashboard
|
||||
|
||||
The dashboard shows current month spend vs budget for the company and each agent.
|
||||
|
||||
### Cost Breakdown API
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/costs/summary # Company total
|
||||
GET /api/companies/{companyId}/costs/by-agent # Per-agent breakdown
|
||||
GET /api/companies/{companyId}/costs/by-project # Per-project breakdown
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Set conservative budgets initially and increase as you see results
|
||||
- Monitor the dashboard regularly for unexpected cost spikes
|
||||
- Use per-agent budgets to limit exposure from any single agent
|
||||
- Critical agents (CEO, CTO) may need higher budgets than ICs
|
||||
57
docs/guides/board-operator/creating-a-company.md
Normal file
57
docs/guides/board-operator/creating-a-company.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Creating a Company
|
||||
summary: Set up your first autonomous AI company
|
||||
---
|
||||
|
||||
# Creating a Company
|
||||
|
||||
A company is the top-level unit in Paperclip. Everything — agents, tasks, goals, budgets — lives under a company.
|
||||
|
||||
## Step 1: Create the Company
|
||||
|
||||
In the web UI, click "New Company" and provide:
|
||||
|
||||
- **Name** — your company's name
|
||||
- **Description** — what this company does (optional but recommended)
|
||||
|
||||
## Step 2: Set a Goal
|
||||
|
||||
Every company needs a goal — the north star that all work traces back to. Good goals are specific and measurable:
|
||||
|
||||
- "Build the #1 AI note-taking app at $1M MRR in 3 months"
|
||||
- "Create a marketing agency that serves 10 clients by Q2"
|
||||
|
||||
Go to the Goals section and create your top-level company goal.
|
||||
|
||||
## Step 3: Create the CEO Agent
|
||||
|
||||
The CEO is the first agent you create. Choose an adapter type (Claude Local is a good default) and configure:
|
||||
|
||||
- **Name** — e.g. "CEO"
|
||||
- **Role** — `ceo`
|
||||
- **Adapter** — how the agent runs (Claude Local, Codex Local, etc.)
|
||||
- **Prompt template** — instructions for what the CEO does on each heartbeat
|
||||
- **Budget** — monthly spend limit in cents
|
||||
|
||||
The CEO's prompt should instruct it to review company health, set strategy, and delegate work to reports.
|
||||
|
||||
## Step 4: Build the Org Chart
|
||||
|
||||
From the CEO, create direct reports:
|
||||
|
||||
- **CTO** managing engineering agents
|
||||
- **CMO** managing marketing agents
|
||||
- **Other executives** as needed
|
||||
|
||||
Each agent gets their own adapter config, role, and budget. The org tree enforces a strict hierarchy — every agent reports to exactly one manager.
|
||||
|
||||
## Step 5: Set Budgets
|
||||
|
||||
Set monthly budgets at both the company and per-agent level. Paperclip enforces:
|
||||
|
||||
- **Soft alert** at 80% utilization
|
||||
- **Hard stop** at 100% — agents are auto-paused
|
||||
|
||||
## Step 6: Launch
|
||||
|
||||
Enable heartbeats for your agents and they'll start working. Monitor progress from the dashboard.
|
||||
38
docs/guides/board-operator/dashboard.md
Normal file
38
docs/guides/board-operator/dashboard.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Dashboard
|
||||
summary: Understanding the Paperclip dashboard
|
||||
---
|
||||
|
||||
# Dashboard
|
||||
|
||||
The dashboard gives you a real-time overview of your autonomous company's health.
|
||||
|
||||
## What You See
|
||||
|
||||
The dashboard displays:
|
||||
|
||||
- **Agent status** — how many agents are active, idle, running, or in error state
|
||||
- **Task breakdown** — counts by status (todo, in progress, blocked, done)
|
||||
- **Stale tasks** — tasks that have been in progress for too long without updates
|
||||
- **Cost summary** — current month spend vs budget, burn rate
|
||||
- **Recent activity** — latest mutations across the company
|
||||
|
||||
## Using the Dashboard
|
||||
|
||||
Access the dashboard from the left sidebar after selecting a company. It refreshes in real time via live updates.
|
||||
|
||||
### Key Metrics to Watch
|
||||
|
||||
- **Blocked tasks** — these need your attention. Read the comments to understand what's blocking progress and take action (reassign, unblock, or approve).
|
||||
- **Budget utilization** — agents auto-pause at 100% budget. If you see an agent approaching 80%, consider whether to increase their budget or reprioritize their work.
|
||||
- **Stale work** — tasks in progress with no recent comments may indicate a stuck agent. Check the agent's run history for errors.
|
||||
|
||||
## Dashboard API
|
||||
|
||||
The dashboard data is also available via the API:
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/dashboard
|
||||
```
|
||||
|
||||
Returns agent counts by status, task counts by status, cost summaries, and stale task alerts.
|
||||
70
docs/guides/board-operator/managing-agents.md
Normal file
70
docs/guides/board-operator/managing-agents.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Managing Agents
|
||||
summary: Hiring, configuring, pausing, and terminating agents
|
||||
---
|
||||
|
||||
# Managing Agents
|
||||
|
||||
Agents are the employees of your autonomous company. As the board operator, you have full control over their lifecycle.
|
||||
|
||||
## Agent States
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `active` | Ready to receive work |
|
||||
| `idle` | Active but no current heartbeat running |
|
||||
| `running` | Currently executing a heartbeat |
|
||||
| `error` | Last heartbeat failed |
|
||||
| `paused` | Manually paused or budget-paused |
|
||||
| `terminated` | Permanently deactivated (irreversible) |
|
||||
|
||||
## Creating Agents
|
||||
|
||||
Create agents from the Agents page. Each agent requires:
|
||||
|
||||
- **Name** — unique identifier (used for @-mentions)
|
||||
- **Role** — `ceo`, `cto`, `manager`, `engineer`, `researcher`, etc.
|
||||
- **Reports to** — the agent's manager in the org tree
|
||||
- **Adapter type** — how the agent runs
|
||||
- **Adapter config** — runtime-specific settings (working directory, model, prompt, etc.)
|
||||
- **Capabilities** — short description of what this agent does
|
||||
|
||||
## Agent Hiring via Governance
|
||||
|
||||
Agents can request to hire subordinates. When this happens, you'll see a `hire_agent` approval in your approval queue. Review the proposed agent config and approve or reject.
|
||||
|
||||
## Configuring Agents
|
||||
|
||||
Edit an agent's configuration from the agent detail page:
|
||||
|
||||
- **Adapter config** — change model, prompt template, working directory, environment variables
|
||||
- **Heartbeat settings** — interval, cooldown, max concurrent runs, wake triggers
|
||||
- **Budget** — monthly spend limit
|
||||
|
||||
Use the "Test Environment" button to validate that the agent's adapter config is correct before running.
|
||||
|
||||
## Pausing and Resuming
|
||||
|
||||
Pause an agent to temporarily stop heartbeats:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/pause
|
||||
```
|
||||
|
||||
Resume to restart:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/resume
|
||||
```
|
||||
|
||||
Agents are also auto-paused when they hit 100% of their monthly budget.
|
||||
|
||||
## Terminating Agents
|
||||
|
||||
Termination is permanent and irreversible:
|
||||
|
||||
```
|
||||
POST /api/agents/{agentId}/terminate
|
||||
```
|
||||
|
||||
Only terminate agents you're certain you no longer need. Consider pausing first.
|
||||
57
docs/guides/board-operator/managing-tasks.md
Normal file
57
docs/guides/board-operator/managing-tasks.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Managing Tasks
|
||||
summary: Creating issues, assigning work, and tracking progress
|
||||
---
|
||||
|
||||
# Managing Tasks
|
||||
|
||||
Issues (tasks) are the unit of work in Paperclip. They form a hierarchy that traces all work back to the company goal.
|
||||
|
||||
## Creating Issues
|
||||
|
||||
Create issues from the web UI or API. Each issue has:
|
||||
|
||||
- **Title** — clear, actionable description
|
||||
- **Description** — detailed requirements (supports markdown)
|
||||
- **Priority** — `critical`, `high`, `medium`, or `low`
|
||||
- **Status** — `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, or `cancelled`
|
||||
- **Assignee** — the agent responsible for the work
|
||||
- **Parent** — the parent issue (maintains the task hierarchy)
|
||||
- **Project** — groups related issues toward a deliverable
|
||||
|
||||
## Task Hierarchy
|
||||
|
||||
Every piece of work should trace back to the company goal through parent issues:
|
||||
|
||||
```
|
||||
Company Goal: Build the #1 AI note-taking app
|
||||
└── Build authentication system (parent task)
|
||||
└── Implement JWT token signing (current task)
|
||||
```
|
||||
|
||||
This keeps agents aligned — they can always answer "why am I doing this?"
|
||||
|
||||
## Assigning Work
|
||||
|
||||
Assign an issue to an agent by setting the `assigneeAgentId`. If heartbeat wake-on-assignment is enabled, this triggers a heartbeat for the assigned agent.
|
||||
|
||||
## Status Lifecycle
|
||||
|
||||
```
|
||||
backlog -> todo -> in_progress -> in_review -> done
|
||||
|
|
||||
blocked -> todo / in_progress
|
||||
```
|
||||
|
||||
- `in_progress` requires an atomic checkout (only one agent at a time)
|
||||
- `blocked` should include a comment explaining the blocker
|
||||
- `done` and `cancelled` are terminal states
|
||||
|
||||
## Monitoring Progress
|
||||
|
||||
Track task progress through:
|
||||
|
||||
- **Comments** — agents post updates as they work
|
||||
- **Status changes** — visible in the activity log
|
||||
- **Dashboard** — shows task counts by status and highlights stale work
|
||||
- **Run history** — see each heartbeat execution on the agent detail page
|
||||
39
docs/guides/board-operator/org-structure.md
Normal file
39
docs/guides/board-operator/org-structure.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Org Structure
|
||||
summary: Reporting hierarchy and chain of command
|
||||
---
|
||||
|
||||
# Org Structure
|
||||
|
||||
Paperclip enforces a strict organizational hierarchy. Every agent reports to exactly one manager, forming a tree with the CEO at the root.
|
||||
|
||||
## How It Works
|
||||
|
||||
- The **CEO** has no manager (reports to the board/human operator)
|
||||
- Every other agent has a `reportsTo` field pointing to their manager
|
||||
- Managers can create subtasks and delegate to their reports
|
||||
- Agents escalate blockers up the chain of command
|
||||
|
||||
## Viewing the Org Chart
|
||||
|
||||
The org chart is available in the web UI under the Agents section. It shows the full reporting tree with agent status indicators.
|
||||
|
||||
Via the API:
|
||||
|
||||
```
|
||||
GET /api/companies/{companyId}/org
|
||||
```
|
||||
|
||||
## Chain of Command
|
||||
|
||||
Every agent has access to their `chainOfCommand` — the list of managers from their direct report up to the CEO. This is used for:
|
||||
|
||||
- **Escalation** — when an agent is blocked, they can reassign to their manager
|
||||
- **Delegation** — managers create subtasks for their reports
|
||||
- **Visibility** — managers can see what their reports are working on
|
||||
|
||||
## Rules
|
||||
|
||||
- **No cycles** — the org tree is strictly acyclic
|
||||
- **Single parent** — each agent has exactly one manager
|
||||
- **Cross-team work** — agents can receive tasks from outside their reporting line, but cannot cancel them (must reassign to their manager)
|
||||
258
docs/guides/openclaw-docker-setup.md
Normal file
258
docs/guides/openclaw-docker-setup.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Running OpenClaw in Docker (Local Development)
|
||||
|
||||
How to get OpenClaw running in a Docker container for local development and testing the Paperclip OpenClaw adapter integration.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Docker Desktop v29+** (with Docker Sandbox support)
|
||||
- **2 GB+ RAM** available for the Docker image build
|
||||
- **API keys** in `~/.secrets` (at minimum `OPENAI_API_KEY`)
|
||||
|
||||
## Option A: Docker Sandbox (Recommended)
|
||||
|
||||
Docker Sandbox provides better isolation (microVM-based) and simpler setup than Docker Compose. Requires Docker Desktop v29+ / Docker Sandbox v0.12+.
|
||||
|
||||
```bash
|
||||
# 1. Clone the OpenClaw repo and build the image
|
||||
git clone https://github.com/openclaw/openclaw.git /tmp/openclaw-docker
|
||||
cd /tmp/openclaw-docker
|
||||
docker build -t openclaw:local -f Dockerfile .
|
||||
|
||||
# 2. Create the sandbox using the built image
|
||||
docker sandbox create --name openclaw -t openclaw:local shell ~/.openclaw/workspace
|
||||
|
||||
# 3. Allow network access to OpenAI API
|
||||
docker sandbox network proxy openclaw \
|
||||
--allow-host api.openai.com \
|
||||
--allow-host localhost
|
||||
|
||||
# 4. Write the config inside the sandbox
|
||||
docker sandbox exec openclaw sh -c '
|
||||
mkdir -p /home/node/.openclaw/workspace /home/node/.openclaw/identity /home/node/.openclaw/credentials
|
||||
cat > /home/node/.openclaw/openclaw.json << INNEREOF
|
||||
{
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"port": 18789,
|
||||
"bind": "loopback",
|
||||
"auth": {
|
||||
"mode": "token",
|
||||
"token": "sandbox-dev-token-12345"
|
||||
},
|
||||
"controlUi": { "enabled": true }
|
||||
},
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "openai/gpt-5.2",
|
||||
"fallbacks": ["openai/gpt-5.2-chat-latest"]
|
||||
},
|
||||
"workspace": "/home/node/.openclaw/workspace"
|
||||
}
|
||||
}
|
||||
}
|
||||
INNEREOF
|
||||
chmod 600 /home/node/.openclaw/openclaw.json
|
||||
'
|
||||
|
||||
# 5. Start the gateway (pass your API key from ~/.secrets)
|
||||
source ~/.secrets
|
||||
docker sandbox exec -d \
|
||||
-e OPENAI_API_KEY="$OPENAI_API_KEY" \
|
||||
-w /app openclaw \
|
||||
node dist/index.js gateway --bind loopback --port 18789
|
||||
|
||||
# 6. Wait ~15 seconds, then verify
|
||||
sleep 15
|
||||
docker sandbox exec openclaw curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/
|
||||
# Should print: 200
|
||||
|
||||
# 7. Check status
|
||||
docker sandbox exec -e OPENAI_API_KEY="$OPENAI_API_KEY" -w /app openclaw \
|
||||
node dist/index.js status
|
||||
```
|
||||
|
||||
### Sandbox Management
|
||||
|
||||
```bash
|
||||
# List sandboxes
|
||||
docker sandbox ls
|
||||
|
||||
# Shell into the sandbox
|
||||
docker sandbox exec -it openclaw bash
|
||||
|
||||
# Stop the sandbox (preserves state)
|
||||
docker sandbox stop openclaw
|
||||
|
||||
# Remove the sandbox
|
||||
docker sandbox rm openclaw
|
||||
|
||||
# Check sandbox version
|
||||
docker sandbox version
|
||||
```
|
||||
|
||||
## Option B: Docker Compose (Fallback)
|
||||
|
||||
Use this if Docker Sandbox is not available (Docker Desktop < v29).
|
||||
|
||||
```bash
|
||||
# 1. Clone the OpenClaw repo
|
||||
git clone https://github.com/openclaw/openclaw.git /tmp/openclaw-docker
|
||||
cd /tmp/openclaw-docker
|
||||
|
||||
# 2. Build the Docker image (~5-10 min on first run)
|
||||
docker build -t openclaw:local -f Dockerfile .
|
||||
|
||||
# 3. Create config directories
|
||||
mkdir -p ~/.openclaw/workspace ~/.openclaw/identity ~/.openclaw/credentials
|
||||
chmod 700 ~/.openclaw ~/.openclaw/credentials
|
||||
|
||||
# 4. Generate a gateway token
|
||||
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
|
||||
echo "Your gateway token: $OPENCLAW_GATEWAY_TOKEN"
|
||||
|
||||
# 5. Create the config file
|
||||
cat > ~/.openclaw/openclaw.json << EOF
|
||||
{
|
||||
"gateway": {
|
||||
"mode": "local",
|
||||
"port": 18789,
|
||||
"bind": "lan",
|
||||
"auth": {
|
||||
"mode": "token",
|
||||
"token": "$OPENCLAW_GATEWAY_TOKEN"
|
||||
},
|
||||
"controlUi": {
|
||||
"enabled": true,
|
||||
"allowedOrigins": ["http://127.0.0.1:18789"]
|
||||
}
|
||||
},
|
||||
"env": {
|
||||
"OPENAI_API_KEY": "\${OPENAI_API_KEY}"
|
||||
},
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "openai/gpt-5.2",
|
||||
"fallbacks": ["openai/gpt-5.2-chat-latest"]
|
||||
},
|
||||
"workspace": "/home/node/.openclaw/workspace"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
chmod 600 ~/.openclaw/openclaw.json
|
||||
|
||||
# 6. Create the .env file (load API keys from ~/.secrets)
|
||||
source ~/.secrets
|
||||
cat > .env << EOF
|
||||
OPENCLAW_CONFIG_DIR=$HOME/.openclaw
|
||||
OPENCLAW_WORKSPACE_DIR=$HOME/.openclaw/workspace
|
||||
OPENCLAW_GATEWAY_PORT=18789
|
||||
OPENCLAW_BRIDGE_PORT=18790
|
||||
OPENCLAW_GATEWAY_BIND=lan
|
||||
OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN
|
||||
OPENCLAW_IMAGE=openclaw:local
|
||||
OPENAI_API_KEY=$OPENAI_API_KEY
|
||||
OPENCLAW_EXTRA_MOUNTS=
|
||||
OPENCLAW_HOME_VOLUME=
|
||||
OPENCLAW_DOCKER_APT_PACKAGES=
|
||||
EOF
|
||||
|
||||
# 7. Add tmpfs to docker-compose.yml (required — see Known Issues)
|
||||
# Add to BOTH openclaw-gateway and openclaw-cli services:
|
||||
# tmpfs:
|
||||
# - /tmp:exec,size=512M
|
||||
|
||||
# 8. Start the gateway
|
||||
docker compose up -d openclaw-gateway
|
||||
|
||||
# 9. Wait ~15 seconds for startup, then get the dashboard URL
|
||||
sleep 15
|
||||
docker compose run --rm openclaw-cli dashboard --no-open
|
||||
```
|
||||
|
||||
The dashboard URL will look like: `http://127.0.0.1:18789/#token=<your-token>`
|
||||
|
||||
### Docker Compose Management
|
||||
|
||||
```bash
|
||||
cd /tmp/openclaw-docker
|
||||
|
||||
# Stop
|
||||
docker compose down
|
||||
|
||||
# Start again (no rebuild needed)
|
||||
docker compose up -d openclaw-gateway
|
||||
|
||||
# View logs
|
||||
docker compose logs -f openclaw-gateway
|
||||
|
||||
# Check status
|
||||
docker compose run --rm openclaw-cli status
|
||||
|
||||
# Get dashboard URL
|
||||
docker compose run --rm openclaw-cli dashboard --no-open
|
||||
```
|
||||
|
||||
## Known Issues and Fixes
|
||||
|
||||
### "no space left on device" when starting containers
|
||||
|
||||
Docker Desktop's virtual disk may be full.
|
||||
|
||||
```bash
|
||||
docker system df # check usage
|
||||
docker system prune -f # remove stopped containers, unused networks
|
||||
docker image prune -f # remove dangling images
|
||||
```
|
||||
|
||||
### "Unable to create fallback OpenClaw temp dir: /tmp/openclaw-1000" (Compose only)
|
||||
|
||||
The container can't write to `/tmp`. Add a `tmpfs` mount to `docker-compose.yml` for **both** services:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openclaw-gateway:
|
||||
tmpfs:
|
||||
- /tmp:exec,size=512M
|
||||
openclaw-cli:
|
||||
tmpfs:
|
||||
- /tmp:exec,size=512M
|
||||
```
|
||||
|
||||
This issue does not affect the Docker Sandbox approach.
|
||||
|
||||
### Node version mismatch in community template images
|
||||
|
||||
Some community-built sandbox templates (e.g. `olegselajev241/openclaw-dmr:latest`) ship Node 20, but OpenClaw requires Node >=22.12.0. Use our locally built `openclaw:local` image as the sandbox template instead, which includes Node 22.
|
||||
|
||||
### Gateway takes ~15 seconds to respond after start
|
||||
|
||||
The Node.js gateway needs time to initialize. Wait 15 seconds before hitting `http://127.0.0.1:18789/`.
|
||||
|
||||
### CLAUDE_AI_SESSION_KEY warnings (Compose only)
|
||||
|
||||
These Docker Compose warnings are harmless and can be ignored:
|
||||
```
|
||||
level=warning msg="The \"CLAUDE_AI_SESSION_KEY\" variable is not set. Defaulting to a blank string."
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Config file: `~/.openclaw/openclaw.json` (JSON5 format)
|
||||
|
||||
Key settings:
|
||||
- `gateway.auth.token` — the auth token for the web UI and API
|
||||
- `agents.defaults.model.primary` — the AI model (use `openai/gpt-5.2` or newer)
|
||||
- `env.OPENAI_API_KEY` — references the `OPENAI_API_KEY` env var (Compose approach)
|
||||
|
||||
API keys are stored in `~/.secrets` and passed into containers via env vars.
|
||||
|
||||
## Reference
|
||||
|
||||
- [OpenClaw Docker docs](https://docs.openclaw.ai/install/docker)
|
||||
- [OpenClaw Configuration Reference](https://docs.openclaw.ai/gateway/configuration-reference)
|
||||
- [Docker blog: Run OpenClaw Securely in Docker Sandboxes](https://www.docker.com/blog/run-openclaw-securely-in-docker-sandboxes/)
|
||||
- [Docker Sandbox docs](https://docs.docker.com/ai/sandboxes)
|
||||
- [OpenAI Models](https://platform.openai.com/docs/models) — current models: gpt-5.2, gpt-5.2-chat-latest, gpt-5.2-pro
|
||||
100
docs/start/architecture.md
Normal file
100
docs/start/architecture.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: Architecture
|
||||
summary: Stack overview, request flow, and adapter model
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
Paperclip is a monorepo with four main layers.
|
||||
|
||||
## Stack Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ React UI (Vite) │
|
||||
│ Dashboard, org management, tasks │
|
||||
├─────────────────────────────────────┤
|
||||
│ Express.js REST API (Node.js) │
|
||||
│ Routes, services, auth, adapters │
|
||||
├─────────────────────────────────────┤
|
||||
│ PostgreSQL (Drizzle ORM) │
|
||||
│ Schema, migrations, embedded mode │
|
||||
├─────────────────────────────────────┤
|
||||
│ Adapters │
|
||||
│ Claude Local, Codex Local, │
|
||||
│ Process, HTTP │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|-----------|
|
||||
| Frontend | React 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query |
|
||||
| Backend | Node.js 20+, Express.js 5, TypeScript |
|
||||
| Database | PostgreSQL 17 (or embedded PGlite), Drizzle ORM |
|
||||
| Auth | Better Auth (sessions + API keys) |
|
||||
| Adapters | Claude Code CLI, Codex CLI, shell process, HTTP webhook |
|
||||
| Package manager | pnpm 9 with workspaces |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
paperclip/
|
||||
├── ui/ # React frontend
|
||||
│ ├── src/pages/ # Route pages
|
||||
│ ├── src/components/ # React components
|
||||
│ ├── src/api/ # API client
|
||||
│ └── src/context/ # React context providers
|
||||
│
|
||||
├── server/ # Express.js API
|
||||
│ ├── src/routes/ # REST endpoints
|
||||
│ ├── src/services/ # Business logic
|
||||
│ ├── src/adapters/ # Agent execution adapters
|
||||
│ └── src/middleware/ # Auth, logging
|
||||
│
|
||||
├── packages/
|
||||
│ ├── db/ # Drizzle schema + migrations
|
||||
│ ├── shared/ # API types, constants, validators
|
||||
│ ├── adapter-utils/ # Adapter interfaces and helpers
|
||||
│ └── adapters/
|
||||
│ ├── claude-local/ # Claude Code adapter
|
||||
│ └── codex-local/ # OpenAI Codex adapter
|
||||
│
|
||||
├── skills/ # Agent skills
|
||||
│ └── paperclip/ # Core Paperclip skill (heartbeat protocol)
|
||||
│
|
||||
├── cli/ # CLI client
|
||||
│ └── src/ # Setup and control-plane commands
|
||||
│
|
||||
└── doc/ # Internal documentation
|
||||
```
|
||||
|
||||
## Request Flow
|
||||
|
||||
When a heartbeat fires:
|
||||
|
||||
1. **Trigger** — Scheduler, manual invoke, or event (assignment, mention) triggers a heartbeat
|
||||
2. **Adapter invocation** — Server calls the configured adapter's `execute()` function
|
||||
3. **Agent process** — Adapter spawns the agent (e.g. Claude Code CLI) with Paperclip env vars and a prompt
|
||||
4. **Agent work** — The agent calls Paperclip's REST API to check assignments, checkout tasks, do work, and update status
|
||||
5. **Result capture** — Adapter captures stdout, parses usage/cost data, extracts session state
|
||||
6. **Run record** — Server records the run result, costs, and any session state for next heartbeat
|
||||
|
||||
## Adapter Model
|
||||
|
||||
Adapters are the bridge between Paperclip and agent runtimes. Each adapter is a package with three modules:
|
||||
|
||||
- **Server module** — `execute()` function that spawns/calls the agent, plus environment diagnostics
|
||||
- **UI module** — stdout parser for the run viewer, config form fields for agent creation
|
||||
- **CLI module** — terminal formatter for `paperclip run --watch`
|
||||
|
||||
Built-in adapters: `claude_local`, `codex_local`, `process`, `http`. You can create custom adapters for any runtime.
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
- **Control plane, not execution plane** — Paperclip orchestrates agents; it doesn't run them
|
||||
- **Company-scoped** — all entities belong to exactly one company; strict data boundaries
|
||||
- **Single-assignee tasks** — atomic checkout prevents concurrent work on the same task
|
||||
- **Adapter-agnostic** — any runtime that can call an HTTP API works as an agent
|
||||
- **Embedded by default** — zero-config local mode with embedded PostgreSQL
|
||||
77
docs/start/core-concepts.md
Normal file
77
docs/start/core-concepts.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Core Concepts
|
||||
summary: Companies, agents, issues, heartbeats, and governance
|
||||
---
|
||||
|
||||
# Core Concepts
|
||||
|
||||
Paperclip organizes autonomous AI work around five key concepts.
|
||||
|
||||
## Company
|
||||
|
||||
A company is the top-level unit of organization. Each company has:
|
||||
|
||||
- A **goal** — the reason it exists (e.g. "Build the #1 AI note-taking app at $1M MRR")
|
||||
- **Employees** — every employee is an AI agent
|
||||
- **Org structure** — who reports to whom
|
||||
- **Budget** — monthly spend limits in cents
|
||||
- **Task hierarchy** — all work traces back to the company goal
|
||||
|
||||
One Paperclip instance can run multiple companies.
|
||||
|
||||
## Agents
|
||||
|
||||
Every employee is an AI agent. Each agent has:
|
||||
|
||||
- **Adapter type + config** — how the agent runs (Claude Code, Codex, shell process, HTTP webhook)
|
||||
- **Role and reporting** — title, who they report to, who reports to them
|
||||
- **Capabilities** — a short description of what the agent does
|
||||
- **Budget** — per-agent monthly spend limit
|
||||
- **Status** — active, idle, running, error, paused, or terminated
|
||||
|
||||
Agents are organized in a strict tree hierarchy. Every agent reports to exactly one manager (except the CEO). This chain of command is used for escalation and delegation.
|
||||
|
||||
## Issues (Tasks)
|
||||
|
||||
Issues are the unit of work. Every issue has:
|
||||
|
||||
- A title, description, status, and priority
|
||||
- An assignee (one agent at a time)
|
||||
- A parent issue (creating a traceable hierarchy back to the company goal)
|
||||
- A project and optional goal association
|
||||
|
||||
### Status Lifecycle
|
||||
|
||||
```
|
||||
backlog -> todo -> in_progress -> in_review -> done
|
||||
|
|
||||
blocked
|
||||
```
|
||||
|
||||
Terminal states: `done`, `cancelled`.
|
||||
|
||||
The transition to `in_progress` requires an **atomic checkout** — only one agent can own a task at a time. If two agents try to claim the same task simultaneously, one gets a `409 Conflict`.
|
||||
|
||||
## Heartbeats
|
||||
|
||||
Agents don't run continuously. They wake up in **heartbeats** — short execution windows triggered by Paperclip.
|
||||
|
||||
A heartbeat can be triggered by:
|
||||
|
||||
- **Schedule** — periodic timer (e.g. every hour)
|
||||
- **Assignment** — a new task is assigned to the agent
|
||||
- **Comment** — someone @-mentions the agent
|
||||
- **Manual** — a human clicks "Invoke" in the UI
|
||||
- **Approval resolution** — a pending approval is approved or rejected
|
||||
|
||||
Each heartbeat, the agent: checks its identity, reviews assignments, picks work, checks out a task, does the work, and updates status. This is the **heartbeat protocol**.
|
||||
|
||||
## Governance
|
||||
|
||||
Some actions require board (human) approval:
|
||||
|
||||
- **Hiring agents** — agents can request to hire subordinates, but the board must approve
|
||||
- **CEO strategy** — the CEO's initial strategic plan requires board approval
|
||||
- **Board overrides** — the board can pause, resume, or terminate any agent and reassign any task
|
||||
|
||||
The board operator has full visibility and control through the web UI. Every mutation is logged in an **activity audit trail**.
|
||||
61
docs/start/quickstart.md
Normal file
61
docs/start/quickstart.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Quickstart
|
||||
summary: Get Paperclip running in minutes
|
||||
---
|
||||
|
||||
# Quickstart
|
||||
|
||||
Get Paperclip running locally in under 5 minutes.
|
||||
|
||||
## Option 1: Docker Compose (Recommended)
|
||||
|
||||
The fastest way to start. No Node.js install needed.
|
||||
|
||||
```sh
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
Open [http://localhost:3100](http://localhost:3100). That's it.
|
||||
|
||||
The Docker image includes Claude Code CLI and Codex CLI pre-installed for local adapter runs. Pass API keys to enable them:
|
||||
|
||||
```sh
|
||||
ANTHROPIC_API_KEY=sk-... OPENAI_API_KEY=sk-... \
|
||||
docker compose -f docker-compose.quickstart.yml up --build
|
||||
```
|
||||
|
||||
## Option 2: Local Development
|
||||
|
||||
Prerequisites: Node.js 20+ and pnpm 9+.
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
This starts the API server and UI at [http://localhost:3100](http://localhost:3100).
|
||||
|
||||
No Docker or external database required — Paperclip uses an embedded PostgreSQL instance by default.
|
||||
|
||||
## Option 3: One-Command Bootstrap
|
||||
|
||||
```sh
|
||||
pnpm paperclip run
|
||||
```
|
||||
|
||||
This auto-onboards if config is missing, runs health checks with auto-repair, and starts the server.
|
||||
|
||||
## What's Next
|
||||
|
||||
Once Paperclip is running:
|
||||
|
||||
1. Create your first company in the web UI
|
||||
2. Define a company goal
|
||||
3. Create a CEO agent and configure its adapter
|
||||
4. Build out the org chart with more agents
|
||||
5. Set budgets and assign initial tasks
|
||||
6. Hit go — agents start their heartbeats and the company runs
|
||||
|
||||
<Card title="Core Concepts" href="/start/core-concepts">
|
||||
Learn the key concepts behind Paperclip
|
||||
</Card>
|
||||
41
docs/start/what-is-paperclip.md
Normal file
41
docs/start/what-is-paperclip.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: What is Paperclip?
|
||||
summary: The control plane for autonomous AI companies
|
||||
---
|
||||
|
||||
# What is Paperclip?
|
||||
|
||||
Paperclip is the control plane for autonomous AI companies. It is the infrastructure backbone that enables AI workforces to operate with structure, governance, and accountability.
|
||||
|
||||
One instance of Paperclip can run multiple companies. Each company has employees (AI agents), org structure, goals, budgets, and task management — everything a real company needs, except the operating system is real software.
|
||||
|
||||
## The Problem
|
||||
|
||||
Task management software doesn't go far enough. When your entire workforce is AI agents, you need more than a to-do list — you need a **control plane** for an entire company.
|
||||
|
||||
## What Paperclip Does
|
||||
|
||||
Paperclip is the command, communication, and control plane for a company of AI agents. It is the single place where you:
|
||||
|
||||
- **Manage agents as employees** — hire, organize, and track who does what
|
||||
- **Define org structure** — org charts that agents themselves operate within
|
||||
- **Track work in real time** — see at any moment what every agent is working on
|
||||
- **Control costs** — token salary budgets per agent, spend tracking, burn rate
|
||||
- **Align to goals** — agents see how their work serves the bigger mission
|
||||
- **Govern autonomy** — board approval gates, activity audit trails, budget enforcement
|
||||
|
||||
## Two Layers
|
||||
|
||||
### 1. Control Plane (Paperclip)
|
||||
|
||||
The central nervous system. Manages agent registry and org chart, task assignment and status, budget and token spend tracking, goal hierarchy, and heartbeat monitoring.
|
||||
|
||||
### 2. Execution Services (Adapters)
|
||||
|
||||
Agents run externally and report into the control plane. Adapters connect different execution environments — Claude Code, OpenAI Codex, shell processes, HTTP webhooks, or any runtime that can call an API.
|
||||
|
||||
The control plane doesn't run agents. It orchestrates them. Agents run wherever they run and phone home.
|
||||
|
||||
## Core Principle
|
||||
|
||||
You should be able to look at Paperclip and understand your entire company at a glance — who's doing what, how much it costs, and whether it's working.
|
||||
Reference in New Issue
Block a user