# Installing Paperclip Paperclip supports a managed installation, an ephemeral `npx` tryout, a traditional global npm installation, and development from a source checkout. The managed installation is recommended because it provides atomic updates, rollback, git-ref installs, and a stable entrypoint for the background service. ## Recommended Install On macOS, Linux, or WSL2: ```sh curl -fsSLO https://paperclip.ing/install.sh curl -fsSLO https://paperclip.ing/install.sh.sha256 if command -v sha256sum >/dev/null 2>&1; then sha256sum -c install.sh.sha256 else shasum -a 256 -c install.sh.sha256 fi bash install.sh ``` The bootstrap script: 1. verifies that the platform is supported; 2. ensures Node.js 24.11 or newer is available; 3. delegates installation to `paperclipai install`; 4. starts interactive onboarding when stdin and stdout are terminals. The script prints and confirms any command that requires elevated privileges. Third-party Node.js bootstrap scripts are pinned and SHA-256 verified before execution; the installer stops if a published script changes unexpectedly. The `paperclip.ing` checksum detects transfer or publishing mistakes, but it is served from the same origin as the script and is not an independent authenticity proof. For an independently hosted source, download a release-tag or commit-pinned copy from GitHub, review it, and run that local file. Use `--no-prompt` for automation and `--no-onboard` to stop after installing. The piped form only proceeds when supported Node.js, npm, and npx are already installed; if Node.js bootstrap is required, download the script first so the privileged commands are inspectable before execution: ```sh curl -fsSL https://paperclip.ing/install.sh | bash -s -- --no-prompt --no-onboard paperclipai onboard --yes ``` If the vanity installer endpoint is unavailable, fetch the same release-controlled source from GitHub raw content: ```sh raw_base=https://raw.githubusercontent.com/paperclipai/paperclip curl -fsSL "$raw_base/master/scripts/install.sh" | bash ``` For audits or incident response, pin the raw URL to a release tag or commit SHA instead of `master` and download it first. That immutable GitHub URL provides a separate delivery path from `paperclip.ing`; do not treat a checksum served by the same origin as the artifact as an independent trust anchor. Each installer flag also has a `PAPERCLIP_INSTALL_*` environment-variable equivalent. This helps where passing arguments through a pipe is awkward. Codex ACP workspace sessions enable networking so agents can report task outcomes. To disable it explicitly, set `extraArgs` to `["-c", "sandbox_workspace_write.network_access=false"]`, or set `env.PAPERCLIP_CODEX_ACP_NETWORK_ACCESS="false"`. Execution-target network denial also remains enforced. Read-only ACP mode remains read-only. ## Node runtime used by background services Check the Node executable used by the running service, not only `node --version` in an interactive shell. Systemd and launchd do not load shell version-manager configuration. A newer Node installed elsewhere does not upgrade a running service or change a custom startup script's `PATH`. Managed installs pin the validated Node executable in the `paperclipai` shim and prepend its directory to `PATH` for child tools, including ACP servers with an `/usr/bin/env node` shebang. Re-run the installer using the supported Node runtime after changing runtime installations, then restart the service. For example, put the supported Node's bin directory first on `PATH` and run `npx paperclipai@latest install --yes`. Do not use the old managed shim to re-pin Node: it intentionally continues launching its previously pinned runtime. Installs and updates refresh existing managed shims in place. Updates reject an unsupported running Node before installing or activating a payload; read-only update checks and rollback remain available for recovery. Global npm installs and source checkout services must configure their own executable and child-process `PATH`. For custom service wrappers, use an absolute, supported Node executable and put that executable's directory first on `PATH`. Keep required existing PATH entries. On Linux, verify the running executable with `/proc//exe`; an interactive shell version check alone is insufficient. Use the guarded restart procedure in [DEVELOPING.md](DEVELOPING.md#hot-restart-deploys) when jobs are active. Legacy local adapters default to ACP, including configurations with no `engine` field or the old `auto` value. An unavailable ACP runtime fails the run and the agent environment test with a setup error; it never silently changes engines. Repair the reported prerequisite or explicitly select `engine: cli`. Local filesystem/network confinement and in-place Codex workspaces require explicit CLI selection. CLI sandbox defaults and explicit restrictions are described in the adapter configuration documentation. ## Managed Install Layout Managed code is separate from instance data: ```text ~/.paperclip/cli/ ├── install.json ├── current -> installs/npm/2026.720.0 └── installs/ ├── npm// └── git// ~/.local/bin/paperclipai ``` The `paperclipai` shim remains stable while `current` switches atomically between complete payloads. Paperclip keeps the two previous managed payloads for rollback. Configuration, databases, uploads, logs, secrets, and workspaces remain under `~/.paperclip/instances/` and are not stored inside CLI payloads. If `~/.local/bin` is not on `PATH`, the installer offers to update the relevant shell startup file when running interactively. Non-interactive installs print the exact `export PATH` command instead of editing shell files silently. ## Install Sources Install the current stable release: ```sh npx --registry https://registry.npmjs.org paperclipai install ``` Install canary or pin an exact published version: ```sh npx --registry https://registry.npmjs.org paperclipai install --canary npx --registry https://registry.npmjs.org paperclipai install --version 2026.720.0 ``` Install a branch, tag, or commit from GitHub: ```sh npx --registry https://registry.npmjs.org paperclipai install --ref master npx --registry https://registry.npmjs.org paperclipai install --ref v2026.720.0 npx --registry https://registry.npmjs.org paperclipai install --ref ``` Use a fork by adding `--repo owner/repository`: ```sh npx --registry https://registry.npmjs.org paperclipai install \ --repo your-org/paperclip \ --ref your-branch ``` Git-ref installs resolve the requested ref to an exact commit before building. Review and trust the repository and ref: installing a git ref executes that revision's package installation and release build scripts on your machine. ## Onboarding And The Service Run onboarding after a non-interactive installation: ```sh paperclipai onboard ``` Interactive onboarding asks whether Paperclip should run as a background service when the platform supports one. Automated onboarding deliberately does not install a service unless explicitly requested: ```sh paperclipai onboard --yes # configure only; no service install paperclipai onboard --yes --install-service # explicit automation opt-in paperclipai onboard --yes --no-install-service ``` After onboarding installs and starts the service, it waits for the service to report its selected runtime port and then prints the dashboard URL. Interactive terminals open that URL in the default browser; headless and non-interactive runs print the URL without trying to launch a browser. Service commands are namespaced: ```sh paperclipai service install paperclipai service status paperclipai service start paperclipai service stop paperclipai service restart paperclipai service logs -f paperclipai service uninstall ``` Paperclip uses a systemd user service on Linux and WSL2 systems with user systemd, and a LaunchAgent on macOS. Containers, WSL1, and systems without a supported user service manager receive foreground `paperclipai run` guidance instead of a hard failure. The service uses the stable managed-install shim, restarts after crashes, and can start on login. On Linux, service installation may offer to enable user lingering so it can continue without an active login session. The command explains and confirms that system-level action before running it. Use one server process per instance. `paperclipai run` refuses to start when the same instance is already supervised; stop the service first or use `--force` only when you intentionally accept the single-writer risk. ## Update And Rollback Update according to the source and channel recorded in the install manifest: ```sh paperclipai update ``` Select a different release source explicitly: ```sh paperclipai update --latest paperclipai update --canary paperclipai update --version 2026.720.0 ``` Managed updates create a database backup before switching payloads, verify the new CLI, atomically flip `current`, and restart an installed service. A failed install or verification leaves the previous payload active. If the service is stopped, start it with `paperclipai service start` before updating so Paperclip can take the safety backup. Use `paperclipai update --no-backup` only when you intentionally accept updating without that rollback safeguard. A never-onboarded instance with no config or instance data skips the backup automatically because there is nothing to save. Roll back to the previous retained payload: ```sh paperclipai update --rollback ``` The `upgrade` command is an alias for `update`. Exact versions and commit SHAs are pinned; provide a new target when you want them to move. ## Other Installation Methods Ephemeral tryout with no managed install: ```sh npx --registry https://registry.npmjs.org paperclipai onboard --yes ``` Traditional global npm install: ```sh npm install --global --registry https://registry.npmjs.org paperclipai paperclipai onboard ``` Source checkout for development: ```sh git clone https://github.com/paperclipai/paperclip.git cd paperclip pnpm install pnpm dev ``` The managed `paperclipai update` command can update managed and global npm installs. For source checkouts it reports the appropriate git workflow instead of modifying the checkout automatically. ## Diagnose An Installation Run: ```sh paperclipai doctor paperclipai service status ``` `doctor` checks the managed install store, manifest, `current` link, shim, `PATH`, Node.js version, and service state. Service diagnostics cover unit-file presence and drift, running state, configured port ownership, and the running server version. The CLI and server also print a non-blocking startup warning when Node.js is below the supported minimum. Upgrade Node.js with a version manager or follow the downloaded `install.sh` workflow under **Recommended Install**. Do not use the piped form for this repair because it requires a supported Node.js runtime before it starts. ## Uninstall Remove the background service and managed CLI payloads: ```sh paperclipai service uninstall paperclipai uninstall ``` `paperclipai uninstall` removes the managed shim, manifest, and CLI payloads. It deliberately preserves `~/.paperclip/instances/`, including configuration, databases, uploads, logs, secrets, backups, and workspaces. Back up and remove that data separately only when you intend to delete the Paperclip instance.