Skip to content

DEVELOPING.md

Latest commit

 

History

History
220 lines (140 loc) · 5.66 KB

DEVELOPING.md

File metadata and controls

220 lines (140 loc) · 5.66 KB

Developing

This project can run fully in local dev without setting up PostgreSQL manually.

Deployment Modes

For mode definitions and intended CLI behavior, see doc/DEPLOYMENT-MODES.md.

Current implementation status:

  • canonical model: local_trusted and authenticated (with private/public exposure)

Prerequisites

  • Node.js 20+
  • pnpm 9+

Start Dev

From repo root:

pnpm install
pnpm dev

This starts:

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

Tailscale/private-auth dev mode:

pnpm dev --tailscale-auth

This runs dev as authenticated/private and binds the server to 0.0.0.0 for private-network access.

Allow additional private hostnames (for example custom Tailscale hostnames):

pnpm paperclipai allowed-hostname dotta-macbook-pro

One-Command Local Run

For a first-time local install, you can bootstrap and run in one command:

pnpm paperclipai run

paperclipai run does:

  1. auto-onboard if config is missing
  2. paperclipai doctor with repair enabled
  3. starts the server when checks pass

Docker Quickstart (No local Node install)

Build and run Paperclip in Docker:

docker build -t paperclip-local .
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local

Or use Compose:

docker compose -f docker-compose.quickstart.yml up --build

See doc/DOCKER.md for API key wiring (OPENAI_API_KEY / ANTHROPIC_API_KEY) and persistence details.

Database in Dev (Auto-Handled)

For local development, leave DATABASE_URL unset. The server will automatically use embedded PostgreSQL and persist data at:

  • ~/.paperclip/instances/default/db

Override home and instance:

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

No Docker or external database is required for this mode.

Storage in Dev (Auto-Handled)

For local development, the default storage provider is local_disk, which persists uploaded images/attachments at:

  • ~/.paperclip/instances/default/data/storage

Configure storage provider/settings:

pnpm paperclipai configure --section storage

Default Agent Workspaces

When a local agent run has no resolved project/session workspace, Paperclip falls back to an agent home workspace under the instance root:

  • ~/.paperclip/instances/default/workspaces/<agent-id>

This path honors PAPERCLIP_HOME and PAPERCLIP_INSTANCE_ID in non-default setups.

Quick Health Checks

In another terminal:

curl http://localhost:3100/api/health
curl http://localhost:3100/api/companies

Expected:

  • /api/health returns {"status":"ok"}
  • /api/companies returns a JSON array

Reset Local Dev Database

To wipe local dev data and start fresh:

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

Optional: Use External Postgres

If you set DATABASE_URL, the server will use that instead of embedded PostgreSQL.

Secrets in Dev

Agent env vars now support secret references. By default, secret values are stored with local encryption and only secret refs are persisted in agent config.

  • Default local key path: ~/.paperclip/instances/default/secrets/master.key
  • Override key material directly: PAPERCLIP_SECRETS_MASTER_KEY
  • Override key file path: PAPERCLIP_SECRETS_MASTER_KEY_FILE

Strict mode (recommended outside local trusted machines):

PAPERCLIP_SECRETS_STRICT_MODE=true

When strict mode is enabled, sensitive env keys (for example *_API_KEY, *_TOKEN, *_SECRET) must use secret references instead of inline plain values.

CLI configuration support:

  • pnpm paperclipai onboard writes a default secrets config section (local_encrypted, strict mode off, key file path set) and creates a local key file when needed.
  • pnpm paperclipai configure --section secrets lets you update provider/strict mode/key path and creates the local key file when needed.
  • pnpm paperclipai doctor validates secrets adapter configuration and can create a missing local key file with --repair.

Migration helper for existing inline env secrets:

pnpm secrets:migrate-inline-env         # dry run
pnpm secrets:migrate-inline-env --apply # apply migration

Company Deletion Toggle

Company deletion is intended as a dev/debug capability and can be disabled at runtime:

PAPERCLIP_ENABLE_COMPANY_DELETION=false

Default behavior:

  • local_trusted: enabled
  • authenticated: disabled

CLI Client Operations

Paperclip CLI now includes client-side control-plane commands in addition to setup commands.

Quick examples:

pnpm paperclipai issue list --company-id <company-id>
pnpm paperclipai issue create --company-id <company-id> --title "Investigate checkout conflict"
pnpm paperclipai issue update <issue-id> --status in_progress --comment "Started triage"

Set defaults once with context profiles:

pnpm paperclipai context set --api-base http://localhost:3100 --company-id <company-id>

Then run commands without repeating flags:

pnpm paperclipai issue list
pnpm paperclipai dashboard get

See full command reference in doc/CLI.md.

OpenClaw Invite Onboarding Endpoints

Agent-oriented invite onboarding now exposes machine-readable API docs:

  • GET /api/invites/:token returns invite summary plus onboarding and skills index links.
  • GET /api/invites/:token/onboarding returns onboarding manifest details (registration endpoint, claim endpoint template, skill install hints).
  • GET /api/skills/index lists available skill documents.
  • GET /api/skills/paperclip returns the Paperclip heartbeat skill markdown.