Instance setup and diagnostics commands. These commands own the host/bootstrap layer:
  • creating or loading a local instance
  • validating the environment
  • preparing storage, secrets, and database configuration
  • allowing trusted private hostnames in authenticated mode
They do not own business data or heartbeat execution policy.

​
paperclipai run

One-command bootstrap and start: 
pnpm paperclipai run
Does:
  1. Auto-onboards if config is missing
  2. Runs paperclipai doctor with repair enabled
  3. Starts the server when checks pass
Choose a specific instance: 
pnpm 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:
  1. Quickstart (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
  2. Advanced setup: full interactive configuration
Start immediately after onboarding: 
pnpm paperclipai onboard --run
Non-interactive defaults + immediate start (opens browser on server listen): 
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
  • Storage configuration
  • Missing key files
Use doctor as the first-line check for host bootstrapping issues. If the runtime cannot start cleanly, fix the setup layer before debugging agents or tasks.

​
paperclipai configure

Update configuration sections: 
pnpm paperclipai configure --section server
pnpm paperclipai configure --section secrets
pnpm paperclipai configure --section storage

​
paperclipai env

Show resolved environment configuration: 
pnpm paperclipai env

​
paperclipai allowed-hostname

Allow a private hostname for authenticated/private mode: 
pnpm paperclipai allowed-hostname my-tailscale-host
This is a host-level trust control. It belongs to setup because it affects whether the instance can safely accept board traffic from a non-local origin.

​
Local Storage Paths

DataDefault 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

​
Host Bootstrap Responsibilities

CommandResponsibility
onboardCreate initial instance config and defaults
doctorValidate and optionally repair the instance prerequisites
configureEdit the persisted configuration sections
envDisplay the resolved environment for the selected instance
allowed-hostnameRegister a private hostname for authenticated mode
runExecute bootstrap checks and start the server
Override with: 
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
Or pass --data-dir directly on any command: 
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev