Paperclip: How to Run a One-Person Company with This Open Source Framework

Paperclip: How to Run a One-Person Company with This Open Source FrameworkPreecha

Run a One-Person Company With Paperclip and Apidog Paperclip is an open-source framework...

Run a One-Person Company With Paperclip and Apidog

Paperclip is an open-source framework for operating AI agents like employees: define an org chart, assign budgets, schedule heartbeats, require governance approvals, and retain an audit log. Start it locally with one command, then direct the work instead of manually coordinating every agent.

Try Apidog today

A one-person company in 2026 does not mean doing every task alone. It means setting strategy while AI agents execute structured work. Paperclip provides the self-hosted control plane for that model: agents have roles, reporting lines, monthly budgets, goals, and assigned issues. If you use Apidog to design, mock, and test APIs, the split is straightforward:

  • Apidog owns the API contract.
  • Paperclip owns the agents that implement and call that contract.

Use Apidog mock URLs in Paperclip task descriptions so agents can build against a defined API response before production APIs are available. Then use API and contract tests to catch drift before agent runs consume more budget.

What Paperclip Does

Paperclip is a Node.js server with a React UI for organizing AI agents as a company. It is not a chatbot, prompt manager, or visual workflow builder. It is a control plane for assigning work, tracking outcomes, enforcing constraints, and reviewing decisions.

Its core concepts map directly to familiar company operations:

  • Org chart: Agents have roles, titles, and managers.
  • Issues: Work is tracked with a status, priority, assignee, and history.
  • Goals: Tasks can be connected to higher-level company objectives.
  • Heartbeats: Agents wake on a schedule, inspect their inbox, perform work, and report back.
  • Budgets: Each agent has a monthly token-spend limit.
  • Governance: Important actions, such as agent hires or strategy decisions, can require approval.
  • Audit log: Activity is recorded so you can review what an agent changed and why.

This helps replace an unstructured collection of agent sessions with a repeatable operating model. Instead of tracking work across tabs and chat histories, define the task, assign it to an agent, set a budget, and review the result.

Where Apidog Fits

Apidog covers a different layer of the stack: API design, mocking, testing, and contract validation.

A useful division of responsibility is:

Concern Tool
API request and response contracts Apidog
Mock endpoints during implementation Apidog
Contract and API testing Apidog
Agent roles, tasks, and schedules Paperclip
Spend limits and approval gates Paperclip
Agent activity history Paperclip

For example, an agent may be assigned to add pagination to an internal service. Apidog provides the expected request and response shape; Paperclip provides the context, ownership, schedule, budget, and audit trail for the work.

How Heartbeats Work

A heartbeat is Paperclip's execution loop. During a typical run, an agent:

  1. Confirms its identity with GET /api/agents/me.
  2. Reads assigned work with GET /api/companies/:id/issues?status=todo,in_progress.
  3. Loads task details and parent-goal context with GET /api/issues/:id.
  4. Performs the assigned work, such as writing code, calling an API, or generating content.
  5. Reports progress with PATCH /api/issues/:id, including a status update and comment.

When the task includes API work, give the agent an Apidog mock endpoint first. The agent can validate the expected response shape during development, while the implementation remains decoupled from a live dependency.

For example, a task can instruct an agent to query a mock customer-data API, generate a weekly report, and later switch the base URL to the production endpoint without changing the application logic.

Use Goal Context to Avoid Local Optimization

Paperclip organizes work from company goals down to individual tasks:

Company → Team → Agent → Task
Enter fullscreen mode Exit fullscreen mode

An agent receives its ancestor context when it works on a task. That means a task such as “write a blog post” can remain connected to a larger goal such as “grow SEO traffic,” which can in turn support a company objective.

Use the same pattern for APIs:

  1. Define an internal service contract in Apidog.
  2. Publish an Apidog mock server for the service.
  3. Reference the mock URL and acceptance criteria in a Paperclip issue.
  4. Update the Apidog specification when the contract changes.
  5. Have downstream agents use the updated contract as their implementation reference.

This gives agents an explicit API contract instead of requiring them to infer one from an incomplete codebase.

Enforce Agent Budgets

Paperclip assigns each agent a budgetMonthlyCents value. When an agent reaches its spentMonthlyCents ceiling, it stops accepting tasks.

That creates a practical operating constraint for solo founders. You can assign an agent a fixed monthly budget, review its output, and increase its budget only when the results justify it.

Combine budgets with mock-first development:

  1. Build and test against Apidog mocks.
  2. Validate request and response behavior against the API specification.
  3. Move to live services only after the contract and implementation are ready.
  4. Keep production agent work within the budget configured in Paperclip.

Start Paperclip Locally

Bootstrap Paperclip with:

npx paperclipai onboard --yes
Enter fullscreen mode Exit fullscreen mode

This command bootstraps an embedded PostgreSQL database, generates a master encryption key, applies database migrations, and starts the server at:

http://localhost:3100
Enter fullscreen mode Exit fullscreen mode

After the server starts:

  1. Open the Paperclip UI.
  2. Create a company.
  3. Add a company goal.
  4. Create an agent.
  5. Assign the agent an initial task that references an Apidog mock or collection.

For example, start with a concrete company goal:

Build the #1 AI-powered API monitoring tool to $1M MRR.
Enter fullscreen mode Exit fullscreen mode

Then configure a backend-focused agent with a monthly budget:

{
  "adapterType": "claude_local",
  "adapterConfig": {
    "model": "claude-opus-4-6",
    "maxTokens": 4096
  },
  "budgetMonthlyCents": 2000
}
Enter fullscreen mode Exit fullscreen mode

