# kashiwagieri233/palette architecture

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

- Interactive diagram: https://gitdiagram.com/kashiwagieri233/palette
- Repository: https://github.com/kashiwagieri233/palette

## Overview

Palette is a managed QEMU desktop service with two principal workflows: MCP agents observe a bounded screenshot and submit frame-bound actions, while Desktop/CLI users create and manage persistent VMs, view them, and take exclusive input control. The runtime centralizes authorization, scheduling, auditing, VM lifecycle, and guest integrations. The README documents the cross-process product paths; source-index references support several internal dependencies, but many implementation details were not sampled, so those links are omitted or marked unverified.

Main entry points: [`src/palette/service.py`](https://github.com/kashiwagieri233/palette/blob/main/src/palette/service.py) (Palette service), [`desktop/src/renderer/App.tsx`](https://github.com/kashiwagieri233/palette/blob/main/desktop/src/renderer/App.tsx) (Desktop workbench), [`src/palette/vm/manager.py`](https://github.com/kashiwagieri233/palette/blob/main/src/palette/vm/manager.py) (VM lifecycle), [`src/palette/guest_tools/bridge.py`](https://github.com/kashiwagieri233/palette/blob/main/src/palette/guest_tools/bridge.py) (Guest tool bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_desktop_ui["Desktop workbench<br/>[App.tsx]"]
  node_agent_client["Built-in agent<br/>[agent-client.ts]"]
  node_rfb["Live screen console<br/>[Console.tsx]"]
end

subgraph group_interfaces["Service interfaces"]
  node_mcp["MCP server<br/>[server.py]"]
  node_operator_server["Operator IPC<br/>[server.py]"]
  node_desktop_ipc["Desktop IPC<br/>[ipc.ts]"]
  node_service["Palette service<br/>[service.py]"]
end

subgraph group_guardrails["Policy and control"]
  node_policy["Authorization<br/>[policy.py]"]
  node_control["Control lease<br/>[control.py]"]
  node_controller["Action scheduler<br/>[controller.py]"]
  node_audit["Metadata audit<br/>[audit.py]"]
end

subgraph group_vmruntime["VM runtime"]
  node_manager["VM lifecycle<br/>[manager.py]"]
  node_persistent["Persistent VM storage"]
  node_images["Image manager<br/>[images.py]"]
  node_launcher["QEMU launcher<br/>[launcher.py]"]
  node_qmp["QMP client<br/>[client.py]"]
end

subgraph group_guest["Guest integrations"]
  node_guest_bridge["Guest tool bridge<br/>[bridge.py]"]
  node_guest_tools["Guest tool contract<br/>[base.py]"]
  node_windows_guest["Windows enhancements"]
end

node_agent(("MCP agent"))
node_desktop(("Palette Desktop"))
node_operator(("Operator CLI"))

node_agent -->|"uses MCP"| node_mcp
node_mcp -->|"dispatches tools"| node_service
node_desktop -->|"operates workbench"| node_desktop_ui
node_desktop_ui -.->|"requests runtime"| node_desktop_ipc
node_desktop_ipc -.->|"uses local IPC"| node_operator_server
node_operator -->|"uses local IPC"| node_operator_server
node_operator_server -->|"dispatches commands"| node_service
node_desktop_ui -->|"views live screen"| node_rfb
node_desktop_ui -->|"requests takeover"| node_control
node_agent -.->|"prompts built-in agent"| node_agent_client
node_agent_client -->|"invokes agent API"| node_desktop_ipc
node_service -->|"authorizes requests"| node_policy
node_service -->|"dispatches VM operations"| node_manager
node_service -->|"schedules actions"| node_controller
node_service -->|"records events"| node_audit
node_service -->|"checks ownership"| node_control
node_controller -->|"sends input"| node_qmp
node_manager -.->|"starts instances"| node_launcher
node_launcher -.->|"opens management channel"| node_qmp
node_manager -->|"manages guest tools"| node_guest_bridge
node_guest_bridge -.->|"implements contract"| node_guest_tools
node_guest_bridge -.->|"exposes guest operations"| node_windows_guest
node_manager -.->|"manages disk state"| node_persistent
node_persistent -->|"inspects images"| node_images
node_images -->|"supplies image paths"| node_launcher

click node_mcp "https://github.com/kashiwagieri233/palette/blob/main/src/palette/server.py"
click node_operator_server "https://github.com/kashiwagieri233/palette/blob/main/src/palette/operator/server.py"
click node_desktop_ui "https://github.com/kashiwagieri233/palette/blob/main/desktop/src/renderer/App.tsx"
click node_desktop_ipc "https://github.com/kashiwagieri233/palette/blob/main/desktop/src/main/ipc.ts"
click node_agent_client "https://github.com/kashiwagieri233/palette/blob/main/desktop/src/main/agent-client.ts"
click node_service "https://github.com/kashiwagieri233/palette/blob/main/src/palette/service.py"
click node_policy "https://github.com/kashiwagieri233/palette/blob/main/src/palette/policy.py"
click node_control "https://github.com/kashiwagieri233/palette/blob/main/src/palette/control.py"
click node_controller "https://github.com/kashiwagieri233/palette/blob/main/src/palette/input/controller.py"
click node_audit "https://github.com/kashiwagieri233/palette/blob/main/src/palette/audit.py"
click node_manager "https://github.com/kashiwagieri233/palette/blob/main/src/palette/vm/manager.py"
click node_persistent "https://github.com/kashiwagieri233/palette/blob/main/src/palette/persistent_storage.py"
click node_images "https://github.com/kashiwagieri233/palette/blob/main/src/palette/vm/images.py"
click node_launcher "https://github.com/kashiwagieri233/palette/blob/main/src/palette/vm/launcher.py"
click node_qmp "https://github.com/kashiwagieri233/palette/blob/main/src/palette/qmp/client.py"
click node_guest_bridge "https://github.com/kashiwagieri233/palette/blob/main/src/palette/guest_tools/bridge.py"
click node_guest_tools "https://github.com/kashiwagieri233/palette/blob/main/src/palette/guest_tools/base.py"
click node_windows_guest "https://github.com/kashiwagieri233/palette/blob/main/guest/windows/Palette.Operations.cs"
click node_rfb "https://github.com/kashiwagieri233/palette/blob/main/desktop/src/renderer/Console.tsx"

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_desktop_ui,node_agent_client,node_rfb toneBlue
class node_mcp,node_operator_server,node_desktop_ipc,node_service toneAmber
class node_policy,node_control,node_controller,node_audit toneMint
class node_manager,node_persistent,node_images,node_launcher,node_qmp toneRose
class node_guest_bridge,node_guest_tools,node_windows_guest,node_agent,node_desktop,node_operator toneIndigo
```

## Components

### Clients

- [Desktop workbench](https://github.com/kashiwagieri233/palette/blob/main/desktop/src/renderer/App.tsx): `desktop/src/renderer/App.tsx`
- [Built-in agent](https://github.com/kashiwagieri233/palette/blob/main/desktop/src/main/agent-client.ts): `desktop/src/main/agent-client.ts`
- [Live screen console](https://github.com/kashiwagieri233/palette/blob/main/desktop/src/renderer/Console.tsx): `desktop/src/renderer/Console.tsx`

### Service interfaces

- [MCP server](https://github.com/kashiwagieri233/palette/blob/main/src/palette/server.py): `src/palette/server.py`
- [Operator IPC](https://github.com/kashiwagieri233/palette/blob/main/src/palette/operator/server.py): `src/palette/operator/server.py`
- [Desktop IPC](https://github.com/kashiwagieri233/palette/blob/main/desktop/src/main/ipc.ts): `desktop/src/main/ipc.ts`
- [Palette service](https://github.com/kashiwagieri233/palette/blob/main/src/palette/service.py): `src/palette/service.py`

### Policy and control

- [Authorization](https://github.com/kashiwagieri233/palette/blob/main/src/palette/policy.py): `src/palette/policy.py`
- [Control lease](https://github.com/kashiwagieri233/palette/blob/main/src/palette/control.py): `src/palette/control.py`
- [Action scheduler](https://github.com/kashiwagieri233/palette/blob/main/src/palette/input/controller.py): `src/palette/input/controller.py`
- [Metadata audit](https://github.com/kashiwagieri233/palette/blob/main/src/palette/audit.py): `src/palette/audit.py`

### VM runtime

- [VM lifecycle](https://github.com/kashiwagieri233/palette/blob/main/src/palette/vm/manager.py): `src/palette/vm/manager.py`
- [Persistent VM storage](https://github.com/kashiwagieri233/palette/blob/main/src/palette/persistent_storage.py): `src/palette/persistent_storage.py`
- [Image manager](https://github.com/kashiwagieri233/palette/blob/main/src/palette/vm/images.py): `src/palette/vm/images.py`
- [QEMU launcher](https://github.com/kashiwagieri233/palette/blob/main/src/palette/vm/launcher.py): `src/palette/vm/launcher.py`
- [QMP client](https://github.com/kashiwagieri233/palette/blob/main/src/palette/qmp/client.py): `src/palette/qmp/client.py`

### Guest integrations

- [Guest tool bridge](https://github.com/kashiwagieri233/palette/blob/main/src/palette/guest_tools/bridge.py): `src/palette/guest_tools/bridge.py`
- [Guest tool contract](https://github.com/kashiwagieri233/palette/blob/main/src/palette/guest_tools/base.py): `src/palette/guest_tools/base.py`
- [Windows enhancements](https://github.com/kashiwagieri233/palette/blob/main/guest/windows/Palette.Operations.cs): `guest/windows/Palette.Operations.cs`

### Other components

- **MCP agent**
- **Palette Desktop**
- **Operator CLI**

## Connections

- MCP agent → MCP server: uses MCP (evidence: `README.md`)
- MCP server → Palette service: dispatches tools (evidence: `src/palette/server.py`)
- Palette Desktop → Desktop workbench: operates workbench (evidence: `README.md`)
- Desktop workbench → Desktop IPC: requests runtime
- Desktop IPC → Operator IPC: uses local IPC (evidence: `README.md`)
- Operator CLI → Operator IPC: uses local IPC (evidence: `README.md`)
- Operator IPC → Palette service: dispatches commands (evidence: `src/palette/operator/server.py`)
- Desktop workbench → Live screen console: views live screen (evidence: `README.md`)
- Desktop workbench → Control lease: requests takeover (evidence: `README.md`)
- MCP agent → Built-in agent: prompts built-in agent
- Built-in agent → Desktop IPC: invokes agent API (evidence: `desktop/src/main/agent-client.ts`)
- Palette service → Authorization: authorizes requests (evidence: `src/palette/service.py`)
- Palette service → VM lifecycle: dispatches VM operations (evidence: `src/palette/service.py`)
- Palette service → Action scheduler: schedules actions (evidence: `src/palette/service.py`)
- Palette service → Metadata audit: records events (evidence: `src/palette/service.py`)
- Palette service → Control lease: checks ownership (evidence: `src/palette/service.py`)
- Action scheduler → QMP client: sends input (evidence: `src/palette/input/controller.py`)
- VM lifecycle → QEMU launcher: starts instances (evidence: `src/palette/vm/manager.py`)
- QEMU launcher → QMP client: opens management channel
- VM lifecycle → Guest tool bridge: manages guest tools (evidence: `src/palette/vm/manager.py`)
- Guest tool bridge → Guest tool contract: implements contract
- Guest tool bridge → Windows enhancements: exposes guest operations (evidence: `README.md`)
- VM lifecycle → Persistent VM storage: manages disk state (evidence: `src/palette/persistent_storage.py`)
- Persistent VM storage → Image manager: inspects images (evidence: `src/palette/persistent_storage.py`)
- Image manager → QEMU launcher: supplies image paths (evidence: `src/palette/vm/images.py`)
