# sancaaa/headnode architecture

> Architecture diagram of the GitHub repository sancaaa/headnode, 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/sancaaa/headnode
- Repository: https://github.com/sancaaa/headnode

## Overview

headnode is a self-hosted remote-management system: an operator enrolls agents on managed hosts, then uses the web dashboard or hnctl to manage them through a server the agents dial out to. The documented workflow covers host administration and interactive shell, file management and transfers, and TCP forwarding; VNC is also represented in the protocol. The sampled code confirms session dispatch and server setup. Some capability-specific implementation files were not sampled, so those links are based on README documentation rather than inspected calls.

Main entry points: [`server/http.go`](https://github.com/sancaaa/headnode/blob/main/server/http.go) (HTTP API), [`server/sessions.go`](https://github.com/sancaaa/headnode/blob/main/server/sessions.go) (Session relay), [`cmd/headnode-agent/main.go`](https://github.com/sancaaa/headnode/blob/main/cmd/headnode-agent/main.go) (Agent runtime), [`cmd/headnode/main.go`](https://github.com/sancaaa/headnode/blob/main/cmd/headnode/main.go) (Server runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Management clients"]
  node_dashboard["Web dashboard<br/>[app.js]"]
  node_hnctl["hnctl CLI<br/>[main.go]"]
end

subgraph group_server["Headnode server"]
  node_servercmd["Server runtime<br/>[main.go]"]
  node_httpapi["HTTP API<br/>[http.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_hosts["Host management<br/>[hosts.go]"]
  node_enrollment["Agent enrollment<br/>[enroll.go]"]
  node_sessions["Session relay<br/>[sessions.go]"]
  node_filetransfers["File transfers<br/>[transfers.go]"]
  node_upload["Uploads<br/>[upload.go]"]
  node_download["Downloads<br/>[download.go]"]
  node_database[("SQLite store<br/>[db.go]")]
end

subgraph group_agent["Managed agent"]
  node_agententry["Agent runtime<br/>[main.go]"]
  node_agentconnection["Reverse connection<br/>[conn.go]"]
  node_agentfiles["File operations<br/>[files.go]"]
  node_agentshell["Remote shell<br/>[shell_linux.go]"]
  node_agenttunnel["TCP tunnels<br/>[tunnel.go]"]
  node_agentvnc["VNC access<br/>[vnc.go]"]
end

subgraph group_shared["Shared protocol"]
  node_protocol["Message contract<br/>[messages.go]"]
end

node_operator(("Operator"))

node_operator -->|"manages hosts"| node_dashboard
node_operator -->|"forwards ports"| node_hnctl
node_dashboard -->|"uses dashboard API"| node_httpapi
node_hnctl -->|"uses server API"| node_httpapi
node_servercmd -->|"serves requests"| node_httpapi
node_servercmd -->|"opens database"| node_database
node_httpapi -->|"authenticates requests"| node_auth
node_httpapi -->|"manages hosts"| node_hosts
node_httpapi -->|"enrolls agents"| node_enrollment
node_httpapi -->|"opens sessions"| node_sessions
node_sessions -->|"dispatches open"| node_agententry
node_agententry -.->|"runs connection"| node_agentconnection
node_agentconnection -->|"dials server"| node_httpapi
node_sessions -->|"sends session messages"| node_protocol
node_agententry -->|"exchanges messages"| node_protocol
node_sessions -->|"relays shell sessions"| node_agentshell
node_sessions -->|"relays file sessions"| node_agentfiles
node_httpapi -->|"coordinates transfers"| node_filetransfers
node_httpapi -->|"accepts uploads"| node_upload
node_httpapi -->|"streams downloads"| node_download
node_sessions -->|"supports tunnels"| node_agenttunnel
node_sessions -->|"supports VNC access"| node_agentvnc

click node_dashboard "https://github.com/sancaaa/headnode/blob/main/web/app.js"
click node_hnctl "https://github.com/sancaaa/headnode/blob/main/cmd/hnctl/main.go"
click node_servercmd "https://github.com/sancaaa/headnode/blob/main/cmd/headnode/main.go"
click node_httpapi "https://github.com/sancaaa/headnode/blob/main/server/http.go"
click node_auth "https://github.com/sancaaa/headnode/blob/main/server/auth.go"
click node_hosts "https://github.com/sancaaa/headnode/blob/main/server/hosts.go"
click node_enrollment "https://github.com/sancaaa/headnode/blob/main/server/enroll.go"
click node_sessions "https://github.com/sancaaa/headnode/blob/main/server/sessions.go"
click node_filetransfers "https://github.com/sancaaa/headnode/blob/main/server/transfers.go"
click node_upload "https://github.com/sancaaa/headnode/blob/main/server/upload.go"
click node_download "https://github.com/sancaaa/headnode/blob/main/server/download.go"
click node_database "https://github.com/sancaaa/headnode/blob/main/server/db.go"
click node_agententry "https://github.com/sancaaa/headnode/blob/main/cmd/headnode-agent/main.go"
click node_agentconnection "https://github.com/sancaaa/headnode/blob/main/agent/conn.go"
click node_agentfiles "https://github.com/sancaaa/headnode/blob/main/agent/files.go"
click node_agentshell "https://github.com/sancaaa/headnode/blob/main/agent/shell_linux.go"
click node_agenttunnel "https://github.com/sancaaa/headnode/blob/main/agent/tunnel.go"
click node_agentvnc "https://github.com/sancaaa/headnode/blob/main/agent/vnc.go"
click node_protocol "https://github.com/sancaaa/headnode/blob/main/protocol/messages.go"

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_dashboard,node_hnctl toneBlue
class node_servercmd,node_httpapi,node_auth,node_hosts,node_enrollment,node_sessions,node_filetransfers,node_upload,node_download,node_database toneAmber
class node_agententry,node_agentconnection,node_agentfiles,node_agentshell,node_agenttunnel,node_agentvnc toneMint
class node_protocol toneRose
class node_operator toneIndigo
```

## Components

### Management clients

- [Web dashboard](https://github.com/sancaaa/headnode/blob/main/web/app.js): `web/app.js`
- [hnctl CLI](https://github.com/sancaaa/headnode/blob/main/cmd/hnctl/main.go): `cmd/hnctl/main.go`

### Headnode server

- [Server runtime](https://github.com/sancaaa/headnode/blob/main/cmd/headnode/main.go): `cmd/headnode/main.go`
- [HTTP API](https://github.com/sancaaa/headnode/blob/main/server/http.go): `server/http.go`
- [Authentication](https://github.com/sancaaa/headnode/blob/main/server/auth.go): `server/auth.go`
- [Host management](https://github.com/sancaaa/headnode/blob/main/server/hosts.go): `server/hosts.go`
- [Agent enrollment](https://github.com/sancaaa/headnode/blob/main/server/enroll.go): `server/enroll.go`
- [Session relay](https://github.com/sancaaa/headnode/blob/main/server/sessions.go): `server/sessions.go`
- [File transfers](https://github.com/sancaaa/headnode/blob/main/server/transfers.go): `server/transfers.go`
- [Uploads](https://github.com/sancaaa/headnode/blob/main/server/upload.go): `server/upload.go`
- [Downloads](https://github.com/sancaaa/headnode/blob/main/server/download.go): `server/download.go`
- [SQLite store](https://github.com/sancaaa/headnode/blob/main/server/db.go): `server/db.go`

### Managed agent

- [Agent runtime](https://github.com/sancaaa/headnode/blob/main/cmd/headnode-agent/main.go): `cmd/headnode-agent/main.go`
- [Reverse connection](https://github.com/sancaaa/headnode/blob/main/agent/conn.go): `agent/conn.go`
- [File operations](https://github.com/sancaaa/headnode/blob/main/agent/files.go): `agent/files.go`
- [Remote shell](https://github.com/sancaaa/headnode/blob/main/agent/shell_linux.go): `agent/shell_linux.go`
- [TCP tunnels](https://github.com/sancaaa/headnode/blob/main/agent/tunnel.go): `agent/tunnel.go`
- [VNC access](https://github.com/sancaaa/headnode/blob/main/agent/vnc.go): `agent/vnc.go`

### Shared protocol

- [Message contract](https://github.com/sancaaa/headnode/blob/main/protocol/messages.go): `protocol/messages.go`

### Other components

- **Operator**

## Connections

- Operator → Web dashboard: manages hosts
- Operator → hnctl CLI: forwards ports
- Web dashboard → HTTP API: uses dashboard API
- hnctl CLI → HTTP API: uses server API (evidence: `cmd/hnctl/main.go`)
- Server runtime → HTTP API: serves requests (evidence: `cmd/headnode/main.go`)
- Server runtime → SQLite store: opens database (evidence: `cmd/headnode/main.go`)
- HTTP API → Authentication: authenticates requests
- HTTP API → Host management: manages hosts
- HTTP API → Agent enrollment: enrolls agents
- HTTP API → Session relay: opens sessions (evidence: `server/sessions.go`)
- Session relay → Agent runtime: dispatches open (evidence: `server/sessions.go`)
- Agent runtime → Reverse connection: runs connection
- Reverse connection → HTTP API: dials server
- Session relay → Message contract: sends session messages (evidence: `server/sessions.go`)
- Agent runtime → Message contract: exchanges messages (evidence: `protocol/messages.go`)
- Session relay → Remote shell: relays shell sessions
- Session relay → File operations: relays file sessions
- HTTP API → File transfers: coordinates transfers
- HTTP API → Uploads: accepts uploads
- HTTP API → Downloads: streams downloads
- Session relay → TCP tunnels: supports tunnels
- Session relay → VNC access: supports VNC access
