System map
How Copse fits together
Explore the desktop runtime, agent turn, safety gates, persistent data, UI bridge, auxiliary agents, workspace services, and build pipeline. Choose a view, then select any component to see its current responsibilities and source files.
Where the project sandbox applies
Permission to call a tool and OS containment are separate checks. Electron main is the trusted host; the project sandbox restricts the local subprocesses and filesystem workers routed through it, not every operation performed by the app.
| Execution path | Boundary and exceptions |
|---|---|
| Local commands and file workers | macOS seatbelt or Linux bubblewrap applies while the project sandbox is active. Windows and sandbox initialization failures have no project OS containment; shell commands then require approval. A thread execution root alone is not an OS sandbox. |
| Commands outside the sandbox | Approved external commands and verified-block retries run outside it. Eligible deterministic auto-approval can skip the prompt only while the project sandbox is active; Guarded YOLO can also allow some external commands through its harm gate. Approval does not make these executions contained. |
| Trusted host services | Provider requests, web fetches, and GitHub API tools use the host network path. The GitHub service explicitly runs gh outside the project sandbox. Dedicated GitHub writes still require approval; web calls have their own origin policy. |
| Configured MCP and custom tools | Configured stdio MCP servers launch without the project sandbox wrapper; HTTP MCP runs at the configured server. Trust, annotations and approval policy govern calls. User-installed custom JavaScript runs in the main process with Node privileges, outside project containment. |
| ACP and remote agents | A local ACP process is contained only with a sandbox configuration and an active project sandbox. SSH and managed agents execute remotely under the remote environment's controls. Calls back through Copse's native bridge use each tool's own host policy and execution path. |
| Hooks and container runs | Command hooks use the project sandbox by default when active; sandbox: false and the trusted-code fallback run outside it. First-party function hooks run in-process. Optional Docker runs use guest containment and brokered egress, a separate boundary from the host project sandbox. |