Security Model, Network Ports & Prometheus Monitoring

1. Zero-Exposure Default Security Posture

1. Zero Open Ports in Single-Node Mode: Running ./hypercache -c configs/hypercache-agent.toml start without controller_url or --metrics opens zero TCP network ports. All communication between Python and the Rust daemon occurs over the local Unix Domain Socket (/run/hypercache/hypercache.sock).
2. Zero-Config Localhost Admin: Running ./hypercache-admin directly on the Controller host (127.0.0.1 / ::1) automatically bypasses token checks so operators can run ./hypercache-admin nodes or preload without flags.
3. Bearer Token Authentication for Cluster Traffic: When cluster_auth_token (or HYPERCACHE_AUTH_TOKEN) is set, all network requests between the Controller (:9120) and Worker Node Agents (:9115) - including heartbeats, preload directives, P2P chunk transfers, and k=2 checkpoint replication - require Authorization: Bearer <token>. Unauthorized requests are rejected with HTTP 401 Unauthorized.

Component / Service	Default Port / Socket	Default State	Who Should Have Access
Worker Local IPC	/run/hypercache/hypercache.sock	ON (Local file socket)	Local processes on the compute node
Prometheus Exporter	TCP :9110 (127.0.0.1)	OFF (Enable via --metrics)	Prometheus scraper / localhost
Worker Agent Fleet & P2P API	TCP :9115 (0.0.0.0)	OFF (Auto-enabled with controller_url)	Central Controller & peer GPU worker nodes (Private VPC)
Central Controller API	TCP :9120 (0.0.0.0)	ON when running hypercache-admin controller	GPU worker nodes & operator CLI (Private VPC)

---

2. Prometheus & Grafana Monitoring Stack

HyperCache includes a pre-configured Prometheus + Grafana observability stack in docker-compose.yml and configs/grafana/.

# 1. Start the worker daemon with Prometheus metrics enabled (:9110/metrics)
./hypercache -c configs/hypercache-agent.toml start --metrics

# 2. Launch the pre-provisioned Prometheus (:9090) and Grafana (:3000) dashboard stack
docker compose up -d

Exported Prometheus Metrics (http://<node-ip>:9110/metrics)

# Real-Time Hardware Throughput & Latency
hypercache_bandwidth_mbps
hypercache_local_metadata_latency_us
hypercache_remote_metadata_latency_us
hypercache_local_ttfb_us
hypercache_hit_ratio_percent

# Cloud Egress Savings & GPU Idle Time ROI
hypercache_estimated_cost_savings_dollars
hypercache_s3_egress_bytes_saved_total
hypercache_gpu_idle_time_saved_seconds

# Storage Pool & Cache Lifecycle
hypercache_active_devices_count
hypercache_storage_utilization_percent
hypercache_storage_used_bytes
hypercache_cached_objects_count
hypercache_evictions_total