Execution Workspaces
When an agent picks up a task that involves working with code or files, it needs a place to do that work — a folder with the right code checked out at the right state, ready for the agent to read, ed…
Workspaces
When an agent picks up a task that involves working with code or files, it needs a place to do that work — a folder with the right code checked out at the right state, ready for the agent to read, edit, and run. That's what an execution workspace is: a snapshot of a project's working directory, tied to a specific task run.
Execution workspaces exist so that multiple agents can work on the same project simultaneously without stepping on each other. When a project is configured for isolated work, agents can get their own copy — their own branch, folder, and runtime context — so work in one workspace doesn't accidentally break another.
This guide covers what execution workspaces are, how they relate to projects, and how to use the workspace detail screen — its three tabs, runtime controls, and logs — to inspect and manage them.
---
How execution workspaces relate to projects
Every execution workspace is linked to a project. The project defines the base configuration — where the code lives, how to run it, what the default setup looks like.
When a task runs, Paperclip resolves which execution workspace to use for that run:
The heartbeat fires and the agent picks up a task Paperclip resolves the workspace — creating a new one, reusing an existing one, or sticking with the project default, depending on your settings The agent receives the workspace path and works within it The workspace persists after the run if you're using an isolated or reusable workspace mode
!Execution workspace list showing multiple isolated workspaces for a project (/uploads/content/2026/04/cc3e27ac-61e0-431c-89d2-f76bd18acf16.webp)