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;
}

// 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);
  // 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 NetworkInfo(Id) returns (NetworkInformation);
  rpc ListContainers(Id) returns (ListContainersResponse);
  rpc Shutdown(Id) returns (google.protobuf.Empty);
}