Proto

Protobuf

The VM Registry Proto repository (vm-registry-proto) contains the shared Protocol Buffer definitions that form the communication contract between the CLI (Rust) and the Daemon (Go). It defines a single gRPC service — VMService — along with all request and response message types, organized into domain-specific .proto files.

Overview

The proto definitions serve as the single source of truth for the gRPC API. Both the Rust CLI (via tonic-prost-build) and the Go daemon (via protoc-gen-go-grpc) generate their respective client and server code from these same .proto files, ensuring type-safe communication across language boundaries.

vm-registry-proto/
├── vm.proto              # Service definition (imports all message defs)
└── defs/
    ├── action.proto       # VM lifecycle messages
    ├── auth.proto         # Authentication messages
    ├── compose.proto      # Multi-VM orchestration messages
    ├── context.proto      # Context management messages
    ├── image.proto        # Image management messages
    └── network.proto      # Network management messages

Service Definition

The VMService is the sole gRPC service, defined in vm.proto. It aggregates all RPCs across every domain into a unified interface exposed by the daemon over a Unix domain socket.

Authentication RPCs

RPC	Request	Response	Description
Login	LoginRequest	LoginResponse	Authenticate a user and receive an access token
Logout	LogoutRequest	LogoutResponse	Revoke credentials and clear the session
Register	RegisterRequest	RegisterResponse	Create a new user account
HealthCheck	Empty	HealthCheckResponse	Check daemon, registry, and auth server health

Image RPCs

RPC	Request	Response	Description
PullImage	PullImageRequest	PullImageResponse	Download an image from the remote registry
PushImage	PushImageRequest	PushImageResponse	Upload an image to the remote registry
ImportImage	ImportImageRequest	ImportImageResponse	Import a VM image with inline disk data
ImportImageStream	stream ImportImageStreamRequest	ImportImageResponse	Import a VM image via chunked streaming
ExportImage	ExportImageRequest	ExportImageResponse	Export an image to a file on disk
ListLocalImages	Empty	ListLocalImagesResponse	List all locally stored images
DeleteImage	DeleteImageRequest	DeleteImageResponse	Remove a local image
GetImageManifest	GetImageManifestRequest	GetImageManifestResponse	Retrieve an image's manifest JSON
ValidateVMFile	ValidateVMFileRequest	ValidateVMFileResponse	Validate a VMFile without importing
TagImage	TagImageRequest	TagImageResponse	Create a new tag for an existing image
GarbageCollect	GarbageCollectRequest	GarbageCollectResponse	Clean up orphaned blobs and manifests

Context RPCs

RPC	Request	Response	Description
ContextCreate	ContextCreateRequest	ContextResponse	Create a new named context
ContextUpdate	ContextUpdateRequest	ContextResponse	Modify an existing context
ContextUse	ContextUseRequest	ContextResponse	Switch the active context
ContextList	Empty	ContextListResponse	List all configured contexts
ContextRemove	ContextRemoveRequest	ContextResponse	Delete a context
ContextCurrent	Empty	ContextInfoResponse	Get the currently active context

Action RPCs

RPC	Request	Response	Description
RunVM	RunVMRequest	RunVMResponse	Create and start a new VM from an image
StartVM	StartVMRequest	StartVMResponse	Start a stopped VM
StopVM	StopVMRequest	StopVMResponse	Stop a running VM
RestartVM	RestartVMRequest	RestartVMResponse	Restart a VM
DeleteVM	DeleteVMRequest	DeleteVMResponse	Destroy and undefine a VM
PsVMs	Empty	PsVMsResponse	List running VMs with process details
ListVMs	Empty	ListVMsResponse	List all VMs with basic info

Network RPCs

RPC	Request	Response	Description
NetworkList	Empty	NetworkListResponse	List all libvirt networks
NetworkGet	NetworkGetRequest	NetworkGetResponse	Get details of a specific network
NetworkCreate	NetworkCreateRequest	NetworkCreateResponse	Create a new virtual network
NetworkActivate	NetworkActivateRequest	NetworkActivateResponse	Activate an inactive network
NetworkDeactivate	NetworkDeactivateRequest	NetworkDeactivateResponse	Deactivate a running network
NetworkDelete	NetworkDeleteRequest	NetworkDeleteResponse	Delete a network definition

Compose RPCs

RPC	Request	Response	Description
ComposeUp	ComposeUpRequest	ComposeUpResponse	Deploy a multi-VM environment
ComposeDown	ComposeDownRequest	ComposeDownResponse	Tear down a compose project
ComposePs	ComposePsRequest	ComposePsResponse	List services in a compose project
ComposeRestart	ComposeRestartRequest	ComposeRestartResponse	Restart compose services
ComposeValidate	ComposeValidateRequest	ComposeValidateResponse	Validate a VMCompose file

Key Message Types

VMFile

The VMFile message represents a complete VM image definition, used during import and validation:

Field	Type	Description
api_version	string	API version (e.g., vmregistry.io/v1alpha1)
metadata	VMMetadata	Image name, description, author, source, and labels
spec	VMSpec	Disk image path, format, and resource allocation

VMRunOptions

Controls how a VM is launched, sent as part of RunVMRequest:

Field	Type	Description
memory_mb	uint32	Memory allocation in megabytes
vcpu_count	uint32	Number of virtual CPUs
ephemeral	bool	Whether disk changes are discarded on stop
cloud_init	CloudInitConfig	Cloud-init user-data, meta-data, and network-config
activate_network	bool	Activate the network if not already active
network_name	string	Name of the libvirt network to attach to

VMProcessInfo

Detailed information about a running VM, returned by PsVMs:

Field	Type	Description
vm_id	string	Unique VM identifier
name	string	VM name
status	string	Current state (running, stopped, etc.)
image	string	Source image reference
created	string	Creation timestamp
uptime	string	Time since the VM was started
networks	repeated VMNetworkInfo	Attached network details (name, MAC, interface type)

NetworkInfo

Detailed network information, returned by network list and inspect operations:

Field	Type	Description
name	string	Network name
uuid	string	Libvirt UUID
active	bool	Whether the network is currently active
persistent	bool	Whether the network persists across restarts
autostart	bool	Whether the network auto-starts on host boot
mode	string	Network mode (nat, isolated, routed, bridge