Files
PaperClipAI/doc/INSTALLING.md
T
DottaandClaude Fable 5.2 ac114d9479 refactor: cut DEVELOPING.md to a setup and workflow guide (#21670)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `AGENTS.md` tells every contributor and agent to read
`doc/DEVELOPING.md` for setup, commands, testing, and worktrees
> - That file grew to 5,495 lines. Most of it was notes on how one
subsystem behaves, added one pull request at a time
> - Readers could not find the commands. Agents also read behavior notes
as rules
> - This pull request cuts `doc/DEVELOPING.md` to a 660-line setup and
workflow guide. It moves the subsystem notes to focused docs
> - The benefit is a guide that a person or an agent can read in full,
and a clear place for each kind of note

## Linked Issues or Issue Description

**Issue type**

Outdated or confusing documentation.

**Where is the issue?**

`doc/DEVELOPING.md`

**What's wrong?**

The file was 5,495 lines. It opened with 112 lines about case handoffs
before it reached Prerequisites. Unrelated sections sat below the
"OpenClaw Docker UI One-Command Script" heading. Statements about
current behavior read like policy.

**Suggested fix**

Keep setup, commands, and workflow in `doc/DEVELOPING.md`. Move each
subsystem note to a doc for that subsystem. Add an index.

## What Changed

- `doc/DEVELOPING.md` is now 660 lines: prerequisites, start dev, health
checks, local run, test drive, Docker, instance layout, database,
storage, secrets, worktrees, test commands, Storybook, CLI, and an index
of the other docs.
- 15 new docs hold the moved text without wording changes:
`ci-workflows`, `test-infrastructure`, `worktrees`,
`hot-restart-deploys`, `heartbeat-internals`, `runner-internals`,
`workspace-repositories`, `workspace-storage`,
`skills-and-teams-catalog`, `ui-internals`, `case-handoffs`,
`chat-connector-development`, `instance-configuration`,
`integration-api-notes`, `database-backups`.
- "Publish a branch Storybook" moved to `doc/STORYBOOK-DEPLOYMENT.md`.
The privacy rollout notes moved to `doc/ISSUE-PRIVACY.md`.
- Deleted about 280 lines: the story-by-story Storybook notes, "Agent
Artifact Uploads" (a copy of `doc/AGENT-ARTIFACTS.md`), two pointer-only
sections, "Workspace feature checks (2026-10-09)", and "Chat and task
navigation caching". The test-drive build-lock paragraph is now four
lines.
- Repointed every inbound link and every script or workflow comment that
named a moved section.
- `AGENTS.md` now says where a behavior note goes, so the guide does not
grow again.

## Verification

- A script split the file by line range. It asserts that each of the
5,495 source lines is kept, moved, or dropped exactly one time.
- A link check on every changed Markdown file found 0 missing files and
0 missing anchors.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail.
- `node --check` passes on the three scripts with changed comments.
- `pnpm verify` was not run. This worktree has no installed
dependencies, and the change has no runtime code.

## Risks

- Low risk. The change is documentation and comments only.
- A link to a moved section from outside this repository will land on
the top of `doc/DEVELOPING.md`.
- The new docs are not in the audited prose list in
`.github/scripts/ci-inputs.mjs`. An edit to one of them runs full CI. An
edit to `doc/DEVELOPING.md` does not. This PR does not change that list.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool
use.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 18:02:27 -06:00

11 KiB

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.

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 hot-restart-deploys.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.