# jarvisoslinux/jarvisos architecture

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

- Interactive diagram: https://gitdiagram.com/jarvisoslinux/jarvisos
- Repository: https://github.com/jarvisoslinux/jarvisos

## Overview

JARVIS OS is an AI-integrated Linux distribution. Its principal interaction is user voice or text input, agent planning with an LLM, policy/confirmation, and command execution; a separate wake listener can launch the chat terminal. The tree contains the agent and approval checker, but not the cloned kernel source or the larger daemon described in the README, so kernel capabilities are represented only at the available package path. Build and ISO scripts are omitted. Edges reflect the shown agent calls and documented capabilities; unsampled runtime wiring is not inferred.

Main entry points: [`packages/linux-jarvisos`](https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos) (JARVIS kernel package), [`jarvis_agent.py`](https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis_agent.py) (Agent runtime), [`packages/jarvis-approvers/jarvis_approval.py`](https://github.com/jarvisoslinux/jarvisos/blob/main/packages/jarvis-approvers/jarvis_approval.py) (Approval verifier), [`jarvis-wake.py`](https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis-wake.py) (Wake listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_wake["Wake listener<br/>[jarvis-wake.py]"]
  node_terminal["Chat terminal"]
end

subgraph group_agent["Agent runtime"]
  node_agent["Agent runtime<br/>[jarvis_agent.py]"]
  node_execution["Command execution<br/>[jarvis_agent.py]"]
end

subgraph group_security["Authorization"]
  node_approval["Approval verifier<br/>[jarvis_approval.py]"]
  node_approval_state[("Approval state<br/>[jarvis_approval.py]")]
  node_polkit["Polkit rules"]
end

subgraph group_os["OS platform"]
  node_kernel["JARVIS kernel package"]
  node_jarvis_device["/dev/jarvis"]
  node_sysmon["System metrics"]
  node_kernel_policy["Kernel policy engine"]
  node_kernel_keys[("Kernel key storage")]
  node_dibs["DIBS buffers"]
end

node_user(("User"))
node_llm["Local LLM service"]

node_user -->|"gives text"| node_agent
node_wake -->|"opens terminal"| node_terminal
node_terminal -->|"launches chat"| node_agent
node_agent -->|"requests plan"| node_llm
node_agent -->|"executes commands"| node_execution
node_polkit -->|"runs checker"| node_approval
node_approval -->|"spends nonce"| node_approval_state
node_kernel -->|"provides device"| node_jarvis_device
node_kernel -->|"provides metrics"| node_sysmon
node_kernel -->|"provides policy"| node_kernel_policy
node_kernel -->|"provides keyring"| node_kernel_keys
node_kernel -->|"provides buffers"| node_dibs

click node_wake "https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis-wake.py"
click node_agent "https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis_agent.py"
click node_execution "https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis_agent.py"
click node_approval "https://github.com/jarvisoslinux/jarvisos/blob/main/packages/jarvis-approvers/jarvis_approval.py"
click node_approval_state "https://github.com/jarvisoslinux/jarvisos/blob/main/packages/jarvis-approvers/jarvis_approval.py"
click node_polkit "https://github.com/jarvisoslinux/jarvisos/tree/main/packages/polkit"
click node_kernel "https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos"
click node_sysmon "https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos"
click node_kernel_policy "https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos"
click node_kernel_keys "https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos"
click node_dibs "https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos"

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_wake,node_terminal,node_user toneBlue
class node_agent,node_execution toneAmber
class node_approval,node_approval_state,node_polkit toneMint
class node_kernel,node_jarvis_device,node_sysmon,node_kernel_policy,node_kernel_keys,node_dibs toneRose
class node_llm toneIndigo
```

## Components

### User interaction

- [Wake listener](https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis-wake.py): `jarvis-wake.py`
- **Chat terminal**

### Agent runtime

- [Agent runtime](https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis_agent.py): `jarvis_agent.py`
- [Command execution](https://github.com/jarvisoslinux/jarvisos/blob/main/jarvis_agent.py): `jarvis_agent.py`

### Authorization

- [Approval verifier](https://github.com/jarvisoslinux/jarvisos/blob/main/packages/jarvis-approvers/jarvis_approval.py): `packages/jarvis-approvers/jarvis_approval.py`
- [Approval state](https://github.com/jarvisoslinux/jarvisos/blob/main/packages/jarvis-approvers/jarvis_approval.py): `packages/jarvis-approvers/jarvis_approval.py`
- [Polkit rules](https://github.com/jarvisoslinux/jarvisos/tree/main/packages/polkit): `packages/polkit`

### OS platform

- [JARVIS kernel package](https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos): `packages/linux-jarvisos`
- **/dev/jarvis**
- [System metrics](https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos): `packages/linux-jarvisos`
- [Kernel policy engine](https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos): `packages/linux-jarvisos`
- [Kernel key storage](https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos): `packages/linux-jarvisos`
- [DIBS buffers](https://github.com/jarvisoslinux/jarvisos/tree/main/packages/linux-jarvisos): `packages/linux-jarvisos`

### Other components

- **User**
- **Local LLM service**

## Connections

- User → Agent runtime: gives text (evidence: `README.md`)
- Wake listener → Chat terminal: opens terminal (evidence: `jarvis-wake.py`)
- Chat terminal → Agent runtime: launches chat
- Agent runtime → Local LLM service: requests plan (evidence: `jarvis_agent.py`)
- Agent runtime → Command execution: executes commands (evidence: `jarvis_agent.py`)
- Polkit rules → Approval verifier: runs checker (evidence: `packages/jarvis-approvers/jarvis_approval.py`)
- Approval verifier → Approval state: spends nonce (evidence: `packages/jarvis-approvers/jarvis_approval.py`)
- JARVIS kernel package → /dev/jarvis: provides device (evidence: `README.md`)
- JARVIS kernel package → System metrics: provides metrics (evidence: `README.md`)
- JARVIS kernel package → Kernel policy engine: provides policy (evidence: `README.md`)
- JARVIS kernel package → Kernel key storage: provides keyring (evidence: `README.md`)
- JARVIS kernel package → DIBS buffers: provides buffers (evidence: `README.md`)
