PaperClipAI/maps/feature-map/instance-operations.md

Installation, configuration, updates, and backups

An operator can install and run Paperclip, diagnose the instance, configure supported deployment settings, manage its service, and produce a recoverable database backup.

Implementation: CLI entry point, instance settings, backup command.

Agent access: companion.

Sub-features

• install-update: inspect install channel/version and apply supported update or rollback operations.
• server-service: start/stop the intended instance and inspect its service health.
• configuration: configure database, server binding, storage, secrets, and available experimental settings.
• diagnostics: use doctor/health output to distinguish readiness from a listening port.
• backup: create and inspect backups and verify restore only into a separate disposable target.

How to get to it (user POV)

operator-cli

Use paperclipai install, run, service, doctor, configure, channels, or update --help for the intended operation.

settings-backup

Use currently visible instance settings for experiments/access and paperclipai db:backup --help for one-off backup. Some legacy general-settings URLs redirect.

Driving it with Playwright and the Paperclip CLI

Preconditions: follow the baseline. Use a disposable data directory/service identity. Do not update, restart, or restore over an unrelated live instance as a documentation test.

operator-cli

Automated: doctor, update command, and service manager cover command contracts.

Manual: Inspect the selected installation/channel and configuration, start the isolated instance, confirm health and browser access, then stop that instance. For update changes, use the dry-run/check path first and verify installed version and rollback state on an owned disposable installation.

Routine HTTP monitoring may use GET /api/liveness (or HEAD). It returns only process startup status and the public build commit without SQL or authentication. It remains reachable during an idle drain. Use /api/health for explicit database readiness, signed bootstrap, and authorized diagnostics; liveness does not establish database health or claim a workspace.

settings-backup

Automated: experimental settings and database backup routes cover their UI/API contracts.

Manual: Change a harmless experimental setting, reload, and confirm the affected route honors it. Back up a disposable instance, inspect the reported file and metadata, and restore using the documented procedure into a second isolated target. Verify a known record after restoration.

Gotchas

• Source-checkout update/check commands report manual update guidance; they do not qualify a managed installation. Rollback restores retained CLI payloads, not database migrations. Service status applies to its selected service identity, not automatically to an owned foreground dev server.

• A successful backup write does not prove restoration works.

• Settings visibility and mutability differ for cloud-managed and self-hosted instances.

• Keep the three data paths distinct: first-party Telemetry, operator-configured OpenTelemetry, and local run logs.