paperclipai/paperclip installation guide

Install Paperclip on macOS Tahoe (Apple silicon)

What you are installing

Paperclip is a self-hosted Node.js server with a React web interface for coordinating teams of AI agents. It provides tasks, projects, goals, org charts, budgets, approval gates, schedules, audit history, skills, connections, and agent run management. Its local setup uses an embedded PostgreSQL database, so the documented quickstart does not require you to install or configure PostgreSQL separately.

How Paperclip relates to Claude Code

**Classification: standalone application with orchestration, context-injection, and tool-surface mechanisms. Install mode: standalone. Setup effort: medium.**

Paperclip is not a Claude Code plugin and does not replace Claude Code. It runs as its own control plane and can use Claude Code as one of several agent harnesses. The repository says Paperclip invokes adapters, supplies agents with task and goal context, loads skills at runtime, resumes supported sessions, and can expose Paperclip operations through an MCP server. It can also coordinate Codex, Cursor, Gemini CLI, OpenCode, Pi, Hermes, and custom processes or HTTP adapters.

This means installing Paperclip alone does not establish that Claude Code is installed, authenticated, or connected. The supplied files do not contain a complete, Claude-specific setup sequence, so this guide does not invent one. Use Paperclip’s onboarding screens and its linked first-party documentation when you are ready to add a Claude Code agent.

Before you begin

You need:

• An Apple-silicon Mac running macOS Tahoe.
• An internet connection for npm to retrieve the Paperclip CLI.
• **Node.js 24.11 or newer** already installed.
• A normal macOS user account that can run Terminal commands.

The repository does not provide a source-supported Terminal command for installing Node.js on macOS. Obtain Node.js from a first-party Node.js distribution method, then return here. Do not continue with an older Node version.

There is no first-party compatibility statement specifically naming macOS Tahoe in the supplied files. The documented local architecture is a Node.js process with embedded PostgreSQL, and repository evidence mentions macOS use, but Tahoe-specific validation is not established. If you encounter a platform problem, use the project’s GitHub Issues or Discord links.

Choose the right installation mode

For a first installation on one Mac, use the documented `npx` onboarding command. It runs the CLI from npm’s cache while keeping Paperclip’s configuration and data locally. This avoids cloning the development repository or installing its workspace dependencies.

The default quickstart uses **trusted local loopback mode**. That is the appropriate starting point when only you will use Paperclip on this Mac. Do not expose that mode to your local network or the internet. Paperclip also documents authenticated `lan` and `tailnet` bind presets, but those are separate choices covered later.

Install with the recommended quickstart

1. Open **Terminal** on your Mac.
2. Paste the following documented command and press Return:

npx paperclipai@latest onboard --yes

1. Leave Terminal open while npm retrieves the CLI and onboarding completes.
2. Follow any status information or directions printed by the CLI.

The quickstart is self-hosted and does not require a Paperclip account. Rerunning onboarding later preserves an existing configuration rather than replacing it. Paperclip’s instance configuration and data persist locally even though the CLI itself runs from npm’s cache.

The supplied files do not document every interactive screen or the exact filesystem location of the persistent data, so this guide does not guess. Do not delete directories reported by Paperclip unless you have consulted its first-party uninstall or backup documentation.

Complete initial setup

After onboarding, use the Paperclip interface and guided setup to create or configure your organization, goals, projects, and first agent. A typical Paperclip deployment has agents assigned to tasks, with runs and costs visible from the dashboard.

When adding Claude Code, remember the division of responsibility:

• Paperclip stores and coordinates work.
• Claude Code is an agent harness Paperclip can invoke.
• Model access and authentication belong to the selected harness or provider.
• Agent permissions, budgets, workspaces, connections, and approval rules should be reviewed before autonomous execution.

The repository supports local and isolated workspaces, secrets, skills, connections, MCP servers, and plugin-provided tools. These can increase what an agent can read or change. Begin with one agent and a low-risk project, inspect its proposed work, and configure budget and approval limits before enabling unattended routines.

Privacy and telemetry

Anonymous usage telemetry is enabled by default. The project states that it does not collect personal information, issue content, prompts, file paths, or secrets, and that private repository references are salted and hashed. It documents three ways to disable telemetry: set `PAPERCLIP_TELEMETRY_DISABLED=1`, use the standard `DO_NOT_TRACK=1` convention, or set `telemetry.enabled: false` in the Paperclip configuration. Because the supplied files do not document the exact macOS persistence procedure for those environment variables, use the configuration interface or the first-party installation documentation rather than adding an undocumented shell configuration command.

Optional OpenTelemetry tracing and Sentry error monitoring remain inactive unless their documented environment variables and optional dependencies are configured.

Change settings later

If Paperclip is already configured and you want to edit its settings, use the documented command:

npx paperclipai configure

Rerunning the onboarding command keeps the existing configuration in place, but `configure` is the repository’s stated command for editing settings.

Optional authenticated bind modes

The default loopback setup is intended for the fastest local first run. If you intentionally need authenticated/private access beyond this Mac, Paperclip documents two explicit onboarding alternatives.

For a LAN bind preset:

npx paperclipai@latest onboard --yes --bind lan

For a tailnet bind preset:

npx paperclipai@latest onboard --yes --bind tailnet

Choose only one onboarding mode. Do not run these merely to test whether they work: changing the bind scope changes how the service can be reached. The README recommends authenticated mode with a private-network bind such as Tailscale for remote access and refers production users to separate deployment documentation.

Troubleshoot an npm `E404`

If installation fails with an `E404` mentioning `paperclipai`, a global `~/.npmrc` may be directing npm to a private registry such as GitHub Packages. First run the repository’s documented diagnostic:

npm config get registry

If it reports a private registry, retry onboarding while forcing the public npm registry for this command:

npx --registry https://registry.npmjs.org paperclipai@latest onboard --yes

This workaround affects that invocation rather than documenting a permanent change to your npm configuration.

Optional source-development installation

Most users should skip this section. Use it only if you want a development checkout rather than the managed `npx` installation.

The source path requires **Node.js 24.11 or newer** and **pnpm 9.15 or newer**. Source development also builds the native Paperclip Runner when enabled, which is the self-hosted default. The repository says this requires a Rust toolchain unless `PAPERCLIP_RUNNER_BINARY` points to a compatible prebuilt runner. No source-supported macOS commands for installing pnpm or Rust were supplied, so install those prerequisites through their first-party instructions before continuing.

Run the documented sequence:

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

This starts the UI and API at `http://localhost:3100` and creates an embedded PostgreSQL database automatically. Keep the Terminal process running while using this development instance. This path is intended for source work and uses the repository checkout; it is not necessary for ordinary local use.

Security notes and next steps

Paperclip can launch agents that edit files, call external services, use credentials, and run on schedules. Review every agent’s workspace, connections, permissions, model account, and budget. Its plugin system should also be treated cautiously: the first-party SDK says plugin workers and same-origin plugin UI are trusted code today, not a sandbox for untrusted marketplace code.

For normal use, continue with Paperclip’s first-party guided quickstart and adapter documentation. For remote or production deployment, consult its documented deployment modes and Docker guide rather than exposing the trusted local installation directly.