# jamesstringer90/appsandbox architecture

> Architecture diagram of the GitHub repository jamesstringer90/appsandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamesstringer90/appsandbox
- Repository: https://github.com/jamesstringer90/appsandbox

## Overview

App Sandbox runs desktop VMs on Windows and macOS through either a native GUI or a local headless API. Users choose a guest OS and installer or restore image; the platform provisions a disk, performs unattended installation, and starts the VM. The core also supports snapshots, branches, templates (Windows), and VM configuration. Guest integration supplies display, GPU, audio, clipboard, input, and SSH capabilities. The README documents several subsystems whose implementation was not sampled, so their connections are shown only where documented; platform-specific details may be incomplete.

Main entry points: [`src/backend_win/asb_core.c`](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/asb_core.c) (Windows Core), [`tools/transport/asb_transport.c`](https://github.com/jamesstringer90/appsandbox/blob/main/tools/transport/asb_transport.c) (Shared Transport), [`src/app_win/ui.c`](https://github.com/jamesstringer90/appsandbox/blob/main/src/app_win/ui.c) (Native GUI), [`src/app_win/headless.c`](https://github.com/jamesstringer90/appsandbox/blob/main/src/app_win/headless.c) (Headless API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User Interfaces"]
  node_gui["Native GUI<br/>[ui.c]"]
  node_webui["Web UI<br/>[app.js]"]
  node_macui["macOS UI"]
  node_headless["Headless API<br/>[headless.c]"]
  node_sdk["Python SDK<br/>[asb.py]"]
end

subgraph group_lifecycle["VM Lifecycle"]
  node_protocol["Core Protocol<br/>[protocol.h]"]
  node_corewin["Windows Core<br/>[asb_core.c]"]
  node_coremac["macOS Core<br/>[asb_core_mac.h]"]
  node_diskbuild["Disk Provisioning<br/>[iso-patch.c]"]
  node_snapshots["Snapshots<br/>[snapshot.c]"]
end

subgraph group_platform["Host Platforms"]
  node_windowsvm["Windows VM<br/>[hcs_vm.c]"]
  node_network["Host Networking<br/>[hcn_network.c]"]
  node_macvm["macOS VM<br/>[vz_vm.h]"]
end

subgraph group_guest["Guest Integration"]
  node_transport["Shared Transport<br/>[asb_transport.c]"]
  node_winagent["Windows Agent<br/>[agent.c]"]
  node_linuxagent["Linux Agent<br/>[appsandbox-agent.c]"]
  node_display["Virtual Display<br/>[vm_display.c]"]
  node_gpu["GPU Paravirtualization<br/>[d3dlayers.c]"]
  node_audio["Virtual Audio<br/>[adapter.cpp]"]
  node_ssh["SSH Proxy<br/>[vm_ssh_proxy.c]"]
end

node_user(("User"))
node_host(("Host OS"))
node_guestos(("Guest OS"))

node_user -->|"operates"| node_gui
node_user -->|"scripts"| node_sdk
node_gui -->|"hosts"| node_webui
node_webui -->|"sends commands"| node_protocol
node_headless -->|"serves commands"| node_protocol
node_sdk -->|"HTTP requests"| node_headless
node_gui -->|"drives VMs"| node_corewin
node_headless -->|"drives VMs"| node_corewin
node_macui -->|"drives VMs"| node_coremac
node_corewin -->|"provisions disks"| node_diskbuild
node_corewin -->|"creates and runs"| node_windowsvm
node_corewin -->|"configures networking"| node_network
node_corewin -->|"manages snapshots"| node_snapshots
node_coremac -->|"creates and runs"| node_macvm
node_windowsvm -->|"uses guest channel"| node_transport
node_macvm -.->|"uses guest channel"| node_transport
node_transport -->|"dispatches messages"| node_winagent
node_transport -->|"dispatches messages"| node_linuxagent
node_corewin -->|"configures display"| node_display
node_corewin -->|"configures GPU sharing"| node_gpu
node_host -->|"shares GPU"| node_gpu
node_host -->|"hosts audio device"| node_audio
node_winagent -->|"integrates guest"| node_guestos
node_linuxagent -->|"integrates guest"| node_guestos
node_corewin -->|"proxies SSH"| node_ssh
node_ssh -->|"connects to"| node_guestos

click node_gui "https://github.com/jamesstringer90/appsandbox/blob/main/src/app_win/ui.c"
click node_webui "https://github.com/jamesstringer90/appsandbox/blob/main/web/app.js"
click node_macui "https://github.com/jamesstringer90/appsandbox/blob/main/src/app_mac/MainWindowController.h"
click node_headless "https://github.com/jamesstringer90/appsandbox/blob/main/src/app_win/headless.c"
click node_sdk "https://github.com/jamesstringer90/appsandbox/blob/main/tools/headless-api/asb.py"
click node_protocol "https://github.com/jamesstringer90/appsandbox/blob/main/src/core/protocol.h"
click node_corewin "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/asb_core.c"
click node_coremac "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_mac/asb_core_mac.h"
click node_diskbuild "https://github.com/jamesstringer90/appsandbox/blob/main/tools/iso-patch/iso-patch.c"
click node_snapshots "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/snapshot.c"
click node_windowsvm "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/hcs_vm.c"
click node_network "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/hcn_network.c"
click node_macvm "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_mac/vz_vm.h"
click node_transport "https://github.com/jamesstringer90/appsandbox/blob/main/tools/transport/asb_transport.c"
click node_winagent "https://github.com/jamesstringer90/appsandbox/blob/main/tools/agent/agent.c"
click node_linuxagent "https://github.com/jamesstringer90/appsandbox/blob/main/tools/linux/agent/appsandbox-agent.c"
click node_display "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/vm_display.c"
click node_gpu "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/d3dlayers.c"
click node_audio "https://github.com/jamesstringer90/appsandbox/blob/main/tools/vad/adapter.cpp"
click node_ssh "https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/vm_ssh_proxy.c"

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_gui,node_webui,node_macui,node_headless,node_sdk,node_user toneBlue
class node_protocol,node_corewin,node_coremac,node_diskbuild,node_snapshots toneAmber
class node_windowsvm,node_network,node_macvm toneMint
class node_transport,node_winagent,node_linuxagent,node_display,node_gpu,node_audio,node_ssh toneRose
class node_host,node_guestos toneIndigo
```

## Components

### User Interfaces

- [Native GUI](https://github.com/jamesstringer90/appsandbox/blob/main/src/app_win/ui.c): `src/app_win/ui.c`
- [Web UI](https://github.com/jamesstringer90/appsandbox/blob/main/web/app.js): `web/app.js`
- [macOS UI](https://github.com/jamesstringer90/appsandbox/blob/main/src/app_mac/MainWindowController.h): `src/app_mac/MainWindowController.h`
- [Headless API](https://github.com/jamesstringer90/appsandbox/blob/main/src/app_win/headless.c): `src/app_win/headless.c`
- [Python SDK](https://github.com/jamesstringer90/appsandbox/blob/main/tools/headless-api/asb.py): `tools/headless-api/asb.py`

### VM Lifecycle

- [Core Protocol](https://github.com/jamesstringer90/appsandbox/blob/main/src/core/protocol.h): `src/core/protocol.h`
- [Windows Core](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/asb_core.c): `src/backend_win/asb_core.c`
- [macOS Core](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_mac/asb_core_mac.h): `src/backend_mac/asb_core_mac.h`
- [Disk Provisioning](https://github.com/jamesstringer90/appsandbox/blob/main/tools/iso-patch/iso-patch.c): `tools/iso-patch/iso-patch.c`
- [Snapshots](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/snapshot.c): `src/backend_win/snapshot.c`

### Host Platforms

- [Windows VM](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/hcs_vm.c): `src/backend_win/hcs_vm.c`
- [Host Networking](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/hcn_network.c): `src/backend_win/hcn_network.c`
- [macOS VM](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_mac/vz_vm.h): `src/backend_mac/vz_vm.h`

### Guest Integration

- [Shared Transport](https://github.com/jamesstringer90/appsandbox/blob/main/tools/transport/asb_transport.c): `tools/transport/asb_transport.c`
- [Windows Agent](https://github.com/jamesstringer90/appsandbox/blob/main/tools/agent/agent.c): `tools/agent/agent.c`
- [Linux Agent](https://github.com/jamesstringer90/appsandbox/blob/main/tools/linux/agent/appsandbox-agent.c): `tools/linux/agent/appsandbox-agent.c`
- [Virtual Display](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/vm_display.c): `src/backend_win/vm_display.c`
- [GPU Paravirtualization](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/d3dlayers.c): `src/backend_win/d3dlayers.c`
- [Virtual Audio](https://github.com/jamesstringer90/appsandbox/blob/main/tools/vad/adapter.cpp): `tools/vad/adapter.cpp`
- [SSH Proxy](https://github.com/jamesstringer90/appsandbox/blob/main/src/backend_win/vm_ssh_proxy.c): `src/backend_win/vm_ssh_proxy.c`

### Other components

- **User**
- **Host OS**
- **Guest OS**

## Connections

- User → Native GUI: operates
- User → Python SDK: scripts
- Native GUI → Web UI: hosts
- Web UI → Core Protocol: sends commands
- Headless API → Core Protocol: serves commands
- Python SDK → Headless API: HTTP requests
- Native GUI → Windows Core: drives VMs
- Headless API → Windows Core: drives VMs
- macOS UI → macOS Core: drives VMs
- Windows Core → Disk Provisioning: provisions disks
- Windows Core → Windows VM: creates and runs
- Windows Core → Host Networking: configures networking
- Windows Core → Snapshots: manages snapshots
- macOS Core → macOS VM: creates and runs
- Windows VM → Shared Transport: uses guest channel
- macOS VM → Shared Transport: uses guest channel
- Shared Transport → Windows Agent: dispatches messages
- Shared Transport → Linux Agent: dispatches messages
- Windows Core → Virtual Display: configures display
- Windows Core → GPU Paravirtualization: configures GPU sharing
- Host OS → GPU Paravirtualization: shares GPU
- Host OS → Virtual Audio: hosts audio device
- Windows Agent → Guest OS: integrates guest
- Linux Agent → Guest OS: integrates guest
- Windows Core → SSH Proxy: proxies SSH
- SSH Proxy → Guest OS: connects to