How sancaaa/headnode works
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: http.go HTTP API · sessions.go Session relay · headnode-agent/main.go Agent runtime · headnode/main.go Server runtime
Components 20
Management clients
- Web dashboard
web/app.js - hnctl CLI
cmd/hnctl/main.go
Headnode server
- Server runtime
cmd/headnode/main.go - HTTP API
server/http.go - Authentication
server/auth.go - Host management
server/hosts.go - Agent enrollment
server/enroll.go - Session relay
server/sessions.go - File transfers
server/transfers.go - Uploads
server/upload.go - Downloads
server/download.go - SQLite store
server/db.go
Managed agent
- Agent runtime
cmd/headnode-agent/main.go - Reverse connection
agent/conn.go - File operations
agent/files.go - Remote shell
agent/shell_linux.go - TCP tunnels
agent/tunnel.go - VNC access
agent/vnc.go
Shared protocol
- Message contract
protocol/messages.go
Other components
- Operator
Connections 22
- Operator → Web dashboard: manages hosts
- Operator → hnctl CLI: forwards ports
- Web dashboard → HTTP API: uses dashboard API
- hnctl CLI → HTTP API: uses server API
cmd/hnctl/main.go - Server runtime → HTTP API: serves requests
cmd/headnode/main.go - Server runtime → SQLite store: opens database
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
server/sessions.go - Session relay → Agent runtime: dispatches open
server/sessions.go - Agent runtime → Reverse connection: runs connection
- Reverse connection → HTTP API: dials server
- Session relay → Message contract: sends session messages
server/sessions.go - Agent runtime → Message contract: exchanges messages
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