Repository Public
1package protocol23import "time"45// Report is one telemetry batch (POST /agent/v1/report). Seq increases by one6// per report for the life of an agent identity; the server uses it to detect7// gaps and to discard duplicates replayed from the offline buffer.8type Report struct {9 V int `json:"v"`10 Seq int64 `json:"seq"`11 TS time.Time `json:"ts"` // agent clock, UTC12 AgentVersion string `json:"agent_version"`13 Buffered bool `json:"buffered,omitempty"` // replayed after a disconnection14 Samples []Sample `json:"samples"`15 Availability map[string]string `json:"availability,omitempty"` // metric name -> Avail*16 Processes []Process `json:"processes,omitempty"`17 Services *ServiceSet `json:"services,omitempty"`18 Inventory *Inventory `json:"inventory,omitempty"`19 Volumes []Volume `json:"volumes,omitempty"`20 Inference *InferenceSet `json:"inference,omitempty"`21 NAS []NASProbe `json:"nas,omitempty"`22 Capabilities []string `json:"capabilities,omitempty"` // command types allowed by local policy23}2425type Sample struct {26 M string `json:"m"` // metric name from Catalog27 L string `json:"l,omitempty"` // label28 V float64 `json:"v"`29}3031type Process struct {32 PID int32 `json:"pid"`33 Name string `json:"name"`34 User string `json:"user"`35 CPU float64 `json:"cpu"` // percent of one core36 RSS int64 `json:"rss"`37 Threads int32 `json:"threads,omitempty"`38 Started int64 `json:"started,omitempty"` // unix seconds39 // The command line is deliberately NOT collected: arguments routinely contain secrets.40}4142// ServiceSet is a complete observation by one or more managers. A manager43// listed in Managers but with no entry in Items has zero services; a manager44// absent from Managers was not observed (its services are left untouched).45type ServiceSet struct {46 Managers []string `json:"managers"`47 Items []Service `json:"items"`48}4950type Service struct {51 Manager string `json:"manager"` // pm2 | launchd | systemd | docker52 Name string `json:"name"`53 State string `json:"state"` // online | stopped | errored | unknown54 RawState string `json:"raw_state"` // manager's own word55 PID int32 `json:"pid,omitempty"`56 Restarts int32 `json:"restarts,omitempty"`57 MemBytes int64 `json:"mem_bytes,omitempty"`58 CPU float64 `json:"cpu,omitempty"`59 UptimeS int64 `json:"uptime_s,omitempty"`60 Version string `json:"version,omitempty"`61 Ports []int `json:"ports,omitempty"`62 Scope string `json:"scope,omitempty"` // launchd: user | system63}6465type Inventory struct {66 HardwareUUID string `json:"hardware_uuid"`67 Hostname string `json:"hostname"`68 Kind string `json:"kind"` // mac | linux69 Model string `json:"model"`70 Chip string `json:"chip"`71 Arch string `json:"arch"`72 CPUCores int `json:"cpu_cores"`73 CPULevels []CPULevel `json:"cpu_levels,omitempty"` // as named by the OS; no P/E assumption74 GPUCores int `json:"gpu_cores,omitempty"`75 GPUModel string `json:"gpu_model,omitempty"`76 MemBytes int64 `json:"mem_bytes"`77 StorageBytes int64 `json:"storage_bytes"`78 OSName string `json:"os_name"`79 OSVersion string `json:"os_version"`80 OSBuild string `json:"os_build"`81 Kernel string `json:"kernel"`82 BootTime time.Time `json:"boot_time"`83 Interfaces []Interface `json:"interfaces"`84 Managers []string `json:"managers"` // service managers detected85 Laptop bool `json:"laptop"`86}8788type CPULevel struct {89 Name string `json:"name"`90 Cores int `json:"cores"`91}9293type Interface struct {94 Name string `json:"name"`95 Kind string `json:"kind"` // ethernet | wifi | tunnel | other96 MAC string `json:"mac,omitempty"`97 Addrs []string `json:"addrs"`98 Media string `json:"media,omitempty"`99 Up bool `json:"up"`100 Default bool `json:"default,omitempty"`101}102103type Volume struct {104 Mount string `json:"mount"`105 Device string `json:"device"`106 FS string `json:"fs"`107 Kind string `json:"kind"` // internal | external | network108 Total int64 `json:"total"`109 Used int64 `json:"used"`110 SMART string `json:"smart,omitempty"` // verified | failing | "" when not observable111 Remote string `json:"remote,omitempty"` // network volumes: //host/share, credentials stripped112}113114type InferenceSet struct {115 Items []InferenceServer `json:"items"`116}117118type InferenceServer struct {119 Kind string `json:"kind"` // mlx_lm | ollama | llama.cpp120 Port int `json:"port"`121 Model string `json:"model,omitempty"`122 PID int32 `json:"pid"`123 RSS int64 `json:"rss"`124 UptimeS int64 `json:"uptime_s"`125 DiskBytes int64 `json:"disk_bytes,omitempty"`126 Health string `json:"health"` // ok | failing | unknown127 HealthMS float64 `json:"health_ms,omitempty"`128 ListedModels []string `json:"listed_models,omitempty"`129}130131type NASProbe struct {132 Host string `json:"host"`133 Reachable bool `json:"reachable"`134 LatencyMS float64 `json:"latency_ms,omitempty"`135 Mounted bool `json:"mounted"`136 Total int64 `json:"total,omitempty"`137 Used int64 `json:"used,omitempty"`138}139140// ReportAck is the server's answer to a report.141type ReportAck struct {142 Seq int64 `json:"seq"`143 ServerTime time.Time `json:"server_time"`144 // Directives the agent applies to itself (all optional).145 IntervalS int `json:"interval_s,omitempty"`146 WantInventory bool `json:"want_inventory,omitempty"`147 NASTargets []string `json:"nas_targets,omitempty"` // hosts to probe on TCP 445148 RenewCert bool `json:"renew_cert,omitempty"`149}150151// Enrollment.152type EnrollRequest struct {153 CSRPEM string `json:"csr_pem"`154 Inventory Inventory `json:"inventory"`155 AgentVersion string `json:"agent_version"`156}157158type EnrollResponse struct {159 AgentID string `json:"agent_id"`160 NodeID string `json:"node_id"`161 CertPEM string `json:"cert_pem"`162 CAPEM string `json:"ca_pem"`163 CommandKeys map[string]string `json:"command_keys"` // key id -> base64 Ed25519 public key164 Endpoints []string `json:"endpoints"`165 ServerName string `json:"server_name"`166 IntervalS int `json:"interval_s"`167}168169type RenewRequest struct {170 CSRPEM string `json:"csr_pem"`171}172173type RenewResponse struct {174 CertPEM string `json:"cert_pem"`175 CAPEM string `json:"ca_pem"`176 CommandKeys map[string]string `json:"command_keys"`177}178179// Command lifecycle messages (agent -> ingest).180type CommandAck struct {181 Accepted bool `json:"accepted"`182 Reason string `json:"reason,omitempty"` // verification or policy refusal183}184185type CommandOutput struct {186 Stream string `json:"stream"` // stdout | stderr | info187 Data string `json:"data"` // already redacted by the agent188}189190type CommandResult struct {191 Status string `json:"status"` // succeeded | failed | timed_out | cancelled192 ExitCode *int `json:"exit_code,omitempty"`193 Error string `json:"error,omitempty"`194 Result map[string]any `json:"result,omitempty"`195 Duration float64 `json:"duration_s"`196}197198// CommandsResponse is the long-poll answer; Cancel lists command ids the199// agent should stop cooperatively.200type CommandsResponse struct {201 Commands []SignedCommand `json:"commands"`202 Cancel []string `json:"cancel,omitempty"`203}204