// ArcBox API service protocol definitions.
//
// This file contains API-specific services and types that are used by
// arcbox CLI and other high-level clients communicating with the host daemon.
//
// Design sources:
// - internal-docs/architecture/cli-api.md
// - containerd API patterns
syntax = "proto3";
package arcbox.v1;
import "common.proto";
// =============================================================================
// Network Service
// =============================================================================
// NetworkService manages Docker networks.
service NetworkService {
// Creates a new network.
rpc Create(CreateNetworkRequest) returns (CreateNetworkResponse);
// Removes a network.
rpc Remove(RemoveNetworkRequest) returns (Empty);
// Lists networks.
rpc List(ListNetworksRequest) returns (ListNetworksResponse);
// Inspects a network.
rpc Inspect(InspectNetworkRequest) returns (NetworkInfo);
}
// Request to create a network.
message CreateNetworkRequest {
// Network name.
string name = 1;
// Driver (e.g., "bridge", "host", "none").
string driver = 2;
// Internal network (not connected to external network).
bool internal = 3;
// Labels.
map<string, string> labels = 4;
// Enable IPv6.
bool enable_ipv6 = 5;
// IPAM configuration.
IpamConfig ipam = 6;
}
// IPAM configuration.
message IpamConfig {
// Driver name.
string driver = 1;
// IPAM options.
map<string, string> options = 2;
// Subnet configurations.
repeated IpamSubnet subnets = 3;
}
// IPAM subnet configuration.
message IpamSubnet {
// Subnet in CIDR format.
string subnet = 1;
// Gateway address.
string gateway = 2;
// IP range for allocation.
string ip_range = 3;
}
// Response to create network.
message CreateNetworkResponse {
// Network ID.
string id = 1;
// Warning messages.
repeated string warnings = 2;
}
// Request to remove a network.
message RemoveNetworkRequest {
// Network ID or name.
string id = 1;
}
// Request to list networks.
message ListNetworksRequest {
// Filter by labels.
map<string, string> filters = 1;
}
// Response to list networks.
message ListNetworksResponse {
// List of networks.
repeated NetworkSummary networks = 1;
}
// Summary information about a network.
message NetworkSummary {
// Network ID.
string id = 1;
// Network name.
string name = 2;
// Driver.
string driver = 3;
// Scope (local, global).
string scope = 4;
// Created timestamp (RFC3339).
string created = 5;
// Internal network.
bool internal = 6;
// Attachable.
bool attachable = 7;
// Labels.
map<string, string> labels = 8;
}
// Request to inspect a network.
message InspectNetworkRequest {
// Network ID or name.
string id = 1;
// Verbose output.
bool verbose = 2;
}
// Detailed network information.
message NetworkInfo {
// Network ID.
string id = 1;
// Network name.
string name = 2;
// Driver.
string driver = 3;
// Scope.
string scope = 4;
// Created timestamp (RFC3339).
string created = 5;
// Internal network.
bool internal = 6;
// Attachable.
bool attachable = 7;
// Labels.
map<string, string> labels = 8;
// IPAM configuration.
IpamConfig ipam = 9;
// Connected containers.
map<string, NetworkContainer> containers = 10;
// Driver options.
map<string, string> options = 11;
}
// Container connected to a network.
message NetworkContainer {
// Container name.
string name = 1;
// Container endpoint ID.
string endpoint_id = 2;
// IPv4 address.
string ipv4_address = 3;
// IPv6 address.
string ipv6_address = 4;
// MAC address.
string mac_address = 5;
}
// =============================================================================
// System Service
// =============================================================================
// SystemService provides system-level operations.
service SystemService {
// Gets system information.
rpc GetInfo(GetInfoRequest) returns (GetInfoResponse);
// Gets version information.
rpc GetVersion(GetVersionRequest) returns (GetVersionResponse);
// Pings the server.
rpc Ping(SystemPingRequest) returns (SystemPingResponse);
// Gets system events.
rpc Events(EventsRequest) returns (stream Event);
// Prunes unused resources.
rpc Prune(PruneRequest) returns (PruneResponse);
// Gets current daemon setup status. Used by desktop app to show
// startup progress without managing the daemon lifecycle.
rpc GetSetupStatus(Empty) returns (SetupStatus);
// Streams setup status updates. The server pushes a new message
// each time the daemon phase changes (e.g. VM starting → ready).
rpc WatchSetupStatus(Empty) returns (stream SetupStatus);
}
// Request to get system info.
message GetInfoRequest {}
// Response to get system info.
message GetInfoResponse {
// Number of containers.
int64 containers = 1;
// Running containers.
int64 containers_running = 2;
// Paused containers.
int64 containers_paused = 3;
// Stopped containers.
int64 containers_stopped = 4;
// Number of images.
int64 images = 5;
// Number of machines.
int64 machines = 6;
// Running machines.
int64 machines_running = 7;
// Server version.
string server_version = 8;
// Operating system.
string os = 9;
// Architecture.
string arch = 10;
// Total memory.
int64 mem_total = 11;
// Number of CPUs.
int32 ncpu = 12;
// Data directory.
string data_dir = 13;
// Kernel version.
string kernel_version = 14;
// Operating system type.
string os_type = 15;
// Logging driver.
string logging_driver = 16;
// Storage driver.
string storage_driver = 17;
}
// Request to get version.
message GetVersionRequest {}
// Response to get version.
message GetVersionResponse {
// Version string.
string version = 1;
// API version.
string api_version = 2;
// Minimum API version.
string min_api_version = 3;
// Git commit.
string git_commit = 4;
// Build time.
string build_time = 5;
// OS.
string os = 6;
// Architecture.
string arch = 7;
// Go version (for compatibility).
string go_version = 8;
}
// Request to ping the server.
message SystemPingRequest {}
// Response to ping.
message SystemPingResponse {
// API version.
string api_version = 1;
// Build version.
string build_version = 2;
}
// Request to get events.
message EventsRequest {
// Only events since this timestamp (Unix seconds).
int64 since = 1;
// Only events until this timestamp (Unix seconds).
int64 until = 2;
// Filters.
map<string, string> filters = 3;
}
// System event.
message Event {
// Event type (container, image, network, volume, daemon).
string type = 1;
// Action (create, start, stop, die, destroy, etc.).
string action = 2;
// Actor that generated the event.
EventActor actor = 3;
// Timestamp (Unix nanoseconds).
int64 time_nano = 4;
}
// Event actor.
message EventActor {
// ID of the object.
string id = 1;
// Attributes.
map<string, string> attributes = 2;
}
// Request to prune resources.
message PruneRequest {
// Types to prune: containers, images, networks, volumes, all.
repeated string types = 1;
// Remove all unused resources, not just dangling ones.
bool all = 2;
// Filters.
map<string, string> filters = 3;
}
// Response to prune.
message PruneResponse {
// Space reclaimed in bytes.
uint64 space_reclaimed = 1;
// Deleted containers.
repeated string containers_deleted = 2;
// Deleted images.
repeated string images_deleted = 3;
// Deleted networks.
repeated string networks_deleted = 4;
// Deleted volumes.
repeated string volumes_deleted = 5;
}
// =============================================================================
// Icon Service
// =============================================================================
// IconService provides container image icon lookups.
service IconService {
// Gets the icon URL for a container image reference.
rpc GetImageIcon(GetImageIconRequest) returns (GetImageIconResponse);
}
// Request to get the icon URL for a container image.
message GetImageIconRequest {
// Fully qualified image name (e.g., "nginx", "localstack/localstack", "ghcr.io/astral-sh/uv").
string fqin = 1;
}
// Response containing the icon URL.
message GetImageIconResponse {
// Icon URL, empty if not found.
string url = 1;
// Icon source (e.g., "docker_hub_logo", "docker_official_image", "ghcr_avatar").
string source = 2;
}
// =============================================================================
// Volume Service
// =============================================================================
// VolumeService manages Docker volumes.
service VolumeService {
// Creates a volume.
rpc Create(CreateVolumeRequest) returns (CreateVolumeResponse);
// Removes a volume.
rpc Remove(RemoveVolumeRequest) returns (Empty);
// Lists volumes.
rpc List(ListVolumesRequest) returns (ListVolumesResponse);
// Inspects a volume.
rpc Inspect(InspectVolumeRequest) returns (VolumeInfo);
}
// Request to create a volume.
message CreateVolumeRequest {
// Volume name.
string name = 1;
// Driver name.
string driver = 2;
// Driver options.
map<string, string> driver_opts = 3;
// Labels.
map<string, string> labels = 4;
}
// Response to create volume.
message CreateVolumeResponse {
// Volume name.
string name = 1;
// Driver.
string driver = 2;
// Mountpoint.
string mountpoint = 3;
}
// Request to remove a volume.
message RemoveVolumeRequest {
// Volume name.
string name = 1;
// Force removal.
bool force = 2;
}
// Request to list volumes.
message ListVolumesRequest {
// Filters.
map<string, string> filters = 1;
}
// Response to list volumes.
message ListVolumesResponse {
// List of volumes.
repeated VolumeInfo volumes = 1;
// Warnings.
repeated string warnings = 2;
}
// Request to inspect a volume.
message InspectVolumeRequest {
// Volume name.
string name = 1;
}
// Volume information.
message VolumeInfo {
// Volume name.
string name = 1;
// Driver.
string driver = 2;
// Mountpoint.
string mountpoint = 3;
// Created timestamp (RFC3339).
string created = 4;
// Status.
map<string, string> status = 5;
// Labels.
map<string, string> labels = 6;
// Scope (local, global).
string scope = 7;
// Driver options.
map<string, string> options = 8;
// Usage data.
VolumeUsage usage = 9;
}
// Volume usage data.
message VolumeUsage {
// Size in bytes.
int64 size = 1;
// Reference count.
int64 ref_count = 2;
}
// =============================================================================
// Migration Service
// =============================================================================
// MigrationService plans and runs host-side runtime migrations.
service MigrationService {
// Prepares a migration plan for a supported external runtime.
rpc PrepareMigration(PrepareMigrationRequest) returns (PrepareMigrationResponse);
// Runs a prepared migration plan and streams execution progress.
rpc RunMigration(RunMigrationRequest) returns (stream RunMigrationEvent);
}
// Request to prepare a migration.
message PrepareMigrationRequest {
// Stable source runtime identifier (for example, "docker-desktop" or "orbstack").
string source_kind = 1;
// Optional override for the source Docker-compatible socket path.
string source_socket_path = 2;
// Allow prepare to include replace actions in the plan.
bool allow_replacements = 3;
}
// Prepared migration summary.
message PrepareMigrationResponse {
// Opaque identifier for the prepared plan.
string plan_id = 1;
// Source runtime identifier used for the plan.
string source_kind = 2;
// Resolved source socket path used for the plan.
string source_socket_path = 3;
// Number of images included in the plan.
uint32 image_count = 4;
// Number of volumes included in the plan.
uint32 volume_count = 5;
// Number of networks included in the plan.
uint32 network_count = 6;
// Number of containers included in the plan.
uint32 container_count = 7;
// Whether the plan would replace existing ArcBox resources (images, volumes,
// networks, or containers that already exist on the target). When true,
// RunMigrationRequest.allow_replacements must be set to confirm.
bool replacements_required = 8;
// Non-fatal warnings discovered during preparation (for example, volume
// blockers that will require stopping running source containers).
repeated string warnings = 9;
}
// Request to run a prepared migration.
message RunMigrationRequest {
// Opaque identifier returned by PrepareMigration.
string plan_id = 1;
// Confirms that the caller accepts any replace actions in the plan.
bool allow_replacements = 2;
}
// Streaming migration progress event.
message RunMigrationEvent {
// Opaque identifier of the plan being executed.
string plan_id = 1;
// High-level execution phase (for example, "prepare", "images", or "containers").
string phase = 2;
// Optional resource name currently being processed.
string resource = 3;
// Human-readable progress detail.
string message = 4;
// Number of completed work items in the current phase.
uint32 completed = 5;
// Total work items expected in the current phase.
uint32 total = 6;
// Indicates that no more events will follow for this run.
bool done = 7;
// Indicates whether the run completed successfully.
bool success = 8;
}
// =============================================================================
// Shell/Interactive Session Types
// =============================================================================
// Shell input for interactive sessions.
message ShellInput {
// Input data.
bytes data = 1;
// Resize terminal.
TerminalSize resize = 2;
}
// Shell output for interactive sessions.
message ShellOutput {
// Output data.
bytes data = 1;
// Exit code (only set when done).
int32 exit_code = 2;
// Is this the final message.
bool done = 3;
}
// Terminal size.
message TerminalSize {
// Terminal width.
uint32 width = 1;
// Terminal height.
uint32 height = 2;
}
// =============================================================================
// Setup Status
// =============================================================================
// Daemon startup progress and infrastructure health.
// Allows the desktop app (or any gRPC client) to observe daemon readiness
// without managing its lifecycle.
message SetupStatus {
// Daemon startup phases, ordered by progression.
enum Phase {
PHASE_UNSPECIFIED = 0;
INITIALIZING = 1;
ASSETS_READY = 2;
VM_STARTING = 3;
VM_READY = 4;
NETWORK_READY = 5;
READY = 6;
DEGRADED = 7;
DOWNLOADING_ASSETS = 8;
CLEANING_UP = 9;
}
// Current daemon phase.
Phase phase = 1;
// Whether the DNS resolver file is installed.
bool dns_resolver_installed = 2;
// Whether /var/run/docker.sock is symlinked to ArcBox.
bool docker_socket_linked = 3;
// Whether the container subnet route is installed.
bool route_installed = 4;
// Whether the default VM is running.
bool vm_running = 5;
// Human-readable status message.
string message = 6;
// Whether Docker CLI tools are installed.
bool docker_tools_installed = 7;
}