Give Agents Tasks With an API Contract

Paperclip task descriptions support rich Markdown and include ancestor context. Make the API dependency explicit in the task itself.

## Task: Add pagination to the `/users` endpoint

**Apidog Mock Base:** `http://localhost:4523/m1/123456/users`

**Acceptance criteria:**

- Endpoint accepts `page` and `limit` query parameters.
- Response uses the `{ data: [], total: 0, page: 1 }` envelope.
- Unit tests cover edge cases, including `page=0` and `limit>100`.
Enter fullscreen mode Exit fullscreen mode

This gives the agent three things it needs before implementation:

  • The endpoint to validate against.
  • The required response shape.
  • The conditions that define completion.

The agent can call the mock endpoint, implement the feature, run tests, and add a completion comment to the issue.

Manage the Task Lifecycle From the CLI

Use the Paperclip CLI to create, inspect, and release work.

Create an issue for an Apidog-defined endpoint:

pnpm paperclipai issue create \
  --company-id <id> \
  --title "Implement POST /webhooks endpoint per Apidog spec" \
  --description "See Apidog collection: http://localhost:4523/..."
Enter fullscreen mode Exit fullscreen mode

Check in-progress work:

pnpm paperclipai issue list \
  --company-id <id> \
  --status in_progress
Enter fullscreen mode Exit fullscreen mode

Release an issue if the assigned agent is blocked:

pnpm paperclipai issue release <issue-id>
Enter fullscreen mode Exit fullscreen mode

Paperclip records issue changes in its activity log, allowing you to review which agent worked on a task and what it reported.

Add Approval Gates

Paperclip's governance model lets agents propose actions while you retain final control over consequential decisions.

List pending approvals:

pnpm paperclipai approval list --company-id <id>
Enter fullscreen mode Exit fullscreen mode

Approve an agent hire or decision:

pnpm paperclipai approval approve <approval-id> \
  --decision-note "Approved. Use Apidog mock for first sprint."
Enter fullscreen mode Exit fullscreen mode

Use approval gates for actions that should not be fully autonomous, such as hiring new agents, changing strategic direction, or moving work from mocked APIs to live production dependencies.

Test the Stack

Paperclip includes Vitest unit tests and Playwright end-to-end tests.

Run the unit test suite:

pnpm test:run
Enter fullscreen mode Exit fullscreen mode

Run end-to-end tests:

pnpm test:e2e
Enter fullscreen mode Exit fullscreen mode

Verify that the Paperclip server is available:

curl http://localhost:3100/api/health
Enter fullscreen mode Exit fullscreen mode

The unit tests cover core behavior including issue state transitions, budget enforcement, heartbeat lifecycle, and agent authentication. When adding a custom adapter for another AI provider, run the existing suite to verify that orchestration behavior remains intact.

Use a Three-Layer Quality Check

A practical quality workflow combines API contracts, task acceptance criteria, and implementation tests:

  1. Apidog: Define the API contract and run API or contract tests.
  2. Paperclip: Put the Apidog URL and measurable acceptance criteria in the issue.
  3. Unit tests: Verify that the implementation matches the expected behavior.

This creates a reviewable path from specification to agent task to tested implementation—without requiring a large team to coordinate it manually.

Getting Started Checklist

  • Bootstrap Paperclip: 
  npx paperclipai onboard --yes
Enter fullscreen mode Exit fullscreen mode
  • Open http://localhost:3100, create a company, and define a goal.
  • Add an agent with a fixed monthly budget.
  • Create an Apidog mock for the first API dependency.
  • Include the mock URL and acceptance criteria in the Paperclip task.
  • Run the unit tests before the first production heartbeat: 
  pnpm test:run
Enter fullscreen mode Exit fullscreen mode
  • Review the agent’s task comments and audit-log entries before approving additional work.

Paperclip provides the operating structure for AI agents. Apidog provides the API contracts those agents need to implement and consume. Together, they support a one-person company model where strategy, execution, testing, cost control, and governance are explicit parts of the system.

FAQ

What is Paperclip?

Paperclip is an open-source one-person company framework: a Node.js server and React UI for orchestrating AI agents with org charts, budgets, heartbeat scheduling, tasks, governance, and audit logs.

How does Paperclip integrate with Apidog?

Apidog defines the API contracts agents work against. Include Apidog mock URLs in Paperclip task descriptions, have agents use those mocks during development, and use API contract tests to validate the implementation. Paperclip handles orchestration; Apidog handles API specification.

Is Paperclip suitable for a true one-person company?

Yes. Its local setup uses:

npx paperclipai onboard --yes
Enter fullscreen mode Exit fullscreen mode

Budget limits control spend, heartbeats support recurring work, and the same configuration can be used from local development through cloud deployment.

How do I run the tests?

Run the Vitest unit suite:

pnpm test:run
Enter fullscreen mode Exit fullscreen mode

Run the Playwright end-to-end suite:

pnpm test:e2e
Enter fullscreen mode Exit fullscreen mode

Check that the server is running:

curl http://localhost:3100/api/health
Enter fullscreen mode Exit fullscreen mode

What AI agents does Paperclip support?

Paperclip supports Claude, including local and OpenClaw-based setups, along with Codex, Cursor, Gemini, OpenCode, and agents that communicate over HTTP or run as local processes. Its adapter system is open, so an agent that can receive a heartbeat can be integrated.

Is Paperclip open source?

Yes. Paperclip is MIT-licensed and maintained at github.com/paperclipai/paperclip. Its plugin SDK, adapter packages, and skill definitions are published under the @paperclipai/* npm scope.