Paperclip is the company layer, and its example secrets ship with a change-me string

A heartbeat is the whole integration contract, and it excludes interactive agents

The onboarding rule is stated as a single sentence: if it can receive a heartbeat, it is hired. The README's list includes OpenClaw, Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi, Hermes, Grok Build and Kimi Code, and custom processes, HTTP endpoints and external adapter packages extend it. The heartbeat contract, not the vendor name, is what decides whether an agent can be hired.

Agents wake on a schedule, check their work and act, and delegation flows up and down the org chart. Paperclip is therefore a scheduler and a queue, not a remote control. An agent that can only be driven by a person typing at it has no way to satisfy the contract, which is the single most important thing to know before choosing this tool.

The upside of that narrow contract is that it composes. Custom processes and HTTP endpoints are in the roster alongside the named coding agents, so anything that can poll and post is a candidate employee, and the same org chart holds all of them.

Budgets are a hard stop, so an agent can be killed mid-task

Cost control is described in one line: monthly budgets per agent, and when they hit the limit, they stop. The stated benefit is no runaway costs, and it delivers that.

It is worth being precise about what a budget is here, because it is a kill switch and not a throttle. The agent stops.

The consequence is that budgets are a scheduling tool as much as a cost tool. An agent doing work that spans a month boundary needs a budget that spans it, and an agent doing unpredictable work needs headroom, or you are going to spend your time restarting interrupted runs. The rest of the governance surface is more forgiving by comparison, since you can approve hires, override strategy, and pause or terminate any agent at any time.

The example .env ships two secrets that are printed in the repository

Copying `.env.example` to `.env` and starting the server gives you a working development instance. It also gives you two publicly known secrets, because the file is committed:

DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
PORT=3100
SERVE_UI=false
BETTER_AUTH_SECRET=paperclip-dev-secret
PAPERCLIP_TOOL_ACTION_SIGNING_SECRET=paperclip-dev-tool-action-signing-secret-change-me

The tool-action signing secret is the one to look at. Its default value contains the words change-me, so the file is telling you what to do, but the failure mode if you skip it is not a warning. Anyone who has read this repository holds the key that signs tool actions, which is the difference between an audit log that proves what happened and one that anyone can append to. `BETTER_AUTH_SECRET` has the same problem with less labelling.

The rest of the file shows how much is left to you in production. The optional Paperclip ID Gmail OAuth broker wants two private keys kept in a deployment secret manager and insists HTTP base URLs be loopback. The HTTP adapter allowlist is described as opt-in with exact origins including scheme, host and port. None of that is configured by default, so the defaults are a local laptop and nothing else.

Postgres is a hard dependency, and the default connection string is a laptop

Paperclip is not a single binary you copy onto a machine. The configuration expects a database at the `DATABASE_URL` given above, a Postgres instance on the local machine for development, and the server listens on port 3100 with `SERVE_UI=false` meaning the UI is served separately in that arrangement. The repository layout matches: a `server/` package, a `packages/db/` package, a pnpm workspace, and a `pnpm-workspace.yaml` at the root.

There is no embedded or file-backed mode mentioned anywhere in the configuration, so a deployment is at minimum a Node service and a Postgres database, which is a different operational commitment from installing a desktop application. The Docker image is built for that shape rather than around it, on `node:24-trixie-slim` with pnpm enabled through corepack and a set of package manifests copied in for the server, the UI and more than a dozen workspace packages including the per-agent adapters for Claude, Codex, Cursor and Gemini.

For a small team the honest question is whether you want to operate a database. If the answer is no, the features you are actually after, which are budgets and an org chart, are things a directory of files and a cron entry can do, and Paperclip's own four-pillar framing is a much larger system than that.

The image bakes your host UID into the container so volumes come out writable

One detail in the Dockerfile explains a class of otherwise baffling permission problems. The build takes the UID and GID as arguments and rewrites the existing `node` user to match the host:

ARG USER_UID=1000
ARG USER_GID=1000
RUN usermod -u $USER_UID --non-unique node \
  && groupmod -g $USER_GID --non-unique node \
  && usermod -g $USER_GID -d /paperclip node

The reason is volume ownership. An agent that writes into a mounted workspace, which is the normal case when agents are editing code, will create files owned by the container user, and if that user does not match you on the host the files are unreadable or unremovable afterwards. Remapping the UID fixes that at the cost of making the image host-specific.

So passing `USER_UID` and `USER_GID` at build time is close to mandatory, and the defaults of 1000 and 1000 are only correct if your host user is 1000. On a machine where that UID belongs to somebody else, the `--non-unique` flag is what keeps the build from failing, and you should expect to pass real values. The image also installs `gosu` and `tini`, which are the tools for dropping privileges and reaping the child processes an agent runner leaves behind.

Versions are date-stamped, so a version number tells you when, not what

The release tags are v2026.1023.0, v2026.1012.0 and v2026.1005.0. Those are dates rather than semantic versions, which has real consequences for anyone automating a deployment.

A date-stamped version sorts chronologically, which is useful, but it carries no information about compatibility. With semver you can see from the number that a minor bump might change behaviour and a patch will not; here every release looks like a feature release, and the only way to learn what changed is to read the release. The project keeps a `releases/` directory and a `ROADMAP.md` at the top level, so the information exists, it is just not encoded in the tag.

The second consequence is tooling. Dependency resolvers, image tags and dashboards that assume semver will treat these as unusual but usually workable, while anything that infers a breaking change from a major version number will read 2026 as a major and stop trusting its own rules. Releases v2026.1005.0 on 2026-10-06, v2026.1012.0 on 2026-10-12 and v2026.1023.0 on 2026-10-24 arrived over about three weeks, and the last push to the repository was on 2026-11-02, so the cadence is active.

Editorial conclusion

Paperclip fits a team already running several coding agents at once that has lost track of which terminal is doing what, and it gives that team budgets, reporting lines and an audit trail rather than a shared notepad. It does not fit a single-agent setup, and it is not something to expose before you replace its secrets, because the example configuration publishes both an auth secret and a tool-action signing secret that anyone can read in the repository. Before you run it anywhere shared, set `BETTER_AUTH_SECRET` and `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET` to values of your own and put Postgres behind it, because the default `DATABASE_URL` is a local development instance with the username and password both set to `paperclip`.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes