What Are Paperclip's Execution Workspaces? A Complete Technical Guide

Execution workspaces are first-class filesystem checkouts in Paperclip where runs and issues actually execute, typically implemented as local Git worktrees with support for cloud and adapter-managed alternatives.

This article explains the execution workspace model in the paperclipai/paperclip repository, covering its type system, lifecycle policies, REST API, and UI integration. Whether you're building integrations or customizing workspace behavior, understanding these internals is essential.

What Defines an Execution Workspace in Paperclip

An execution workspace represents the concrete environment where code runs. According to the product model specification, every execution workspace is fundamentally a local Git worktree at its core.

The type system in packages/shared/src/types/workspace-runtime.ts defines several critical aspects:

Core Type Definitions

• ExecutionWorkspaceProviderType (Line 25-29): Enumerates supported backends including local Git worktrees, cloud sandboxes, and adapter-managed environments.

• Runtime configuration (Line 91-99): Each workspace carries provision/teardown commands, desired runtime state, and a map of per-service states.

• Status tracking (Line 31-42): Workspaces track both status (active, idle, in-review, archived, cleanup-failed) and delivery state (merged-via-PR, merged-by-ancestry, unmerged, unknown).

• ExecutionWorkspaceStrategy (Line 81-89): Defines creation strategy options—project primary, git worktree, adapter-managed, or cloud sandbox.

Execution Workspace Lifecycle and Ownership

Paperclip implements a flexible ownership model that balances isolation with reuse capabilities.

One Current Workspace Per Issue

Each issue points to a single current execution workspace at any moment, though it can link to multiple workspaces over its lifetime. This is documented in doc/plans/workspace-technical-implementation.md (Line 22-29).

Intentional Sharing for Long-Lived Workflows

Multiple issues can deliberately reuse the same execution workspace. This enables long-lived branch workflows where related changes share a common environment, as noted in the product model (Line 420-425).

Project-Level Policy Control

Projects configure default behavior through ProjectExecutionWorkspaceDefaultMode (Line 9-13 in workspace-runtime.ts), with options including:

• shared — reuse existing workspaces
• isolated — create dedicated workspaces per issue
• operator-branch — maintain operator-managed branch workflows

Issues may override these defaults with per-issue settings.

REST API for Execution Workspaces

Paperclip exposes full CRUD and runtime control through dedicated REST endpoints in server/src/routes/execution-workspaces.ts:

Endpoint	Method	Purpose
/api/companies/{companyId}/execution-workspaces	GET	List workspaces with optional summary filtering (Line 78)
/api/execution-workspaces/{id}	GET	Retrieve detailed workspace configuration (Line 113)
/api/execution-workspaces/{id}	PATCH	Update workspace properties including mode and commands (Line 585)
/api/execution-workspaces/{id}/runtime-services/:action	POST	Control individual services—start, stop, restart (Line 493)
/api/execution-workspaces/{id}/runtime-commands/:action	POST	Execute arbitrary runtime commands (Line 494)
/api/execution-workspaces/{id}/reconcile-branch	POST	Trigger branch reconciliation for Git-backed workspaces (Line 496)

The underlying service implementation lives in server/src/services/execution-workspaces.ts, imported by the runtime service at server/src/services/workspace-runtime.ts (Line 39).

Working with the Execution Workspaces API

List Workspaces for a Company

import fetch from 'node-fetch';

async function listWorkspaces(companyId: string) {
  const res = await fetch(
    `https://api.paperclip.ai/api/companies/${companyId}/execution-workspaces?summary=true`,
    { headers: { Authorization: `Bearer ${process.env.PAPERCLIP_API_KEY}` } }
  );
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
  return data; // → array of ExecutionWorkspaceSummary
}

Source: server/src/routes/execution-workspaces.ts (Line 78)

Create or Configure an Isolated Workspace

import { patch } from '@/api/execution-workspaces';

await patch(issueId, {
  mode: 'isolated_workspace',            // ExecutionWorkspaceMode
  provisionCommand: 'npm install && npm run build',
  runtimeProvisionCommand: 'docker compose up -d',
  environmentId: 'env-123',
});

Source: server/src/routes/execution-workspaces.ts (Line 585)

Control Runtime Services

import { post } from '@/api/execution-workspaces';

await post(workspaceId, 'runtime-services', {
  action: 'restart',                     // Service action
  serviceId: 'dev-server',
});

Source: server/src/routes/execution-workspaces.ts (Line 493-494)

Read Workspace Configuration

import { get } from '@/api/execution-workspaces';

const workspace = await get(workspaceId);
console.log(workspace.config?.environmentId);

Source: server/src/routes/execution-workspaces.ts (Line 113)

UI Integration in Paperclip

The execution workspace model is fully integrated into Paperclip's React frontend:

• Selector component: ui/src/lib/project-workspaces-tab.ts (Line 119-126) builds reusable option groups and handles default mode logic for the dropdown on issue pages.

• Detail page: ui/src/pages/ExecutionWorkspaceDetail.tsx (Line 839-860) provides status visualization, configuration editing, and direct runtime action invocation.

The reusable workspace options are extracted in ui/src/lib/reusable-execution-workspaces.ts for consistent UI patterns across the application.

Key Source Files Reference

File	Role
packages/shared/src/types/workspace-runtime.ts	Core type definitions for strategy, mode, provider, status, and runtime state
server/src/services/execution-workspaces.ts	Service layer for create, update, reconcile, and control operations
server/src/routes/execution-workspaces.ts	REST API endpoints
ui/src/lib/project-workspaces-tab.ts	UI workspace selector logic
ui/src/pages/ExecutionWorkspaceDetail.tsx	Workspace management interface
doc/plans/workspace-product-model-and-work-product.md	Product specification and lifecycle documentation

Summary

• Execution workspaces are first-class filesystem environments in Paperclip, typically Git worktrees.
• The type system in workspace-runtime.ts defines strategy, provider type, status, and runtime configuration.
• Lifecycle policies support both isolated and shared workspace modes with project defaults and per-issue overrides.
• The REST API in execution-workspaces.ts provides full CRUD plus runtime service control and branch reconciliation.
• UI components in ExecutionWorkspaceDetail.tsx and project-workspaces-tab.ts expose these capabilities to users.

Frequently Asked Questions

How does Paperclip decide whether to create a new execution workspace or reuse an existing one?

The decision flows from ProjectExecutionWorkspaceDefaultMode configured at the project level, which can be overridden by per-issue settings. When mode is isolated, Paperclip creates a dedicated workspace; when shared, it attempts to match and reuse existing workspaces. The matching logic respects the execution workspace strategy and provider type constraints.

Can execution workspaces exist outside of local Git worktrees?

Yes. While the default implementation uses local Git worktrees, the ExecutionWorkspaceProviderType enum and adapter-managed or cloud sandbox strategies enable remote and containerized alternatives. These require appropriate adapter implementations in the service layer.

What happens to execution workspaces when an issue is closed or merged?

Workspaces transition through status states including active, idle, in-review, and eventually archived. The delivery state tracks whether changes reached the main branch via PR merge or ancestry. Cleanup failures are explicitly tracked in cleanup-failed status, allowing operators to intervene before resource leaks occur.

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