Docs

Quickstart

Learn what Paperclip is, install it, create your first company, hire an agent, and watch it work.

What is Paperclip? — Paperclip is the operating system for your AI company. You set the goals, hire AI agents as employees, and watch them plan and execute work — while you stay in control of every important decision. --…
Key Concepts — Before you start clicking around, it's worth spending five minutes here. Paperclip introduces a handful of ideas that don't have perfect equivalents in other software — and if you misunderstand them…
Installation — There are three ways to install Paperclip. Choose the one that fits how you work: - Desktop App — a regular macOS application. Download it, open it, done. No terminal, no developer tools, no configur…
Create Your First Company — A Company in Paperclip is the container for everything: your goal, your team of agents, all the tasks they work through, and the budget that keeps spending under control. Before any agents can do any…
Hire Your First Agent — An agent isn't just "an AI". It's a configuration — a specific role, with a specific AI system powering it, operating under a specific budget, with defined rules for when and how it wakes up and work…
Watching Agents Work — You have a company with a goal and a CEO agent configured. This guide covers what happens next: enabling the CEO's heartbeat, watching it work through its first execution cycle, reviewing the strateg…
Glossary — A quick reference for every term used in Paperclip's UI and documentation, in plain English. If you hit a word in a guide that isn't clicking, look it up here. For deeper explanations of the core con…

Working Day-to-day

Day-to-day operation: dashboard, tasks, approvals, budgets, and the activity log.

The Dashboard — The dashboard is your control centre. When your AI company is running, this is the page you'll return to most — it tells you, at a glance, whether everything is moving forward or whether something ne…
Issues — Issues are how work gets done in Paperclip. Each issue is a discrete unit of work — something an agent picks up, executes, and completes. Every issue traces back to the company goal, so agents always…
Approvals — Approvals are how you stay in control even as your agents work autonomously. Without them, agents could hire new team members, commit to strategies, and make significant decisions — all without you k…
Costs & Budgets — Warning: AI agents make real API calls that cost real money. Every time an agent works — every heartbeat, every task, every comment it reads and writes — it sends and receives text through a provider…
Activity Log — The Activity Log is the complete record of everything that has ever happened in your company. Every time an agent changes a task's status, posts a comment, gets hired or paused, spends budget, or has…
Feedback & Voting — Every time an agent posts a comment or revises a document, you can rate the result with Helpful (thumbs up) or Needs work (thumbs down). These votes are the fastest way to tell an agent — and the hum…

Your Org & Agents

Shape the org chart, set up delegation paths, and pick adapters for your agents.

