paperclip/doc/INSTALLING.md

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:

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:

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:

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/<server-pid>/exe; an interactive shell version check alone is insufficient. Use the guarded restart procedure in DEVELOPING.md 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:

~/.paperclip/cli/
├── install.json
├── current -> installs/npm/2026.720.0
└── installs/
    ├── npm/<version>/
    └── git/<sha12>/

~/.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:

npx --registry https://registry.npmjs.org paperclipai install

Install canary or pin an exact published version:

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:

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 <commit-sha>

Use a fork by adding --repo owner/repository:

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:

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:

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:

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:

paperclipai update

Select a different release source explicitly:

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:

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:

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

Traditional global npm install:

npm install --global --registry https://registry.npmjs.org paperclipai
paperclipai onboard

Source checkout for development:

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:

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:

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.