# tsuyakashi/proxmox-hosted-workstation architecture

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

- Interactive diagram: https://gitdiagram.com/tsuyakashi/proxmox-hosted-workstation
- Repository: https://github.com/tsuyakashi/proxmox-hosted-workstation

## Overview

This repository deploys Proxmox-hosted workstations: Terraform defines Windows and macOS VMs, an Ubuntu desktop LXC, and a separate headless macOS VM; host-side scripts handle GPU ownership and privileged LXC setup. The main user workflow is selecting a workstation with `workstation.sh`, which manages the mutually exclusive GPU-backed guests. README documents the configuration relationships and operational responsibilities; source excerpts were not available, so uncertain script-to-script calls are omitted.

Main entry points: [`mod/vm/main.tf`](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/mod/vm/main.tf) (VM module), [`env/windows/main.tf`](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/windows/main.tf) (Windows VM config), [`scripts/workstation.sh`](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/workstation.sh) (Workstation lifecycle), [`scripts/ct-recreate.sh`](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/ct-recreate.sh) (Privileged CT creation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_envs["Workstation environments"]
  node_windows["Windows VM config<br/>[main.tf]"]
  node_ubuntu["Ubuntu LXC config<br/>[main.tf]"]
  node_macdesktop["macOS desktop config<br/>[main.tf]"]
  node_macheadless["macOS headless config<br/>[main.tf]"]
end

subgraph group_modules["Terraform modules"]
  node_vm["VM module<br/>[main.tf]"]
  node_ct["LXC module<br/>[main.tf]"]
end

subgraph group_hostops["Host operations"]
  node_provision["Ubuntu desktop provisioner"]
  node_recreate["Privileged CT creation<br/>[ct-recreate.sh]"]
  node_passthrough["LXC device passthrough"]
  node_workstation["Workstation lifecycle<br/>[workstation.sh]"]
  node_arbiter["GPU arbiter<br/>[gpu-arbiter.sh]"]
  node_vfio["IOMMU VFIO setup"]
  node_nvidiahost["NVIDIA host setup"]
end

subgraph group_platform["Platform services"]
  node_proxmox["Proxmox VE"]
  node_state[("Terraform state")]
  node_vault["HashiCorp Vault"]
  node_host["Proxmox host"]
end

node_operator(("Operator"))
node_terraform["Terraform CLI"]

node_operator -->|"runs plans"| node_terraform
node_terraform -->|"applies config"| node_windows
node_terraform -->|"applies config"| node_ubuntu
node_terraform -->|"applies config"| node_macdesktop
node_terraform -->|"applies config"| node_macheadless
node_windows -->|"uses module"| node_vm
node_macdesktop -->|"uses module"| node_vm
node_macheadless -->|"uses module"| node_vm
node_ubuntu -->|"uses module"| node_ct
node_vm -->|"creates VMs"| node_proxmox
node_ct -->|"creates container"| node_proxmox
node_terraform -->|"reads/writes state"| node_state
node_operator -->|"selects guest"| node_workstation
node_workstation -->|"rebinds GPU"| node_host
node_workstation -->|"starts guest"| node_proxmox
node_recreate -->|"creates privileged CT"| node_host
node_recreate -->|"imports CT"| node_terraform
node_passthrough -->|"configures CT devices"| node_host
node_provision -->|"installs desktop"| node_host
node_vfio -->|"configures VFIO"| node_host
node_nvidiahost -->|"configures NVIDIA"| node_host
node_arbiter -->|"manages GPU ownership"| node_host
node_windows -.->|"uses secrets"| node_vault

click node_windows "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/windows/main.tf"
click node_ubuntu "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/ubuntu/main.tf"
click node_macdesktop "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/macos-tahoe-desktop/main.tf"
click node_macheadless "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/macos-tahoe-headless/main.tf"
click node_vm "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/mod/vm/main.tf"
click node_ct "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/mod/ct/main.tf"
click node_provision "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/lxc-ubuntu-desktop-provision.sh"
click node_recreate "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/ct-recreate.sh"
click node_passthrough "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/lxc-ct-passthrough.sh"
click node_workstation "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/workstation.sh"
click node_arbiter "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/gpu-arbiter.sh"
click node_vfio "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/iommu-vfio-setup.sh"
click node_nvidiahost "https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/lxc-nvidia-host-setup.sh"

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_windows,node_ubuntu,node_macdesktop,node_macheadless toneBlue
class node_vm,node_ct toneAmber
class node_provision,node_recreate,node_passthrough,node_workstation,node_arbiter,node_vfio,node_nvidiahost toneMint
class node_proxmox,node_state,node_vault,node_host toneRose
class node_operator,node_terraform toneIndigo
```

## Components

### Workstation environments

- [Windows VM config](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/windows/main.tf): `env/windows/main.tf`
- [Ubuntu LXC config](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/ubuntu/main.tf): `env/ubuntu/main.tf`
- [macOS desktop config](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/macos-tahoe-desktop/main.tf): `env/macos-tahoe-desktop/main.tf`
- [macOS headless config](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/env/macos-tahoe-headless/main.tf): `env/macos-tahoe-headless/main.tf`

### Terraform modules

- [VM module](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/mod/vm/main.tf): `mod/vm/main.tf`
- [LXC module](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/mod/ct/main.tf): `mod/ct/main.tf`

### Host operations

- [Ubuntu desktop provisioner](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/lxc-ubuntu-desktop-provision.sh): `scripts/lxc-ubuntu-desktop-provision.sh`
- [Privileged CT creation](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/ct-recreate.sh): `scripts/ct-recreate.sh`
- [LXC device passthrough](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/lxc-ct-passthrough.sh): `scripts/lxc-ct-passthrough.sh`
- [Workstation lifecycle](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/workstation.sh): `scripts/workstation.sh`
- [GPU arbiter](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/gpu-arbiter.sh): `scripts/gpu-arbiter.sh`
- [IOMMU VFIO setup](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/iommu-vfio-setup.sh): `scripts/iommu-vfio-setup.sh`
- [NVIDIA host setup](https://github.com/tsuyakashi/proxmox-hosted-workstation/blob/main/scripts/lxc-nvidia-host-setup.sh): `scripts/lxc-nvidia-host-setup.sh`

### Platform services

- **Proxmox VE**
- **Terraform state**
- **HashiCorp Vault**
- **Proxmox host**

### Other components

- **Operator**
- **Terraform CLI**

## Connections

- Operator → Terraform CLI: runs plans
- Terraform CLI → Windows VM config: applies config
- Terraform CLI → Ubuntu LXC config: applies config
- Terraform CLI → macOS desktop config: applies config
- Terraform CLI → macOS headless config: applies config
- Windows VM config → VM module: uses module
- macOS desktop config → VM module: uses module
- macOS headless config → VM module: uses module
- Ubuntu LXC config → LXC module: uses module
- VM module → Proxmox VE: creates VMs
- LXC module → Proxmox VE: creates container
- Terraform CLI → Terraform state: reads/writes state
- Operator → Workstation lifecycle: selects guest
- Workstation lifecycle → Proxmox host: rebinds GPU
- Workstation lifecycle → Proxmox VE: starts guest
- Privileged CT creation → Proxmox host: creates privileged CT
- Privileged CT creation → Terraform CLI: imports CT
- LXC device passthrough → Proxmox host: configures CT devices
- Ubuntu desktop provisioner → Proxmox host: installs desktop
- IOMMU VFIO setup → Proxmox host: configures VFIO
- NVIDIA host setup → Proxmox host: configures NVIDIA
- GPU arbiter → Proxmox host: manages GPU ownership
- Windows VM config → HashiCorp Vault: uses secrets