# pithings/unkernel architecture

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

- Interactive diagram: https://gitdiagram.com/pithings/unkernel
- Repository: https://github.com/pithings/unkernel

## Overview

unkernel runs a real Linux kernel compiled to WebAssembly, with a TypeScript host runtime for booting and connecting guest services. The main workflows are starting a guest through the CLI or browser, then interacting with its shell, storage, network, and devices. The browser adds a multi-window terminal UI and persistent-disk experience; the SDK also supports Node, browser workers, and host integrations. Some subsystem links below follow explicit README descriptions or SOURCE INDEX references; unsampled implementation details are not inferred as call sequences.

Main entry points: [`js/core/instance.ts`](https://github.com/pithings/unkernel/blob/main/js/core/instance.ts) (Guest instance), [`js/core/kernel.ts`](https://github.com/pithings/unkernel/blob/main/js/core/kernel.ts) (Kernel runtime), [`js/core/worker-serve.ts`](https://github.com/pithings/unkernel/blob/main/js/core/worker-serve.ts) (Worker runtime), [`js/core/worker-host.ts`](https://github.com/pithings/unkernel/blob/main/js/core/worker-host.ts) (Worker host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Kernel host runtime"]
  node_instance["Guest instance<br/>[instance.ts]"]
  node_kernel["Kernel runtime<br/>[kernel.ts]"]
  node_loader["Kernel loader<br/>[load.ts]"]
  node_devices["Device builder<br/>[devices.ts]"]
  node_block[("Block storage<br/>[block.ts]")]
  node_network["Guest networking<br/>[net.ts]"]
  node_mounts["Host mounts<br/>[mounts.ts]"]
  node_terminal["Terminal sessions<br/>[tty.ts]"]
  node_vsock["Vsock streams<br/>[vsock.ts]"]
  node_shared_mem["Shared memory<br/>[shm.ts]"]
  node_snapshot["Snapshots<br/>[snapshot.ts]"]
  node_display["Framebuffer display<br/>[display.ts]"]
  node_input["Input devices<br/>[input.ts]"]
  node_sound["Audio output<br/>[sound.ts]"]
end

subgraph group_platform["Host platforms"]
  node_worker_host["Worker host<br/>[worker-host.ts]"]
  node_worker_serve["Worker runtime<br/>[worker-serve.ts]"]
  node_worker_protocol["Worker protocol<br/>[worker-protocol.ts]"]
  node_worker_shared["Shared transport<br/>[worker-shared.ts]"]
  node_node_platform["Node platform<br/>[platform.ts]"]
  node_web_platform["Web platform<br/>[worker.ts]"]
end

subgraph group_browser["Browser experience"]
  node_browser_app["Browser app<br/>[App.tsx]"]
  node_web_boot["Browser boot<br/>[boot.ts]"]
  node_web_sdk["Web SDK entry<br/>[kw.ts]"]
  node_web_ui["Terminal UI<br/>[ui.ts]"]
  node_web_store["Browser state<br/>[store.ts]"]
end

subgraph group_entry["Ways to launch"]
  node_cli["CLI<br/>[cli.ts]"]
end

node_user(("User"))

node_user -->|"runs"| node_cli
node_user -->|"opens"| node_browser_app
node_cli -->|"starts guest"| node_instance
node_browser_app -->|"renders"| node_web_ui
node_browser_app -->|"reads state"| node_web_store
node_web_boot -.->|"boots through"| node_web_sdk
node_web_sdk -.->|"starts guest"| node_instance
node_web_ui -->|"updates"| node_web_store
node_instance -->|"loads kernel"| node_loader
node_instance -->|"creates runtime"| node_kernel
node_instance -->|"builds devices"| node_devices
node_instance -->|"configures mounts"| node_mounts
node_kernel -->|"uses storage"| node_block
node_devices -->|"builds disks"| node_block
node_devices -->|"builds network"| node_network
node_instance -->|"provides sessions"| node_terminal
node_instance -->|"provides streams"| node_vsock
node_kernel -->|"uses shared memory"| node_shared_mem
node_kernel -->|"uses snapshots"| node_snapshot
node_kernel -->|"uses display"| node_display
node_kernel -->|"uses input"| node_input
node_kernel -->|"uses sound"| node_sound
node_worker_host -->|"exchanges messages"| node_worker_protocol
node_worker_serve -->|"serves messages"| node_worker_protocol
node_worker_serve -->|"creates runtime"| node_instance
node_worker_host -->|"uses shared transport"| node_worker_shared
node_worker_host -.->|"starts worker"| node_worker_serve
node_node_platform -->|"runs worker entry"| node_worker_serve
node_web_platform -->|"runs worker entry"| node_worker_serve
node_instance -.->|"can delegate"| node_worker_host

click node_cli "https://github.com/pithings/unkernel/blob/main/js/cli.ts"
click node_browser_app "https://github.com/pithings/unkernel/blob/main/web/src/components/App.tsx"
click node_web_boot "https://github.com/pithings/unkernel/blob/main/web/src/boot.ts"
click node_web_sdk "https://github.com/pithings/unkernel/blob/main/web/src/kw.ts"
click node_web_ui "https://github.com/pithings/unkernel/blob/main/web/src/ui.ts"
click node_web_store "https://github.com/pithings/unkernel/blob/main/web/src/store.ts"
click node_instance "https://github.com/pithings/unkernel/blob/main/js/core/instance.ts"
click node_kernel "https://github.com/pithings/unkernel/blob/main/js/core/kernel.ts"
click node_loader "https://github.com/pithings/unkernel/blob/main/js/core/load.ts"
click node_devices "https://github.com/pithings/unkernel/blob/main/js/core/devices.ts"
click node_block "https://github.com/pithings/unkernel/blob/main/js/core/block.ts"
click node_network "https://github.com/pithings/unkernel/blob/main/js/core/net.ts"
click node_mounts "https://github.com/pithings/unkernel/blob/main/js/core/mounts.ts"
click node_terminal "https://github.com/pithings/unkernel/blob/main/js/core/tty.ts"
click node_vsock "https://github.com/pithings/unkernel/blob/main/js/core/vsock.ts"
click node_shared_mem "https://github.com/pithings/unkernel/blob/main/js/core/shm.ts"
click node_snapshot "https://github.com/pithings/unkernel/blob/main/js/core/snapshot.ts"
click node_display "https://github.com/pithings/unkernel/blob/main/js/core/display.ts"
click node_input "https://github.com/pithings/unkernel/blob/main/js/core/input.ts"
click node_sound "https://github.com/pithings/unkernel/blob/main/js/core/sound.ts"
click node_worker_host "https://github.com/pithings/unkernel/blob/main/js/core/worker-host.ts"
click node_worker_serve "https://github.com/pithings/unkernel/blob/main/js/core/worker-serve.ts"
click node_worker_protocol "https://github.com/pithings/unkernel/blob/main/js/core/worker-protocol.ts"
click node_worker_shared "https://github.com/pithings/unkernel/blob/main/js/core/worker-shared.ts"
click node_node_platform "https://github.com/pithings/unkernel/blob/main/js/node/platform.ts"
click node_web_platform "https://github.com/pithings/unkernel/blob/main/js/web/worker.ts"

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_instance,node_kernel,node_loader,node_devices,node_block,node_network,node_mounts,node_terminal,node_vsock,node_shared_mem,node_snapshot,node_display,node_input,node_sound,node_user toneBlue
class node_worker_host,node_worker_serve,node_worker_protocol,node_worker_shared,node_node_platform,node_web_platform toneAmber
class node_browser_app,node_web_boot,node_web_sdk,node_web_ui,node_web_store toneMint
class node_cli toneRose
```

## Components

### Kernel host runtime

- [Guest instance](https://github.com/pithings/unkernel/blob/main/js/core/instance.ts): `js/core/instance.ts`
- [Kernel runtime](https://github.com/pithings/unkernel/blob/main/js/core/kernel.ts): `js/core/kernel.ts`
- [Kernel loader](https://github.com/pithings/unkernel/blob/main/js/core/load.ts): `js/core/load.ts`
- [Device builder](https://github.com/pithings/unkernel/blob/main/js/core/devices.ts): `js/core/devices.ts`
- [Block storage](https://github.com/pithings/unkernel/blob/main/js/core/block.ts): `js/core/block.ts`
- [Guest networking](https://github.com/pithings/unkernel/blob/main/js/core/net.ts): `js/core/net.ts`
- [Host mounts](https://github.com/pithings/unkernel/blob/main/js/core/mounts.ts): `js/core/mounts.ts`
- [Terminal sessions](https://github.com/pithings/unkernel/blob/main/js/core/tty.ts): `js/core/tty.ts`
- [Vsock streams](https://github.com/pithings/unkernel/blob/main/js/core/vsock.ts): `js/core/vsock.ts`
- [Shared memory](https://github.com/pithings/unkernel/blob/main/js/core/shm.ts): `js/core/shm.ts`
- [Snapshots](https://github.com/pithings/unkernel/blob/main/js/core/snapshot.ts): `js/core/snapshot.ts`
- [Framebuffer display](https://github.com/pithings/unkernel/blob/main/js/core/display.ts): `js/core/display.ts`
- [Input devices](https://github.com/pithings/unkernel/blob/main/js/core/input.ts): `js/core/input.ts`
- [Audio output](https://github.com/pithings/unkernel/blob/main/js/core/sound.ts): `js/core/sound.ts`

### Host platforms

- [Worker host](https://github.com/pithings/unkernel/blob/main/js/core/worker-host.ts): `js/core/worker-host.ts`
- [Worker runtime](https://github.com/pithings/unkernel/blob/main/js/core/worker-serve.ts): `js/core/worker-serve.ts`
- [Worker protocol](https://github.com/pithings/unkernel/blob/main/js/core/worker-protocol.ts): `js/core/worker-protocol.ts`
- [Shared transport](https://github.com/pithings/unkernel/blob/main/js/core/worker-shared.ts): `js/core/worker-shared.ts`
- [Node platform](https://github.com/pithings/unkernel/blob/main/js/node/platform.ts): `js/node/platform.ts`
- [Web platform](https://github.com/pithings/unkernel/blob/main/js/web/worker.ts): `js/web/worker.ts`

### Browser experience

- [Browser app](https://github.com/pithings/unkernel/blob/main/web/src/components/App.tsx): `web/src/components/App.tsx`
- [Browser boot](https://github.com/pithings/unkernel/blob/main/web/src/boot.ts): `web/src/boot.ts`
- [Web SDK entry](https://github.com/pithings/unkernel/blob/main/web/src/kw.ts): `web/src/kw.ts`
- [Terminal UI](https://github.com/pithings/unkernel/blob/main/web/src/ui.ts): `web/src/ui.ts`
- [Browser state](https://github.com/pithings/unkernel/blob/main/web/src/store.ts): `web/src/store.ts`

### Ways to launch

- [CLI](https://github.com/pithings/unkernel/blob/main/js/cli.ts): `js/cli.ts`

### Other components

- **User**

## Connections

- User → CLI: runs
- User → Browser app: opens
- CLI → Guest instance: starts guest (evidence: `js/cli.ts`)
- Browser app → Terminal UI: renders (evidence: `web/src/components/App.tsx`)
- Browser app → Browser state: reads state (evidence: `web/src/components/App.tsx`)
- Browser boot → Web SDK entry: boots through
- Web SDK entry → Guest instance: starts guest
- Terminal UI → Browser state: updates (evidence: `web/src/ui.ts`)
- Guest instance → Kernel loader: loads kernel (evidence: `js/core/instance.ts`)
- Guest instance → Kernel runtime: creates runtime (evidence: `js/core/instance.ts`)
- Guest instance → Device builder: builds devices (evidence: `js/core/instance.ts`)
- Guest instance → Host mounts: configures mounts (evidence: `js/core/instance.ts`)
- Kernel runtime → Block storage: uses storage (evidence: `js/core/kernel.ts`)
- Device builder → Block storage: builds disks (evidence: `js/core/devices.ts`)
- Device builder → Guest networking: builds network (evidence: `js/core/devices.ts`)
- Guest instance → Terminal sessions: provides sessions (evidence: `js/core/instance.ts`)
- Guest instance → Vsock streams: provides streams (evidence: `js/core/instance.ts`)
- Kernel runtime → Shared memory: uses shared memory (evidence: `js/core/kernel.ts`)
- Kernel runtime → Snapshots: uses snapshots (evidence: `js/core/kernel.ts`)
- Kernel runtime → Framebuffer display: uses display (evidence: `js/core/kernel.ts`)
- Kernel runtime → Input devices: uses input (evidence: `js/core/kernel.ts`)
- Kernel runtime → Audio output: uses sound (evidence: `js/core/kernel.ts`)
- Worker host → Worker protocol: exchanges messages (evidence: `js/core/worker-host.ts`)
- Worker runtime → Worker protocol: serves messages (evidence: `js/core/worker-serve.ts`)
- Worker runtime → Guest instance: creates runtime (evidence: `js/core/worker-serve.ts`)
- Worker host → Shared transport: uses shared transport (evidence: `js/core/worker-host.ts`)
- Worker host → Worker runtime: starts worker
- Node platform → Worker runtime: runs worker entry (evidence: `js/node/worker-entry.ts`)
- Web platform → Worker runtime: runs worker entry
- Guest instance → Worker host: can delegate (evidence: `js/core/instance.ts`)
