PaperClipAI/docs/deploy/local-development.md at 14da75dfc7769c8135a31b1fd40efe77cecf0b4a

0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-06 21:05:21 +02:00

Files

T

Granis87andRobinALG87 bbb3e19c6f docs: add safe local worktree bootstrap guidance (#9195 )

## Thinking Path

> - Parallel local agent experiments should not reuse the primary
Paperclip instance.
> - Paperclip already creates isolated worktree instances with generated
names and environment files.
> - The local development guide lacked a complete bootstrap and recovery
path.
> - This pull request adds that path using the registered CLI forms and
generated selector.
> - The benefit is safer setup, recovery, and cleanup for local
experiments.

## Linked Issues or Issue Description

No public issue was found. The local development guide did not connect
worktree creation, environment loading, startup, repair/reseed, and
cleanup into one safe sequence.

## What Changed

- Added an isolated worktree bootstrap example.
- Documented bash/zsh environment loading without presenting invalid
PowerShell syntax.
- Used registered repair/reseed commands and the generated
paperclip-local-lab selector.
- Added explicit cleanup guidance.

## Verification

- git diff --check upstream/master...HEAD
- Verified command registration and generated naming in
cli/src/commands/worktree.ts.

## Risks

Low. Documentation-only; reviewed command and selector mismatches are
corrected.

## Model Used

OpenAI GPT-5.3 Codex Spark for initial branch work; OpenAI GPT-5 Codex
for review and follow-up fixes, with repository and GitHub tool use.
Context-window sizes were not exposed in this session.

## 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 docs PR does not
duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked or
described the problem above
- [x] I have either linked an existing issue or described the issue
in-PR
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run focused validation locally
- [x] I have added or updated tests where applicable
(documentation-only; no runtime tests needed)
- [x] I have updated the relevant documentation
- [x] I have considered and documented risks above
- [x] All Paperclip CI gates are green on the latest commit
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
on the latest commit
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: RobinALG87 <RobinALG87@users.noreply.github.com>

2026-07-15 15:51:53 -05: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 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