paperclip-dev-workspace-run-verify-fix

Orchestrate, verify, and repair isolated Paperclip development workspace services and database states.

79.8k|14.6k|Updated Mar 2, 2026

Search Tags:#workspace #Database #Debugging #Runtime # orchestration #Paperclip

One-click install

npx skills add https://github.com/paperclipai/paperclip --skill paperclip-dev-workspace-run-verify-fix

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: paperclip-dev-workspace-run-verify-fix
Source: https://github.com/paperclipai/paperclip/tree/main/.agents/skills/paperclip-dev-workspace-run-verify-fix
Command: npx skills add https://github.com/paperclipai/paperclip --skill paperclip-dev-workspace-run-verify-fix

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires curl, jq, lsof.

What problem does it solve?

This Skill resolves common development environment issues where Paperclip workspaces, databases, or runtime services become desynchronized, misconfigured, or suffer from port conflicts, ensuring a stable and reliable local development experience.

Core Features & Use Cases

Runtime Orchestration: Manages the lifecycle of workspace services, including controlled start, stop, and restart operations via the Paperclip API.
Identity Verification: Performs rigorous checks on port ownership and process identity to prevent cross-workspace interference (port squatting).
Database Integrity: Executes full worktree reseeding from primary instances to ensure isolated environments contain complete, bootstrapped data.
Use Case: When a developer finds their local workspace app shows a setup gate or missing data, this Skill automates the full reseed and service restart process to restore the environment to a known-good state.

Quick Start

Use the paperclip-dev-workspace-run-verify-fix skill to diagnose and repair the current workspace service by verifying port ownership and performing a full database reseed.

Frequently Asked Questions about paperclip-dev-workspace-run-verify-fix

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I fix a Paperclip workspace that shows a setup gate?▼

Run a full worktree reseed from the primary instance to ensure the isolated database is correctly bootstrapped. After the reseed, use the managed runtime API to restart the service and verify the bootstrap status is ready.

Why does my workspace URL show a different project's app?▼

This is a port conflict known as port squatting, where a sibling workspace process owns the pinned service port. Stop the conflicting sibling service through its managed control path before restarting your target workspace.

How to verify if a Paperclip service is running correctly?▼

Check the service health via the /api/health endpoint and verify the process identity by checking that /proc/<pid>/cwd resolves within the target worktree. Ensure both the main control plane and the served app report the service as running.

Can I use pnpm dev to start my workspace service?▼

Avoid using unmanaged processes like pnpm dev for reusable workspace services. Use the managed runtime API to ensure the service is correctly registered, monitored, and isolated from other workspace processes.