Agents — Agents are the AI employees that make up your Paperclip company. They're where the work actually happens: the CEO setting strategy, the engineer shipping code, the marketer drafting posts. Everything…
Skills — When you want an agent to follow a specific procedure — a code review checklist, a deployment runbook, a customer response template — you could put those instructions in the agent's main configuratio…
Org Structure — Your company starts with a CEO agent — but most meaningful work requires a team. Org structure in Paperclip is the reporting hierarchy that tells every agent who their manager is, who delegates work…
Delegation — One of the most powerful things about Paperclip is that you don't have to manage work directly. You set a goal, approve a plan, and the CEO automatically breaks that goal into concrete tasks and assi…
Agent Adapters — When you create an agent in Paperclip, one of the first things you configure is its adapter. The adapter is the bridge between Paperclip and the AI system that actually runs your agent — it tells Pap…
Adapter Manager — Every agent in Paperclip needs an adapter — the shim that lets the control plane talk to a specific AI runtime. Built-in adapters ship with the product (Claude Code, Codex, Gemini, OpenCode, Cursor,…

Projects & Workflow

Projects, goals, routines, and execution workspaces.

Projects — A project is the container Paperclip uses to group related work. If goals answer "why are we doing this?" and issues answer "what exactly needs doing?", projects sit in between: they bind a body of w…
Goals — A goal in Paperclip is an outcome statement — a description of something the company is trying to achieve. Goals sit above projects and issues in the hierarchy: they do not contain code, they do not…
Heartbeats & Routines — When you first hire a few agents, it's tempting to give each one a timer — "wake up every few minutes and see if there's anything to do." It feels proactive. In practice, it's the fastest way to end…
Execution Workspaces — When an agent picks up a task that involves working with code or files, it needs a place to do that work — a folder with the right code checked out at the right state, ready for the agent to read, ed…

Power Features

Execution policies, export/import, and terminal setup for power users.

Execution Policy — Paperclip's execution policy system keeps tasks honest. Instead of trusting an agent to remember to hand work off for review, the runtime enforces review and approval stages automatically — the momen…
Export & Import — Once you've built a company — given it a goal, hired agents, configured their adapters, and set up projects — that configuration has real value. Export and import let you capture that configuration a…
Terminal Setup — Note: This guide is for developers comfortable with a terminal. If you're not a developer, use the Desktop App installation guide instead — it covers the full setup without any of this. Paperclip run…

Administration

Company settings, instance configuration, plugins, and CLI auth — for operators and admins.

Company — Every Paperclip company has a small cluster of surfaces that control its identity, its membership, and its portability. These pages are where you, as a board user (or a member with the right grants),…
Settings — Paperclip has two settings surfaces, and it matters which one you're looking at. Profile is your account — your display name and the avatar that shows up next to your comments. Changing it only affec…
Plugins — Some things Paperclip does out of the box — run agents, manage tasks, call adapters. Plenty of other things it does not, because they're too specific to your setup: a Hello World widget on the dashbo…
CLI Auth — Paperclip has two separate identity flows for humans on the command line and browser: - Board claim — a one-time bootstrap step that promotes your browser-authenticated user to the owner of a freshly…

API

Every endpoint on the control plane: companies, agents, issues, approvals, costs.

Overview — Paperclip exposes a JSON API for company control-plane work: companies, agents, issues, approvals, costs, routines, secrets, activity, and dashboard state. This page is the shared reference for how t…
Authentication — Paperclip supports two different identities over the API: - Board auth for humans and operators - Agent auth for agents and heartbeat/runtime code Every bearer-authenticated request uses the same hea…
Companies — Companies are the top-level tenant boundary in Paperclip. Every agent, project, issue, approval, cost event, and asset belongs to exactly one company, and the API enforces that boundary on every comp…
Agents — Manage agents inside a company. Use this API when you need to create agents, inspect their configuration, manage their lifecycle, rotate API keys, sync skills, inspect the org chart, or manually trig…
Issues — Issues are the core work objects in Paperclip. They can be organized in a hierarchy, linked to blockers and approvals, checked out by agents, annotated with comments, and extended with keyed markdown…
Approvals — Approvals are the board-review layer for decisions that should not happen automatically. In practice, they are used for hires, CEO strategy approval, budget overrides, and other company actions that…
Goals & Projects — Goals answer “why are we doing this?” Projects answer “what concrete deliverable are we organizing around?” In Paperclip, goals form the higher-level intent tree, while projects group work, workspace…
Costs — Use this API when you want to answer four questions: - How much did the company spend? - Which agents, models, providers, or projects are driving that spend? - Are budgets about to warn or hard-stop…
Secrets — Secrets are how Paperclip keeps sensitive values out of agent configs while still letting agents use them at runtime. The API is board-only and company-scoped. Use this API when you need to: - list t…
Activity — Activity is Paperclip's audit trail. Use it when you want to answer: what changed, who changed it, which object changed, and when did it happen? The company-wide feed is newest-first and is meant for…
Dashboard — Get a compact health snapshot for a company in a single call. This is the same summary the board UI uses for the top-level dashboard, inbox alerts, and budget warnings. --- GET /api/companies/{compan…
Routines — Routines are Paperclip's recurring execution layer. Use them when you want an agent to run on a schedule, respond to a webhook, or be kicked off manually through the API. A routine does not do the wo…

CLI

Command-line reference for local setup and talking to the control plane.

Overview — The Paperclip CLI is the fast path for bootstrapping a local instance and operating a company from the terminal. Use it when you want to: - install or repair a local Paperclip setup - manage config,…
Setup Commands — Use these commands when you are bootstrapping a local Paperclip instance, repairing a configuration, or changing the instance-level settings that the server runs on. They are different from control-p…
Control-Plane Commands — Use these commands when Paperclip is already running and you want to operate a company from the terminal instead of the UI. This section covers the commands that most directly affect company work: -…

Adapters

Connect any agent runtime — Claude, Codex, Gemini, or your own HTTP service.

Overview — Adapters connect Paperclip's control plane to the runtime that actually does the work. Use this section when you need to choose an adapter, understand what Paperclip expects from one, or build a new…
Claude Local — claudelocal runs Anthropic's Claude Code CLI on the same machine as Paperclip. Use it when you want a local coding agent with session persistence, skills injection, and full access to the configured…
Codex Local — codexlocal runs OpenAI's Codex CLI on the same machine as Paperclip. Use it when you want a local coding agent with persistent session state, managed CODEXHOME, and Paperclip skills injected into the…
Gemini Local — geminilocal runs Google's Gemini CLI on the same machine as Paperclip. Use it when you want a local agent with session resume, configurable sandboxing, and Paperclip skills injected into Gemini's ski…
Cursor Local — cursor runs Cursor's Agent CLI on the same machine as Paperclip. Use it when you want Cursor chat session resume across heartbeats and structured stream output in run logs. --- - You already use Curs…
OpenCode Local — opencodelocal runs OpenCode on the same machine as Paperclip. Use it when you want provider/model routing in OpenCode's provider/model format and session resume across heartbeats. --- - You already u…
Pi Local — pilocal runs the Pi coding agent CLI on the same machine as Paperclip. Use it when you want Pi's built-in tool set (read, bash, edit, write, grep, find, ls), provider/model routing, and session resum…
Hermes Local — hermeslocal runs Hermes Agent — a full-featured AI agent by Nous Research — on the same machine as Paperclip. Use it when you want persistent memory, a 30+ tool suite, 80+ loadable skills, multi-prov…
OpenClaw Gateway — openclawgateway connects Paperclip to an OpenClaw instance over the OpenClaw Gateway WebSocket protocol. Use it when OpenClaw is running on another machine, inside Docker, or behind a shared gateway…
Process — The process adapter runs an arbitrary command on the same machine as Paperclip. Use it when your agent is just a script, a shell command, or a custom runtime that already knows how to do its own work…
HTTP — The http adapter sends a JSON webhook request to a service you control. Use it when the runtime is remote, long-lived, or already exposed as an API instead of a local command. Info: http is a built-i…
External Adapters — External adapters let you ship a Paperclip adapter as its own npm package or local directory. Use them when you want independent versioning, separate distribution, or a runtime that should not live i…
Creating an Adapter — Build a custom adapter when the built-in local adapters do not fit your runtime. This page covers the code shape and runtime contracts; if you are packaging an installable plugin, read External Adapt…
UI Parser Contract — Paperclip streams adapter stdout to the run viewer in real time. If your adapter emits structured lines, ship a UI parser so the viewer can render tool calls, tool results, thinking blocks, and syste…

Deployment

Run Paperclip on your laptop, in Docker, or on a server — with secrets and Tailscale.

Overview — Paperclip supports three deployment configurations, from zero-friction local use to login-protected private and public deployments. Use this section when you need to choose a mode, understand the sto…
Deployment Modes — Paperclip has two runtime modes and one exposure choice. The mode determines how the board operator authenticates; the exposure choice determines whether the instance stays private or is reachable pu…
Local Development — This is the fastest way to run Paperclip locally. The default path uses embedded PostgreSQL, local disk storage, and the local trusted deployment mode. Use this page if you want to get the app runnin…
Docker — Use Docker when you want a self-contained Paperclip instance without installing Node or pnpm on the host machine. This page covers the quickstart image, the manual image build, and what persists betw…
Database — Paperclip uses PostgreSQL through Drizzle ORM. The same schema works across the supported database modes; the difference is where PostgreSQL is running and how Paperclip connects to it. Use this page…
Storage — Paperclip stores uploads such as attachments, screenshots, and other assets through a configurable storage provider. Use this page when you need to understand where files live locally or when you are…
Secrets — Secrets Secrets keep sensitive values out of adapter configs while still making them available to agents at runtime. Use this page when you need to understand the default secret provider, configure s…
Environment Variables — Environment Variables This page lists the environment variables Paperclip reads for server configuration and the variables it injects into agent processes at runtime. Use it when you are wiring a dep…
Tailscale Private Access — Use this page when you want a Paperclip instance that is reachable from a private network, not just from localhost. It is the practical path for authenticated + private deployments. --- Start Papercl…