mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 21:34:48 +01:00
## 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>
307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
# 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/<server-pid>/exe`; an
|
|
interactive shell version check alone is insufficient. Use the guarded restart
|
|
procedure in [hot-restart-deploys.md](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:
|
|
|
|
```text
|
|
~/.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:
|
|
|
|
```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 <commit-sha>
|
|
```
|
|
|
|
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.
|