# nezhahq/agent architecture

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

- Interactive diagram: https://gitdiagram.com/nezhahq/agent
- Repository: https://github.com/nezhahq/agent

## Overview

Nezha Agent is a host-monitoring agent that connects to the Nezha service, reports host state, and handles server-directed tasks. Its principal workflow is startup/configuration, remote connection, periodic state reporting, and task execution; task capabilities include file operations, terminal access, NAT forwarding, and monitoring. The excerpts show parts of this flow, but not the task dispatcher or several session implementations, so their detailed links are omitted or marked unverified. The source index and README provide only limited product documentation.

Main entry points: [`cmd/agent/main.go`](https://github.com/nezhahq/agent/blob/main/cmd/agent/main.go) (Agent entry), [`cmd/agent/task_dispatch.go`](https://github.com/nezhahq/agent/blob/main/cmd/agent/task_dispatch.go) (Task dispatch), [`pkg/monitor/state.go`](https://github.com/nezhahq/agent/blob/main/pkg/monitor/state.go) (State collection), [`cmd/agent/connection_session.go`](https://github.com/nezhahq/agent/blob/main/cmd/agent/connection_session.go) (Connection session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_entry["Agent entry<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_connection["Connection session"]
  node_dispatch["Task dispatch<br/>[task_dispatch.go]"]
  node_model["Host and task models<br/>[host.go]"]
  node_proto["Service protocol<br/>[nezha.proto]"]
end

subgraph group_monitoring["Host monitoring"]
  node_report["State reporting"]
  node_monitor["State collection<br/>[state.go]"]
  node_inventory["Host inventory<br/>[host.go]"]
  node_gpu["GPU metrics<br/>[gpu_darwin.go]"]
  node_ip["IP discovery<br/>[myip.go]"]
end

subgraph group_tasks["Remote tasks"]
  node_mcp["MCP handlers<br/>[mcp_handlers.go]"]
  node_terminal["Terminal session"]
  node_nat["NAT session<br/>[nat_session.go]"]
  node_process["Process tasks<br/>[mcp_exec.go]"]
  node_pty["PTY support<br/>[pty.go]"]
end

subgraph group_filesystem["File operations"]
  node_fm["File transfer tasks<br/>[tasks.go]"]
  node_fmops["Transfer operations<br/>[operations.go]"]
  node_hostfs["Anchored filesystem<br/>[anchor.go]"]
end

node_operator(("Operator"))
node_service(("Nezha service"))

node_operator -->|"configures"| node_entry
node_entry -->|"loads"| node_config
node_entry -.->|"opens"| node_connection
node_connection -.->|"connects"| node_service
node_entry -->|"starts"| node_report
node_report -.->|"reports"| node_monitor
node_entry -->|"starts"| node_dispatch
node_dispatch -.->|"routes"| node_mcp
node_dispatch -.->|"routes"| node_terminal
node_dispatch -.->|"routes"| node_nat
node_dispatch -.->|"routes"| node_process
node_mcp -.->|"uses"| node_hostfs
node_fm -->|"dispatches"| node_fmops
node_terminal -->|"starts"| node_pty
node_monitor -.->|"produces state"| node_model
node_monitor -.->|"collects"| node_gpu
node_monitor -.->|"discovers IP"| node_ip
node_monitor -.->|"collects host"| node_inventory
node_model -->|"encodes"| node_proto
node_connection -.->|"streams"| node_proto

click node_entry "https://github.com/nezhahq/agent/blob/main/cmd/agent/main.go"
click node_config "https://github.com/nezhahq/agent/blob/main/model/config.go"
click node_connection "https://github.com/nezhahq/agent/blob/main/cmd/agent/connection_session.go"
click node_dispatch "https://github.com/nezhahq/agent/blob/main/cmd/agent/task_dispatch.go"
click node_report "https://github.com/nezhahq/agent/blob/main/cmd/agent/report_state_session.go"
click node_monitor "https://github.com/nezhahq/agent/blob/main/pkg/monitor/state.go"
click node_inventory "https://github.com/nezhahq/agent/blob/main/pkg/monitor/host.go"
click node_gpu "https://github.com/nezhahq/agent/blob/main/pkg/monitor/gpu/gpu_darwin.go"
click node_ip "https://github.com/nezhahq/agent/blob/main/pkg/monitor/myip.go"
click node_mcp "https://github.com/nezhahq/agent/blob/main/cmd/agent/mcp_handlers.go"
click node_terminal "https://github.com/nezhahq/agent/blob/main/cmd/agent/terminal_session.go"
click node_nat "https://github.com/nezhahq/agent/blob/main/cmd/agent/nat_session.go"
click node_process "https://github.com/nezhahq/agent/blob/main/cmd/agent/mcp_exec.go"
click node_fm "https://github.com/nezhahq/agent/blob/main/pkg/fm/tasks.go"
click node_fmops "https://github.com/nezhahq/agent/blob/main/pkg/fm/operations.go"
click node_hostfs "https://github.com/nezhahq/agent/blob/main/pkg/hostfs/anchor.go"
click node_pty "https://github.com/nezhahq/agent/blob/main/pkg/pty/pty.go"
click node_model "https://github.com/nezhahq/agent/blob/main/model/host.go"
click node_proto "https://github.com/nezhahq/agent/blob/main/proto/nezha.proto"

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_entry,node_config,node_connection,node_dispatch,node_model,node_proto toneBlue
class node_report,node_monitor,node_inventory,node_gpu,node_ip toneAmber
class node_mcp,node_terminal,node_nat,node_process,node_pty toneMint
class node_fm,node_fmops,node_hostfs toneRose
class node_operator,node_service toneIndigo
```

## Components

### Agent runtime

- [Agent entry](https://github.com/nezhahq/agent/blob/main/cmd/agent/main.go): `cmd/agent/main.go`
- [Configuration](https://github.com/nezhahq/agent/blob/main/model/config.go): `model/config.go`
- [Connection session](https://github.com/nezhahq/agent/blob/main/cmd/agent/connection_session.go): `cmd/agent/connection_session.go`
- [Task dispatch](https://github.com/nezhahq/agent/blob/main/cmd/agent/task_dispatch.go): `cmd/agent/task_dispatch.go`
- [Host and task models](https://github.com/nezhahq/agent/blob/main/model/host.go): `model/host.go`
- [Service protocol](https://github.com/nezhahq/agent/blob/main/proto/nezha.proto): `proto/nezha.proto`

### Host monitoring

- [State reporting](https://github.com/nezhahq/agent/blob/main/cmd/agent/report_state_session.go): `cmd/agent/report_state_session.go`
- [State collection](https://github.com/nezhahq/agent/blob/main/pkg/monitor/state.go): `pkg/monitor/state.go`
- [Host inventory](https://github.com/nezhahq/agent/blob/main/pkg/monitor/host.go): `pkg/monitor/host.go`
- [GPU metrics](https://github.com/nezhahq/agent/blob/main/pkg/monitor/gpu/gpu_darwin.go): `pkg/monitor/gpu/gpu_darwin.go`
- [IP discovery](https://github.com/nezhahq/agent/blob/main/pkg/monitor/myip.go): `pkg/monitor/myip.go`

### Remote tasks

- [MCP handlers](https://github.com/nezhahq/agent/blob/main/cmd/agent/mcp_handlers.go): `cmd/agent/mcp_handlers.go`
- [Terminal session](https://github.com/nezhahq/agent/blob/main/cmd/agent/terminal_session.go): `cmd/agent/terminal_session.go`
- [NAT session](https://github.com/nezhahq/agent/blob/main/cmd/agent/nat_session.go): `cmd/agent/nat_session.go`
- [Process tasks](https://github.com/nezhahq/agent/blob/main/cmd/agent/mcp_exec.go): `cmd/agent/mcp_exec.go`
- [PTY support](https://github.com/nezhahq/agent/blob/main/pkg/pty/pty.go): `pkg/pty/pty.go`

### File operations

- [File transfer tasks](https://github.com/nezhahq/agent/blob/main/pkg/fm/tasks.go): `pkg/fm/tasks.go`
- [Transfer operations](https://github.com/nezhahq/agent/blob/main/pkg/fm/operations.go): `pkg/fm/operations.go`
- [Anchored filesystem](https://github.com/nezhahq/agent/blob/main/pkg/hostfs/anchor.go): `pkg/hostfs/anchor.go`

### Other components

- **Operator**
- **Nezha service**

## Connections

- Operator → Agent entry: configures (evidence: `cmd/agent/main.go`)
- Agent entry → Configuration: loads (evidence: `cmd/agent/main.go`)
- Agent entry → Connection session: opens
- Connection session → Nezha service: connects
- Agent entry → State reporting: starts (evidence: `cmd/agent/main.go`)
- State reporting → State collection: reports
- Agent entry → Task dispatch: starts (evidence: `cmd/agent/main.go`)
- Task dispatch → MCP handlers: routes
- Task dispatch → Terminal session: routes
- Task dispatch → NAT session: routes
- Task dispatch → Process tasks: routes
- MCP handlers → Anchored filesystem: uses
- File transfer tasks → Transfer operations: dispatches (evidence: `pkg/fm/tasks.go`)
- Terminal session → PTY support: starts (evidence: `cmd/agent/terminal_session.go`)
- State collection → Host and task models: produces state
- State collection → GPU metrics: collects
- State collection → IP discovery: discovers IP
- State collection → Host inventory: collects host
- Host and task models → Service protocol: encodes (evidence: `model/host.go`)
- Connection session → Service protocol: streams
