Spaces:
Paused
Paused
| title: Execution Workspaces And Runtime Services | |
| summary: How project runtime configuration, execution workspaces, and issue runs fit together | |
| This guide documents the intended runtime model for projects, execution workspaces, and issue runs in Paperclip. | |
| ## Project runtime configuration | |
| You can define how to run a project on the project workspace itself. | |
| - Project workspace runtime config describes how to run services for that project checkout. | |
| - This is the default runtime configuration that child execution workspaces may inherit. | |
| - Defining the config does not start anything by itself. | |
| ## Manual runtime control | |
| Runtime services are manually controlled from the UI. | |
| - Project workspace runtime services are started and stopped from the project workspace UI. | |
| - Execution workspace runtime services are started and stopped from the execution workspace UI. | |
| - Paperclip does not automatically start or stop these runtime services as part of issue execution. | |
| - Paperclip also does not automatically restart workspace runtime services on server boot. | |
| ## Execution workspace inheritance | |
| Execution workspaces isolate code and runtime state from the project primary workspace. | |
| - An isolated execution workspace has its own checkout path, branch, and local runtime instance. | |
| - The runtime configuration may inherit from the linked project workspace by default. | |
| - The execution workspace may override that runtime configuration with its own workspace-specific settings. | |
| - The inherited configuration answers "how to run the service", but the running process is still specific to that execution workspace. | |
| ## Issues and execution workspaces | |
| Issues are attached to execution workspace behavior, not to automatic runtime management. | |
| - An issue may create a new execution workspace when you choose an isolated workspace mode. | |
| - An issue may reuse an existing execution workspace when you choose reuse. | |
| - Multiple issues may intentionally share one execution workspace so they can work against the same branch and running runtime services. | |
| - Assigning or running an issue does not automatically start or stop runtime services for that workspace. | |
| ## Execution workspace lifecycle | |
| Execution workspaces are durable until a human closes them. | |
| - The UI can archive an execution workspace. | |
| - Closing an execution workspace stops its runtime services and cleans up its workspace artifacts when allowed. | |
| - Shared workspaces that point at the project primary checkout are treated more conservatively during cleanup than disposable isolated workspaces. | |
| ## Resolved workspace logic during heartbeat runs | |
| Heartbeat still resolves a workspace for the run, but that is about code location and session continuity, not runtime-service control. | |
| 1. Heartbeat resolves a base workspace for the run. | |
| 2. Paperclip realizes the effective execution workspace, including creating or reusing a worktree when needed. | |
| 3. Paperclip persists execution-workspace metadata such as paths, refs, and provisioning settings. | |
| 4. Heartbeat passes the resolved code workspace to the agent run. | |
| 5. Workspace runtime services remain manual UI-managed controls rather than automatic heartbeat-managed services. | |
| ## Current implementation guarantees | |
| With the current implementation: | |
| - Project workspace runtime config is the fallback for execution workspace UI controls. | |
| - Execution workspace runtime overrides are stored on the execution workspace. | |
| - Heartbeat runs do not auto-start workspace runtime services. | |
| - Server startup does not auto-restart workspace runtime services. | |