mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 07:23:08 +02:00
Dotta
e3eed3a3ae
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The CLI can save a configuration and start the local server in one command. > - The onboarding path set a browser-open environment variable without an explicit user request. > - Headless test servers use the same onboarding path. > - Each server restart could therefore open a system browser. > - This pull request removes the implicit browser-open request and fixes test servers to disable it explicitly. > - The benefit is predictable foreground and test startup without unsolicited browser windows. ## Linked Issues or Issue Description This is stack 11 of 11. It depends on stack 10. **What happened?** `paperclipai onboard --yes --run` set `PAPERCLIP_OPEN_ON_LISTEN=true`. Headless server users, including browser test runners, opened the system browser on each server restart. **Expected behavior** Server startup must not open a browser unless the caller explicitly sets `PAPERCLIP_OPEN_ON_LISTEN=true`. **Steps to reproduce** 1. Run `paperclipai onboard --yes --run` from a clean source checkout. 2. Wait for the server to listen. 3. Observe that the default system browser opens. **Paperclip version or commit** Reproduced on `dbf052577` plus the dependent stack. **Deployment mode** Local dev from source. ## What Changed - Stop onboarding from setting `PAPERCLIP_OPEN_ON_LISTEN=true` for foreground startup. - Set `PAPERCLIP_OPEN_ON_LISTEN=false` in E2E and issue-detail performance test servers as defense in depth. - Preserve the existing explicit environment opt-in in the server. ## Verification - `pnpm exec vitest run cli/src/__tests__/onboard.test.ts` — 10 tests passed. - `pnpm --filter paperclipai typecheck` — passed. - `pnpm -r typecheck` — passed on the stacked head. - `pnpm build` — passed on the stacked head. - Playwright was not run locally by request. ## Risks - Low risk. The only behavior change removes an unsolicited side effect. - A caller that wants browser startup can still set `PAPERCLIP_OPEN_ON_LISTEN=true` explicitly. - No database or migration change exists in this layer. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5. The exact deployment suffix and context window are not exposed. The model used reasoning, repository tools, code execution, Git, and GitHub API access. ## 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
3.2 KiB
3.2 KiB
title, summary
| title | summary |
|---|---|
| Setup Commands | Onboard, run, doctor, and configure |
Instance setup and diagnostics commands.
paperclipai run
One-command bootstrap and start:
pnpm paperclipai run
Does:
- Auto-onboards if config is missing
- Runs
paperclipai doctorwith repair enabled - Starts the server when checks pass
Choose a specific instance:
npx paperclipai run --instance dev
paperclipai onboard
Interactive first-time setup:
pnpm paperclipai onboard
If Paperclip is already configured, rerunning onboard keeps the existing config in place. Use paperclipai configure to change settings on an existing install.
First prompt:
Quickstart(recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)Advanced setup: full interactive configuration
Start immediately after onboarding:
pnpm paperclipai onboard --run
Non-interactive defaults + immediate start (prints the URL without opening a browser):
pnpm paperclipai onboard --yes
Browser opening is opt-in. Set the environment variable explicitly when that is the desired behavior:
PAPERCLIP_OPEN_ON_LISTEN=true pnpm paperclipai onboard --yes
On an existing install, --yes now preserves the current config and just starts Paperclip with that setup.
paperclipai doctor
Health checks with optional auto-repair:
pnpm paperclipai doctor
pnpm paperclipai doctor --repair
Validates:
- Server configuration
- Database connectivity
- Secrets adapter configuration, including AWS Secrets Manager non-secret env config when selected
- Storage configuration
- Missing key files
paperclipai configure
Update configuration sections:
pnpm paperclipai configure --section server
pnpm paperclipai configure --section secrets
pnpm paperclipai configure --section storage
--section secrets updates the deployment-level provider used as the fallback
for secrets that do not target a specific company vault. Per-company provider
vaults (named instances, default vault selection, multiple vaults per provider,
coming-soon GCP/Vault) live in the board UI under
Company Settings → Secrets → Provider vaults and the
/api/companies/{companyId}/secret-provider-configs API.
paperclipai env
Show resolved environment configuration:
pnpm paperclipai env
This now includes bind-oriented deployment settings such as PAPERCLIP_BIND and PAPERCLIP_BIND_HOST when configured.
paperclipai allowed-hostname
Allow a private hostname for authenticated/private mode:
npx paperclipai allowed-hostname my-tailscale-host
Local Storage Paths
| Data | Default Path |
|---|---|
| Config | ~/.paperclip/instances/default/config.json |
| Database | ~/.paperclip/instances/default/db |
| Logs | ~/.paperclip/instances/default/logs |
| Storage | ~/.paperclip/instances/default/data/storage |
| Secrets key | ~/.paperclip/instances/default/secrets/master.key |
Override with:
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
Or pass --data-dir directly on any command:
npx paperclipai run --data-dir ./tmp/paperclip-dev
npx paperclipai doctor --data-dir ./tmp/paperclip-dev