PaperClipAI/docs/deploy/local-development.md at 5ca7b4c1fefbf9afd5d4e1018c3ac728fc29a0ac

0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-06 20:34:57 +02:00

Files

T

Nicky LeachandPaperclip 5ca7b4c1fe fix(security): standardize paperclipai CLI guidance on safe npx path (#11343 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip provides CLI guidance to agents and operators through
documentation and runtime messages.
> - Content-bearing `pnpm paperclipai` examples send arguments through a
shell.
> - Shell evaluation can execute command substitutions in untrusted
argument content.
> - Runtime hostname guidance can also place request-derived content
inside a shell command.
> - This pull request uses `npx paperclipai` for content-bearing
guidance and uses a static hostname placeholder.
> - The benefit is safer copy-paste guidance for agents and operators.

## Linked Issues or Issue Description

**Issue type**
Incorrect information

**Where is the issue?**
CLI guidance in `doc/CLI.md`, `skills/paperclip/SKILL.md`,
documentation, and runtime-generated hints.

**What's wrong?**
Content-bearing `pnpm paperclipai` commands can pass argument text
through `/bin/sh`. Shell command substitution in an argument can execute
before the CLI receives the value.

**Suggested fix**
Use `npx paperclipai` for content-bearing commands. Use a static
`<host>` placeholder when runtime guidance displays the allowed-hostname
command.

## What Changed

- Replace content-bearing `pnpm paperclipai` examples with `npx
paperclipai` across the documentation and agent-facing guidance.
- Update runtime-generated CLI hints to use a static `<host>`
placeholder.
- Add safety notes to `doc/CLI.md` and `skills/paperclip/SKILL.md`.
- Add scans and regression tests for unsafe invocation and hostile
hostname headers.
- Keep fixed lifecycle commands and `pnpm --filter @paperclipai/*` build
commands unchanged.

## Verification

- Run `tsc --noEmit` for the changed server files.
- Run `cli-invocation-safety.test.ts`.
- Run `private-hostname-guard.test.ts`.
- Confirm that hostile hostname headers do not enter shown shell
commands.
- Confirm that the three commits contain the required Paperclip
co-author trailer.

## Risks

- This change updates documentation and diagnostic text across many
surfaces.
- Fixed lifecycle and setup commands remain unchanged.
- The tests fail if content-bearing `pnpm paperclipai` guidance returns.
- The change does not alter the CLI argument parser.

## Model Used

OpenAI Codex, GPT-5, tool use, code execution, and repository review
assistance.

## 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
- [x] 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-08-13 16:43:21 -07:00

2.8 KiB

Raw Blame History

title, summary

title	summary
Local Development	Set up Paperclip for local development

Run Paperclip locally with zero external dependencies.

Prerequisites

Node.js 20+
pnpm 9+

Start Dev Server

pnpm install
pnpm dev

This starts:

API server at http://localhost:3100
UI served by the API server in dev middleware mode (same origin)

No Docker or external database required. Paperclip uses embedded PostgreSQL automatically.

One-Command Bootstrap

For a first-time install:

pnpm paperclipai run

This does:

Auto-onboards if config is missing
Runs paperclipai doctor with repair enabled
Starts the server when checks pass

Bind Presets In Dev

Default pnpm dev stays in local_trusted with loopback-only binding.

To open Paperclip to a private network with login enabled:

pnpm dev --bind lan

For Tailscale-only binding on a detected tailnet address:

pnpm dev --bind tailnet

Legacy aliases still work and map to the older broad private-network behavior:

pnpm dev --tailscale-auth
pnpm dev --authenticated-private

Allow additional private hostnames:

pnpm exec paperclipai allowed-hostname dotta-macbook-pro

For full setup and troubleshooting, see Tailscale Private Access.

Health Checks

curl http://localhost:3100/api/health
# -> {"status":"ok"}

curl http://localhost:3100/api/companies
# -> []

Safe Worktree Bootstrap for Local Agent Runs

For safer parallel local experiments, initialize a dedicated worktree instance instead of reusing your main checkout:

pnpm paperclipai worktree:make local-lab --seed-mode minimal
cd ~/paperclip-local-lab
pnpm paperclipai worktree env                       # inspect generated env exports
eval "$(pnpm paperclipai worktree env)"             # bash/zsh
pnpm paperclipai run
pnpm paperclipai doctor

If the experiment gets noisy, repair or reseed the worktree without touching the main branch:

pnpm paperclipai worktree repair --branch paperclip-local-lab
pnpm paperclipai worktree reseed --from . --to paperclip-local-lab

When done, shut it down and remove the isolated state explicitly:

pnpm paperclipai worktree:cleanup local-lab --force

Reset Dev Data

To wipe local data and start fresh:

rm -rf ~/.paperclip/instances/default/db
pnpm dev

Data Locations

Data	Path
Config	`~/.paperclip/instances/default/config.json`
Database	`~/.paperclip/instances/default/db`
Storage	`~/.paperclip/instances/default/data/storage`
Secrets key	`~/.paperclip/instances/default/secrets/master.key`
Logs	`~/.paperclip/instances/default/logs`

Override with environment variables:

PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run

2.8 KiB Raw Blame History