guest_api.proto

// SPDX-FileCopyrightText: © 2024-2025 Phala Network <dstack@phala.network>
//
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

import "google/protobuf/empty.proto";

package guest_api;

// Identifies a running guest worker instance.
message Id {
  string id = 1;
}

// Static attestation and registration info reported by the guest agent.
message GuestInfo {
  // Guest software version
  string version = 1;
  // App ID
  bytes app_id = 2;
  // App Instance ID
  bytes instance_id = 3;
  // App certificate
  string app_cert = 4;
  // TCB info
  string tcb_info = 5;
  // Device ID
  bytes device_id = 6;
}

// IPv4/IPv6 address with prefix length.
message IpAddress {
  string address = 1;
  uint32 prefix = 2;
}

// Observability metrics for a single NIC inside the guest.
message Interface {
  string name = 1;
  repeated IpAddress addresses = 2;
  uint64 rx_bytes = 3;
  uint64 tx_bytes = 4;
  uint64 rx_errors = 5;
  uint64 tx_errors = 6;
}

// Default gateway entry advertised to the guest.
message Gateway {
  string address = 1;
}

// Complete networking snapshot including WireGuard info.
message NetworkInformation {
  repeated string dns_servers = 1;
  repeated Gateway gateways = 2;
  repeated Interface interfaces = 3;
  string wg_info = 4;
}

// Lists all containers currently scheduled in the guest.
message ListContainersResponse {
  repeated Container containers = 1;
}

// Docker-compatible view of an application container.
message Container {
  // The ID of this container
  string id = 1;
  // The names that this container has been given
  repeated string names = 2;
  // The name of the image used when creating this container
  string image = 3;
  // The ID of the image that this container was created from
  string image_id = 4;
  // When the container was created
  int64 created = 6;
  // The state of this container (e.g. Exited)
  string state = 7;
  // The status of this container (e.g. Exited)
  string status = 8;
}

// OS, kernel, and resource metrics for the guest worker.
message SystemInfo {
  // Operating system
  string os_name = 1;
  // Operating system version
  string os_version = 2;
  // Kernel version
  string kernel_version = 3;
  // Cpu model
  string cpu_model = 4;
  // Number of logical CPUs
  uint32 num_cpus = 5;
  // Total memory
  uint64 total_memory = 6;
  // Available memory
  uint64 available_memory = 7;
  // Used memory
  uint64 used_memory = 8;
  // Free memory
  uint64 free_memory = 9;
  // Total swap memory
  uint64 total_swap = 10;
  // Used swap memory
  uint64 used_swap = 11;
  // Free swap memory
  uint64 free_swap = 12;
  // Uptime
  uint64 uptime = 13;
  // Load average
  uint32 loadavg_one = 14;
  uint32 loadavg_five = 15;
  uint32 loadavg_fifteen = 16;
  // Disks
  repeated DiskInfo disks = 17;
}

// Disk usage metrics scoped per device or mount point.
message DiskInfo {
  // Device name
  string name = 1;
  // Mount point
  string mount_point = 2;
  // Total size
  uint64 total_size = 3;
  // Free size
  uint64 free_size = 5;
}

// One NVIDIA GPU sampled through NVML.
//
// Optional numeric fields are unset when that query failed, so a consumer can
// tell a genuine zero from a missing sample. `errors` lists the failed queries
// for this card, one entry each, so counting them does not mean re-parsing a
// joined string.
//
// `uuid` is the stable identity; `index` and `pci_bus_id` are ordinal/location
// helpers. `uuid` and `pci_bus_id` are plain strings rather than `optional`
// because an empty value is already unambiguous: NVML never returns one, and
// the matching `errors` entry names the query that failed. `index` is always
// populated, so a device is identifiable even when both lookups fail.
message GpuDevice {
  // NVML device index (PCI order)
  uint32 index = 1;
  string uuid = 2;
  // PCI BDF from nvmlPciInfo.busId
  string pci_bus_id = 3;
  // SM duty cycle, percent
  optional uint32 utilization_gpu = 4;
  // Memory-bus duty cycle, percent
  optional uint32 utilization_memory = 5;
  optional uint64 memory_total_bytes = 6;
  optional uint64 memory_used_bytes = 7;
  optional uint64 memory_free_bytes = 8;
  optional uint32 temperature_c = 9;
  optional uint32 power_usage_mw = 10;
  // Failed queries for this card, one per entry; empty if all fields succeeded
  repeated string errors = 11;
}

// GPU inventory collected through NVML.
//
// `error` is non-empty when NVML itself is unavailable, or when the sample
// could not be taken at all. In that case `gpus` is empty. An empty `gpus`
// with an empty `error` means the collector ran and the guest has no NVIDIA
// GPUs.
//
// `cc_ready` and `cc_enabled` are both system-wide, not per device: NVML
// exposes them as `nvmlSystemGetConfComputeGpusReadyState` and
// `nvmlSystemGetConfComputeSettings`, which nvml-wrapper hangs off `Device`
// without using the device handle. `cc_enabled` says the CC feature is turned
// on; `cc_ready` says the SPDM handshake finished and the GPUs are accepting
// client work. Both unset when the query is unsupported or failed.
//
// `sample_age_ms` is how old the returned sample is. The agent serves the last
// known snapshot rather than nothing, so consumers must decide for themselves
// how stale is too stale. Unset when the response carries no sample.
message GpuInfoResponse {
  repeated GpuDevice gpus = 1;
  string error = 2;
  optional bool cc_ready = 3;
  optional bool cc_enabled = 4;
  optional uint64 sample_age_ms = 5;
}

// Direct gRPC surface exposed by the in-guest agent.
service GuestApi {
  // Returns attestation material and identifiers for the calling guest.
  rpc Info(google.protobuf.Empty) returns (GuestInfo);
  // Reports the guest's OS/kernel and resource statistics.
  rpc SysInfo(google.protobuf.Empty) returns (SystemInfo);
  // Reports per-GPU utilization, memory, temperature, power, and CC ready state.
  rpc GpuInfo(google.protobuf.Empty) returns (GpuInfoResponse);
  // Dumps NIC/Gateway configuration so operators can debug connectivity.
  rpc NetworkInfo(google.protobuf.Empty) returns (NetworkInformation);
  // Enumerates the containers running under the guest supervisor.
  rpc ListContainers(google.protobuf.Empty) returns (ListContainersResponse);
  // Initiates a graceful shutdown inside the guest VM.
  rpc Shutdown(google.protobuf.Empty) returns (google.protobuf.Empty);
}

// Same API surface as GuestApi but multiplexed by VM ID through VMM.
service ProxiedGuestApi {
  rpc Info(Id) returns (GuestInfo);
  rpc SysInfo(Id) returns (SystemInfo);
  rpc GpuInfo(Id) returns (GpuInfoResponse);
  rpc NetworkInfo(Id) returns (NetworkInformation);
  rpc ListContainers(Id) returns (ListContainersResponse);
  rpc Shutdown(Id) returns (google.protobuf.Empty);
}