# lee-xeo/claude-cage architecture

> Architecture diagram of the GitHub repository lee-xeo/claude-cage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lee-xeo/claude-cage
- Repository: https://github.com/lee-xeo/claude-cage

## Overview

Claude Cage is a desktop workbench for running Claude Code in an isolated macOS, Windows, or Linux guest, with managed networking and optional remote/mobile access. The main workflow is to configure a proxy, prepare and start a guest, share a project, then use its terminal, browser, and editor. The graph preserves README capabilities and the sampled storage recovery and Windows update paths; other subsystem links are included only where the README documents them, since most implementation files were not sampled.

Main entry points: [`cmd/cage/main.go`](https://github.com/lee-xeo/claude-cage/blob/main/cmd/cage/main.go) (Cage CLI), [`desktop/windows/MainWindow.cs`](https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/MainWindow.cs) (Windows App), [`desktop/windows/AppUpdater.cs`](https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/AppUpdater.cs) (App Updates), [`internal/managedproxy/core.go`](https://github.com/lee-xeo/claude-cage/blob/main/internal/managedproxy/core.go) (Proxy Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Workbench"]
  node_desktopapp["Desktop App<br/>[Cage.swift]"]
  node_windowsapp["Windows App<br/>[MainWindow.cs]"]
  node_backend["App Backend<br/>[Backend.cs]"]
  node_update["App Updates<br/>[AppUpdater.cs]"]
  node_updater_install["Update Installer<br/>[UpdateInstaller.cs]"]
  node_workbench_ui["Workbench UI<br/>[main.jsx]"]
  node_api["UI API<br/>[api.js]"]
end

subgraph group_environment["Guest Environment"]
  node_entry["Cage CLI<br/>[main.go]"]
  node_environment_cli["Environment Commands<br/>[app.go]"]
  node_guest["Guest Lifecycle<br/>[installation.go]"]
  node_vm["Virtual Machines<br/>[vm.go]"]
  node_storage[("Environment Storage<br/>[storage.go]")]
  node_storage_api["Storage Recovery<br/>[storage.go]"]
end

subgraph group_network["Network Safety"]
  node_proxy["Proxy Management<br/>[core.go]"]
  node_network_gate["Network Gate<br/>[gate.go]"]
  node_checks["Safety Checks<br/>[safety.go]"]
end

subgraph group_work["Work Sessions"]
  node_project["Project Sharing<br/>[projects.go]"]
  node_terminal["Terminal Sessions"]
  node_browser["Cage Browser<br/>[browser_service.go]"]
  node_accounts["Claude Accounts<br/>[claude_accounts.go]"]
end

subgraph group_remote["Remote Access"]
  node_mobile_ui["Mobile Sessions<br/>[main.jsx]"]
  node_mobile_link["Mobile Link<br/>[link.go]"]
  node_remote_host["Remote Hosts<br/>[manager.go]"]
  node_relay["Relay Service<br/>[server.go]"]
end

node_user(("User"))
node_mobile(("Phone User"))

node_user -->|"opens"| node_desktopapp
node_desktopapp -.->|"Windows client"| node_windowsapp
node_windowsapp -->|"starts processes"| node_backend
node_windowsapp -->|"manages"| node_update
node_update -->|"runs update command"| node_backend
node_update -->|"installs"| node_updater_install
node_user -->|"configures work"| node_workbench_ui
node_workbench_ui -->|"sends requests"| node_api
node_api -.->|"calls local backend"| node_entry
node_entry -->|"dispatches commands"| node_environment_cli
node_entry -.->|"prepares guest"| node_guest
node_entry -->|"checks managed proxy"| node_proxy
node_guest -.->|"runs guest"| node_vm
node_entry -.->|"serves workbench"| node_storage_api
node_storage_api -->|"reads and recovers"| node_storage
node_user -->|"configures proxy"| node_proxy
node_proxy -.->|"provides egress"| node_network_gate
node_checks -.->|"approves access"| node_network_gate
node_user -->|"opens project"| node_project
node_user -->|"runs Claude Code"| node_terminal
node_user -->|"uses browser"| node_browser
node_user -->|"manages accounts"| node_accounts
node_mobile -->|"continues session"| node_mobile_ui
node_mobile_ui -.->|"connects device"| node_mobile_link
node_user -->|"connects server"| node_remote_host
node_mobile_link -.->|"uses relay"| node_relay

click node_desktopapp "https://github.com/lee-xeo/claude-cage/blob/main/desktop/Cage.swift"
click node_windowsapp "https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/MainWindow.cs"
click node_backend "https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/Backend.cs"
click node_update "https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/AppUpdater.cs"
click node_updater_install "https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/UpdateInstaller.cs"
click node_workbench_ui "https://github.com/lee-xeo/claude-cage/blob/main/ui/src/main.jsx"
click node_api "https://github.com/lee-xeo/claude-cage/blob/main/ui/src/api.js"
click node_entry "https://github.com/lee-xeo/claude-cage/blob/main/cmd/cage/main.go"
click node_environment_cli "https://github.com/lee-xeo/claude-cage/blob/main/internal/cli/app.go"
click node_guest "https://github.com/lee-xeo/claude-cage/blob/main/internal/guestos/installation.go"
click node_vm "https://github.com/lee-xeo/claude-cage/blob/main/internal/vm/vm.go"
click node_storage "https://github.com/lee-xeo/claude-cage/blob/main/internal/cage/storage.go"
click node_storage_api "https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/storage.go"
click node_proxy "https://github.com/lee-xeo/claude-cage/blob/main/internal/managedproxy/core.go"
click node_network_gate "https://github.com/lee-xeo/claude-cage/blob/main/internal/cage/gate.go"
click node_checks "https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/safety.go"
click node_project "https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/projects.go"
click node_terminal "https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/terminal_service.go"
click node_browser "https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/browser_service.go"
click node_accounts "https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/claude_accounts.go"
click node_mobile_ui "https://github.com/lee-xeo/claude-cage/blob/main/ui/src/mobile-cli/main.jsx"
click node_mobile_link "https://github.com/lee-xeo/claude-cage/blob/main/internal/mobilelink/link.go"
click node_remote_host "https://github.com/lee-xeo/claude-cage/blob/main/internal/remotehost/manager.go"
click node_relay "https://github.com/lee-xeo/claude-cage/blob/main/internal/relay/server.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktopapp,node_windowsapp,node_backend,node_update,node_updater_install,node_workbench_ui,node_api,node_user,node_mobile toneBlue
class node_entry,node_environment_cli,node_guest,node_vm,node_storage,node_storage_api toneAmber
class node_proxy,node_network_gate,node_checks toneMint
class node_project,node_terminal,node_browser,node_accounts toneRose
class node_mobile_ui,node_mobile_link,node_remote_host,node_relay toneIndigo
```

## Components

### Desktop Workbench

- [Desktop App](https://github.com/lee-xeo/claude-cage/blob/main/desktop/Cage.swift): `desktop/Cage.swift`
- [Windows App](https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/MainWindow.cs): `desktop/windows/MainWindow.cs`
- [App Backend](https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/Backend.cs): `desktop/windows/Backend.cs`
- [App Updates](https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/AppUpdater.cs): `desktop/windows/AppUpdater.cs`
- [Update Installer](https://github.com/lee-xeo/claude-cage/blob/main/desktop/windows/UpdateInstaller.cs): `desktop/windows/UpdateInstaller.cs`
- [Workbench UI](https://github.com/lee-xeo/claude-cage/blob/main/ui/src/main.jsx): `ui/src/main.jsx`
- [UI API](https://github.com/lee-xeo/claude-cage/blob/main/ui/src/api.js): `ui/src/api.js`

### Guest Environment

- [Cage CLI](https://github.com/lee-xeo/claude-cage/blob/main/cmd/cage/main.go): `cmd/cage/main.go`
- [Environment Commands](https://github.com/lee-xeo/claude-cage/blob/main/internal/cli/app.go): `internal/cli/app.go`
- [Guest Lifecycle](https://github.com/lee-xeo/claude-cage/blob/main/internal/guestos/installation.go): `internal/guestos/installation.go`
- [Virtual Machines](https://github.com/lee-xeo/claude-cage/blob/main/internal/vm/vm.go): `internal/vm/vm.go`
- [Environment Storage](https://github.com/lee-xeo/claude-cage/blob/main/internal/cage/storage.go): `internal/cage/storage.go`
- [Storage Recovery](https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/storage.go): `internal/workbench/storage.go`

### Network Safety

- [Proxy Management](https://github.com/lee-xeo/claude-cage/blob/main/internal/managedproxy/core.go): `internal/managedproxy/core.go`
- [Network Gate](https://github.com/lee-xeo/claude-cage/blob/main/internal/cage/gate.go): `internal/cage/gate.go`
- [Safety Checks](https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/safety.go): `internal/workbench/safety.go`

### Work Sessions

- [Project Sharing](https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/projects.go): `internal/workbench/projects.go`
- [Terminal Sessions](https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/terminal_service.go): `internal/workbench/terminal_service.go`
- [Cage Browser](https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/browser_service.go): `internal/workbench/browser_service.go`
- [Claude Accounts](https://github.com/lee-xeo/claude-cage/blob/main/internal/workbench/claude_accounts.go): `internal/workbench/claude_accounts.go`

### Remote Access

- [Mobile Sessions](https://github.com/lee-xeo/claude-cage/blob/main/ui/src/mobile-cli/main.jsx): `ui/src/mobile-cli/main.jsx`
- [Mobile Link](https://github.com/lee-xeo/claude-cage/blob/main/internal/mobilelink/link.go): `internal/mobilelink/link.go`
- [Remote Hosts](https://github.com/lee-xeo/claude-cage/blob/main/internal/remotehost/manager.go): `internal/remotehost/manager.go`
- [Relay Service](https://github.com/lee-xeo/claude-cage/blob/main/internal/relay/server.go): `internal/relay/server.go`

### Other components

- **User**
- **Phone User**

## Connections

- User → Desktop App: opens
- Desktop App → Windows App: Windows client
- Windows App → App Backend: starts processes (evidence: `desktop/windows/Backend.cs`)
- Windows App → App Updates: manages (evidence: `desktop/windows/MainWindow.cs`)
- App Updates → App Backend: runs update command (evidence: `desktop/windows/AppUpdater.cs`)
- App Updates → Update Installer: installs (evidence: `desktop/windows/AppUpdater.cs`)
- User → Workbench UI: configures work
- Workbench UI → UI API: sends requests (evidence: `ui/src/api.js`)
- UI API → Cage CLI: calls local backend
- Cage CLI → Environment Commands: dispatches commands (evidence: `cmd/cage/main.go`)
- Cage CLI → Guest Lifecycle: prepares guest
- Cage CLI → Proxy Management: checks managed proxy (evidence: `cmd/cage/main.go`)
- Guest Lifecycle → Virtual Machines: runs guest
- Cage CLI → Storage Recovery: serves workbench
- Storage Recovery → Environment Storage: reads and recovers (evidence: `internal/workbench/storage.go`)
- User → Proxy Management: configures proxy
- Proxy Management → Network Gate: provides egress
- Safety Checks → Network Gate: approves access
- User → Project Sharing: opens project
- User → Terminal Sessions: runs Claude Code
- User → Cage Browser: uses browser
- User → Claude Accounts: manages accounts
- Phone User → Mobile Sessions: continues session
- Mobile Sessions → Mobile Link: connects device
- User → Remote Hosts: connects server
- Mobile Link → Relay Service: uses relay