Paperclip Company Portability Workflow: Import/Export with Secret Scrubbing

Paperclip enables secure migration of entire companies—including agents, projects, tasks, and skills—across environments through a three-stage export, preview, and apply workflow that automatically strips all secrets, local paths, and database IDs.

The paperclipai/paperclip repository implements a robust company portability system that allows board operators to version-control and transfer AI agent configurations without exposing sensitive data. This workflow ensures that secret values never leave the originating instance while maintaining full structural integrity of the company definition.

The Three-Stage Portability Workflow

The portability system follows a strict three-stage pipeline defined in server/src/routes/company-import-paths.ts to prevent accidental data leakage and provide full transparency before any changes are committed.

Stage 1: Export Package Generation

During the export phase, the server constructs a portable markdown package conforming to the Agent Companies specification. The system gathers structural files including COMPANY.md, agents/, projects/, skills/, tasks/, and .paperclip.yaml directories.

Critical security filtering occurs in server/src/services/company-import-transfers.ts, where the export service explicitly removes secret values, machine-local paths, and database identifiers before writing to the zip archive. This ensures the generated package contains only structural definitions without sensitive runtime data.

The export endpoint is defined as:

POST /api/companies/{companyId}/export

Stage 2: Import Preview and Validation

Before any data modification occurs, the system generates an import plan through the preview endpoints. These endpoints return a detailed analysis of which entities will be created, renamed, skipped, or replaced, along with required environment inputs and warnings for missing dependencies.

The preview respects identical secret-scrubbing rules as the export phase, ensuring no secrets are introduced during the validation step. Available endpoints include:

• POST /api/companies/{companyId}/imports/preview (for existing companies)
• POST /api/companies/import/preview (for new company creation)

Stage 3: Apply with Safety Controls

The final stage commits the import to the target company. By default, imported agents and routines are created in a paused state (pauseAutomations: true) to prevent immediate execution until explicitly activated by a board operator.

The apply endpoints enforce collision strategies (rename, skip, replace) and never persist secret values from the source package:

• POST /api/companies/{companyId}/imports/apply
• POST /api/companies/import

How Secret Scrubbing Works

Secret scrubbing is enforced at the service layer rather than the client side. According to the implementation in server/src/services/company-import-transfers.ts, the system filters fields marked as secret during export, ensuring that "secret values, machine-local paths, and database IDs are never exported."

This server-side enforcement guarantees that downstream imports cannot accidentally acquire secrets from the source company, even if the export package is shared via public version control.

CLI Commands for Company Import/Export

The Paperclip CLI provides direct interfaces to the portability API endpoints. All commands automatically respect the secret-scrubbing policy.

Export a company to a local directory:

paperclipai company export abc123 --out ./my-export \
  --include company,agents,projects

Preview an import without applying changes:

paperclipai company import ./my-export \
  --target existing --company-id abc123 \
  --dry-run

Apply an import to create a new company with paused automations:

paperclipai company import ./my-export \
  --target new \
  --new-company-name "Cloned Company" \
  --yes --json

Import from a remote GitHub repository with version pinning:

paperclipai company import org/repo \
  --ref v2.0.0 --target existing --company-id abc123 \
  --collision rename

Key Implementation Files

The portability workflow is implemented across the following critical paths in the paperclipai/paperclip repository:

• server/src/routes/company-import-paths.ts: Defines REST endpoints for export, preview, and apply operations.
• server/src/services/company-import-transfers.ts: Core logic for building export packages and performing import writes, including secret filtering.
• packages/shared/src/company-import-transfer.ts: Shared TypeScript interfaces used by both server and UI layers.
• ui/src/lib/import-transfer.ts: Client-side helper functions that interface with the import/export API from the web interface.
• docs/guides/board-operator/importing-and-exporting.md: Comprehensive documentation covering workflow options and security guarantees.

Summary

• The Paperclip company portability workflow uses a three-stage pipeline: Export, Preview, and Apply to ensure safe cross-environment transfers.
• Secret scrubbing is enforced server-side in server/src/services/company-import-transfers.ts, automatically stripping sensitive values, local paths, and database IDs.
• The preview stage provides a dry-run import plan showing entity collisions and required inputs before any changes occur.
• Imported agents default to a paused state (pauseAutomations: true) to prevent unintended execution in new environments.
• The system supports collision strategies (rename, skip, replace) for handling naming conflicts during import.

Frequently Asked Questions

Does Paperclip export include API keys or environment secrets?

No. The export service explicitly filters out all secret values, machine-local paths, and database identifiers before generating the portable package. This scrubbing occurs in server/src/services/company-import-transfers.ts and is enforced server-side, ensuring sensitive data never leaves the originating instance.

Can I import a company without immediately activating its agents?

Yes. By default, the import process creates agents and routines in a paused state using pauseAutomations: true. This prevents imported automations from running until a board operator explicitly activates them through the UI or API.

What happens if imported entities have the same names as existing ones?

The import workflow supports three collision strategies: rename (creates new entities with modified names), skip (preserves existing entities), and replace (overwrites existing entities). You specify the desired behavior using the --collision flag in the CLI or the corresponding API parameter.

Is the company portability format compatible with version control?

Yes. The export generates a markdown-based package following the Agent Companies specification, including files like COMPANY.md and directories for agents/, projects/, and skills/. Because secret scrubbing removes all sensitive runtime data, these packages are safe to commit to Git repositories for versioning and sharing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}