How to install Paperclip on Windows: use the official paperclipai Node.js CLI, not pip install paperclip. The earlier version of this guide mixed unrelated Python commands into the installation instructions. The corrected route below follows the Paperclip project’s documentation and keeps the first instance local.
Quick answer
With Node.js 24.11 or newer installed, the official repository documents npx --registry https://registry.npmjs.org paperclipai onboard --yes for a local tryout. The UI and API use http://localhost:3100. On Windows, consider WSL2 for Linux-based agents; native Windows adapter compatibility must be checked separately.
What to know first
Paperclip organizes work across agents, goals, budgets and approvals. It is not a Python model loader, a drag-and-drop workflow builder, or a promise that all AI work runs offline. The control plane and an agent’s model/provider are different parts of the setup.
Self-hosted open-source software can still use paid model APIs, subscriptions and hosting. You do not need to buy an Anthropic key merely to open the dashboard; requirements depend on the agent adapter you select. Check those costs before scheduling repeated runs.
This update is a documentation review, not a new Windows installation test. The official installation reference describes its shell installer for macOS, Linux and WSL2. This guide does not claim that every native Windows agent adapter works.
1. Choose your Windows environment
If you plan to use Linux command-line agents, use Ubuntu under WSL2 and install the tools inside Ubuntu. Keep Paperclip and its local agent runtime in the same environment when practical; mixed Windows/WSL paths add avoidable troubleshooting.
Microsoft explains how to install WSL. If it is not already installed, its documented PowerShell command is:
wsl --installFollow Microsoft’s restart and Linux-user setup instructions. An employer-managed PC may require administrator approval. Once Ubuntu is ready, use its normal, non-root shell for the remaining WSL commands. A native Windows tryout uses the same npm CLI route, but validate the required adapter against the project’s current issues before relying on it.
2. Check Node.js and npm
Use Node.js’s official download guidance for your chosen environment. Verify the versions in the shell that will actually launch Paperclip:
node --version
npm --version
npx --versionThe current project requires Node.js 24.11 or newer. Installing Node on Windows does not necessarily install a Linux Node runtime in WSL. Do not substitute an older runtime simply because node is available.
3. Run the official local onboarding command
Run this as your ordinary user, not from an administrator or root shell:
npx --registry https://registry.npmjs.org paperclipai onboard --yesThe explicit registry avoids resolving the package against a private corporate npm registry. On a managed machine, follow company package-source policy instead of overriding it without approval. The command downloads and executes a package; confirm the official package name before accepting npm’s prompt.
The --yes flag accepts onboarding defaults. For a custom setup, omit it and review the prompts. Default first-run configuration is local loopback mode; do not change the bind mode or open port 3100 to the internet just to make the dashboard reachable.
4. Open the dashboard and confirm startup
Use the address printed in the terminal, normally http://localhost:3100. The standard local setup creates an embedded PostgreSQL database, so a separate PostgreSQL installation is not normally required for this first run.
Success means the server remains running and the dashboard loads without a startup error. It does not yet prove that an agent can work. If the browser cannot connect, check the terminal first; do not immediately reinstall or delete the database directory.
5. Configure one agent and one small task
Create the company, define one clear goal, then choose an agent adapter. Follow that adapter’s authentication and runtime requirements. Give it a disposable working folder, a small budget where supported and a task such as writing a short local notes file.
Check the run log, actual output and approval behavior before enabling repeated work. A running dashboard and a configured agent are separate milestones. Do not begin with production credentials, customer records, automatic publishing or permissions to modify important repositories.
For the broader context, see Techmixer’s Paperclip AI overview and agent orchestration guide.
6. Restart and diagnose without losing data
For the npm tryout route, the project documents:
npx --registry https://registry.npmjs.org paperclipai runIts CLI also provides diagnostics:
npx --registry https://registry.npmjs.org paperclipai doctorRead the specific reported error. Keep a copy of useful logs with credentials removed. Paperclip configuration, database and uploads are not disposable install files; consult the backup and recovery guides before a reset or migration.
Common problems and safer next steps
- Package not found: verify
paperclipai, inspectnpm config get registry, and check the official quickstart. The Python package name is not this project’s installation route. - Embedded database startup fails: confirm you are not running as root or administrator. Preserve existing data and use the diagnostic output rather than deleting its directory.
- Dashboard works but the agent fails: check adapter authentication, executable path, working directory and environment. Native Windows and WSL binaries are not interchangeable.
- Shell script or spawn errors on Windows: search the project issue tracker for the adapter and version. Do not bypass security controls or build an unreviewed wrapper as a universal fix.
- You need remote access: consult the official deployment modes. Remote exposure, authentication and HTTPS are a separate deployment task.
FAQ
Should I run pip install paperclip?
No, not to install the Paperclip agent-management project linked here. Its official route uses the Node.js package and CLI named paperclipai.
Can I use Paperclip on Windows without WSL?
A native Windows Node.js tryout is possible, but individual agent adapters may have Windows-specific failures. The project’s shell-install guidance includes WSL2. Choose the environment that matches your agent runtimes and verify one complete task before relying on it.
Is all AI usage free after installation?
No. Self-hosting the control plane does not make model APIs, provider subscriptions or hosting free. Costs depend on the adapters and services you connect.
Related Techmixer guides
Our take
The first useful result is not a dashboard screenshot: it is one controlled agent task that finishes correctly. Start local, verify that task, and expand only after reviewing permissions, costs and failure behavior.
Last reviewed: 3 October 2026 against the official repository, installation and CLI references. The commands were documentation-checked, not newly executed on a clean Windows installation.
That is a great tip especially to those new to the blogosphere.
Simple but very accurate information… Thank you for sharing this one.
A must read article!
I am extremely impressed with your writing skills and also with the layout on your weblog.
Is this a paid theme or did you customize it yourself? Anyway keep up the excellent quality writing,
it is rare to see a great blog like this one today.