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

> Explore Paperclip's execution workspaces, dedicated filesystem checkouts for runs and issues. Learn about Git worktrees and cloud-managed alternatives in this technical guide.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: deep-dive
- Published: 2026-08-14

---

**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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/execution-workspaces.ts), imported by the runtime service at [`server/src/services/workspace-runtime.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/workspace-runtime.ts) (Line 39).

## Working with the Execution Workspaces API

### List Workspaces for a Company

```typescript
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`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/execution-workspaces.ts) (Line 78)

### Create or Configure an Isolated Workspace

```typescript
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`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/execution-workspaces.ts) (Line 585)

### Control Runtime Services

```typescript
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`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/execution-workspaces.ts) (Line 493-494)

### Read Workspace Configuration

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

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

```

*Source:* [`server/src/routes/execution-workspaces.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/packages/shared/src/types/workspace-runtime.ts) | Core type definitions for strategy, mode, provider, status, and runtime state |
| [`server/src/services/execution-workspaces.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/execution-workspaces.ts) | Service layer for create, update, reconcile, and control operations |
| [`server/src/routes/execution-workspaces.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/execution-workspaces.ts) | REST API endpoints |
| [`ui/src/lib/project-workspaces-tab.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/lib/project-workspaces-tab.ts) | UI workspace selector logic |
| [`ui/src/pages/ExecutionWorkspaceDetail.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/src/pages/ExecutionWorkspaceDetail.tsx) | Workspace management interface |
| [`doc/plans/workspace-product-model-and-work-product.md`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/execution-workspaces.ts) provides full CRUD plus runtime service control and branch reconciliation.
- **UI components** in [`ExecutionWorkspaceDetail.tsx`](https://github.com/paperclipai/paperclip/blob/main/ExecutionWorkspaceDetail.tsx) and [`project-workspaces-tab.ts`](https://github.com/paperclipai/paperclip/blob/main/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.