arcbox-protocol 0.4.9

// Machine service protocol definitions.
//
// This service manages virtual machines.
//
// Design sources:
// - internal-docs/architecture/cli-api.md (MachineCommands section)
// - OrbStack's machine management API (conceptual reference)
// - Lima VM management interface patterns

syntax = "proto3";

package arcbox.v1;

import "common.proto";

// MachineService manages virtual machines.
service MachineService {
    // Creates a new virtual machine.
    rpc Create(CreateMachineRequest) returns (CreateMachineResponse);

    // Starts a stopped machine.
    rpc Start(StartMachineRequest) returns (Empty);

    // Stops a running machine.
    rpc Stop(StopMachineRequest) returns (Empty);

    // Removes a machine.
    rpc Remove(RemoveMachineRequest) returns (Empty);

    // Lists machines.
    rpc List(ListMachinesRequest) returns (ListMachinesResponse);

    // Inspects a machine.
    rpc Inspect(InspectMachineRequest) returns (MachineInfo);

    // Pings the guest agent for a machine.
    rpc Ping(MachineAgentRequest) returns (MachinePingResponse);

    // Gets guest system information for a machine.
    rpc GetSystemInfo(MachineAgentRequest) returns (MachineSystemInfo);

    // Executes a command in a machine.
    rpc Exec(MachineExecRequest) returns (stream MachineExecOutput);

    // Gets the SSH connection info.
    rpc SSHInfo(SSHInfoRequest) returns (SSHInfoResponse);
}

// Request to create a machine.
message CreateMachineRequest {
    // Machine name.
    string name = 1;
    // Number of CPUs (0 = use the daemon default).
    uint32 cpus = 2;
    // Memory in bytes.
    uint64 memory = 3;
    // Disk size in bytes.
    uint64 disk_size = 4;
    // Linux distribution (e.g., "ubuntu", "alpine").
    string distro = 5;
    // Version of the distribution.
    string version = 6;
    // Architecture (e.g., "aarch64", "x86_64").
    string arch = 7;
    // Directory mounts.
    repeated DirectoryMount mounts = 8;
    // SSH public key.
    string ssh_public_key = 9;
    // Kernel image path.
    string kernel = 10;
    // Field 11 was initrd (removed in schema v6).
    reserved 11;
    // Kernel command line.
    string cmdline = 12;
}

// Request that targets a machine's guest agent.
message MachineAgentRequest {
    // Machine ID or name.
    string id = 1;
}

// Ping response from machine guest agent.
message MachinePingResponse {
    // Response payload.
    string message = 1;
    // Agent version.
    string version = 2;
}

// System information reported by machine guest agent.
message MachineSystemInfo {
    // Kernel version.
    string kernel_version = 1;
    // OS name.
    string os_name = 2;
    // OS version.
    string os_version = 3;
    // Architecture.
    string arch = 4;
    // Total memory in bytes.
    uint64 total_memory = 5;
    // Available memory in bytes.
    uint64 available_memory = 6;
    // Number of CPUs.
    uint32 cpu_count = 7;
    // Load average (1, 5, 15 minutes).
    repeated double load_average = 8;
    // Hostname.
    string hostname = 9;
    // Uptime in seconds.
    uint64 uptime = 10;
    // Guest IP addresses (excluding loopback).
    repeated string ip_addresses = 11;
}

// Directory mount configuration.
message DirectoryMount {
    // Host directory path.
    string host_path = 1;
    // Guest mount point.
    string guest_path = 2;
    // Read-only flag.
    bool readonly = 3;
}

// Response to create machine.
message CreateMachineResponse {
    // Machine ID.
    string id = 1;
}

// Request to start a machine.
message StartMachineRequest {
    // Machine ID or name.
    string id = 1;
}

// Request to stop a machine.
message StopMachineRequest {
    // Machine ID or name.
    string id = 1;
    // Force stop.
    bool force = 2;
}

// Request to remove a machine.
message RemoveMachineRequest {
    // Machine ID or name.
    string id = 1;
    // Force removal.
    bool force = 2;
    // Remove volumes.
    bool volumes = 3;
}

// Request to list machines.
message ListMachinesRequest {
    // Show all machines (including stopped).
    bool all = 1;
}

// Response to list machines.
message ListMachinesResponse {
    // List of machines.
    repeated MachineSummary machines = 1;
}

// Summary information about a machine.
message MachineSummary {
    // Machine ID.
    string id = 1;
    // Machine name.
    string name = 2;
    // State (running, stopped, etc.).
    string state = 3;
    // Number of CPUs.
    uint32 cpus = 4;
    // Memory in bytes.
    uint64 memory = 5;
    // Disk size in bytes.
    uint64 disk_size = 6;
    // IP address.
    string ip_address = 7;
    // Creation timestamp.
    int64 created = 8;
}

// Request to inspect a machine.
message InspectMachineRequest {
    // Machine ID or name.
    string id = 1;
}

// Detailed machine information.
message MachineInfo {
    // Machine ID.
    string id = 1;
    // Machine name.
    string name = 2;
    // State.
    string state = 3;
    // Hardware configuration.
    MachineHardware hardware = 4;
    // Network configuration.
    MachineNetwork network = 5;
    // Storage configuration.
    MachineStorage storage = 6;
    // OS information.
    MachineOS os = 7;
    // Creation timestamp.
    Timestamp created = 8;
    // Last start timestamp.
    Timestamp started_at = 9;
    // Directory mounts.
    repeated DirectoryMount mounts = 10;
}

// Machine hardware configuration.
message MachineHardware {
    // Number of CPUs.
    uint32 cpus = 1;
    // Memory in bytes.
    uint64 memory = 2;
    // Architecture.
    string arch = 3;
}

// Machine network configuration.
message MachineNetwork {
    // IP address.
    string ip_address = 1;
    // Gateway.
    string gateway = 2;
    // MAC address.
    string mac_address = 3;
    // DNS servers.
    repeated string dns_servers = 4;
    // MAC address of the bridge NAT NIC used for host-side vmnet routing on macOS.
    string bridge_mac_address = 5;
}

// Machine storage configuration.
message MachineStorage {
    // Disk size in bytes.
    uint64 disk_size = 1;
    // Disk format.
    string disk_format = 2;
    // Disk path.
    string disk_path = 3;
}

// Machine OS information.
message MachineOS {
    // Distribution name.
    string distro = 1;
    // Version.
    string version = 2;
    // Kernel version.
    string kernel = 3;
}

// Request to execute a command in a machine.
message MachineExecRequest {
    // Machine ID or name.
    string id = 1;
    // Command to execute.
    repeated string cmd = 2;
    // Working directory.
    string working_dir = 3;
    // User to run as.
    string user = 4;
    // Environment variables.
    map<string, string> env = 5;
    // Allocate TTY.
    bool tty = 6;
}

// Exec output from a machine.
message MachineExecOutput {
    // Stream type: stdout or stderr.
    string stream = 1;
    // Output data.
    bytes data = 2;
    // Exit code (only set on completion).
    int32 exit_code = 3;
    // Is this the final message.
    bool done = 4;
}

// Request for SSH connection info.
message SSHInfoRequest {
    // Machine ID or name.
    string id = 1;
}

// SSH connection information.
message SSHInfoResponse {
    // Host to connect to.
    string host = 1;
    // Port number.
    uint32 port = 2;
    // Username.
    string user = 3;
    // Private key path (if using key-based auth).
    string identity_file = 4;
    // SSH command string.
    string command = 5;
}