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.- Heartbeat resolves a base workspace for the run.
- Paperclip realizes the effective execution workspace, including creating or reusing a worktree when needed.
- Paperclip persists execution-workspace metadata such as paths, refs, and provisioning settings.
- Heartbeat passes the resolved code workspace to the agent run.
- 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.