// Container service protocol definitions.
//
// This service handles container lifecycle operations.
//
// Design sources:
// - internal-docs/architecture/cli-api.md (proto/container.proto section)
// - Docker Engine API v1.43 Containers endpoints
// - containerd's container service interface
syntax = "proto3";
package arcbox.v1;
import "common.proto";
// ContainerService manages container lifecycle.
service ContainerService {
// Creates a new container.
rpc Create(CreateContainerRequest) returns (CreateContainerResponse);
// Starts a stopped container.
rpc Start(StartContainerRequest) returns (Empty);
// Stops a running container.
rpc Stop(StopContainerRequest) returns (Empty);
// Kills a container with a signal.
rpc Kill(KillContainerRequest) returns (Empty);
// Removes a container.
rpc Remove(RemoveContainerRequest) returns (Empty);
// Lists containers.
rpc List(ListContainersRequest) returns (ListContainersResponse);
// Inspects a container.
rpc Inspect(InspectContainerRequest) returns (ContainerInfo);
// Gets container logs.
rpc Logs(LogsRequest) returns (stream LogEntry);
// Creates an exec instance.
rpc ExecCreate(ExecCreateRequest) returns (ExecCreateResponse);
// Starts an exec instance.
rpc ExecStart(ExecStartRequest) returns (stream ExecOutput);
// Attaches to a container.
rpc Attach(stream AttachInput) returns (stream AttachOutput);
// Waits for a container to exit.
rpc Wait(WaitContainerRequest) returns (WaitContainerResponse);
// Pauses a container.
rpc Pause(PauseContainerRequest) returns (Empty);
// Unpauses a container.
rpc Unpause(UnpauseContainerRequest) returns (Empty);
// Gets container stats.
rpc Stats(ContainerStatsRequest) returns (ContainerStatsResponse);
// Gets container processes (top).
rpc Top(ContainerTopRequest) returns (ContainerTopResponse);
}
// Request to create a container.
message CreateContainerRequest {
// Container name (optional, auto-generated if empty).
string name = 1;
// Image reference.
string image = 2;
// Command to run.
repeated string cmd = 3;
// Entrypoint override.
repeated string entrypoint = 4;
// Environment variables.
map<string, string> env = 5;
// Working directory.
string working_dir = 6;
// User to run as.
string user = 7;
// Mount specifications.
repeated Mount mounts = 8;
// Port bindings.
repeated PortBinding ports = 9;
// Resource limits.
ResourceLimits limits = 10;
// Labels.
map<string, string> labels = 11;
// Hostname.
string hostname = 12;
// Allocate a TTY.
bool tty = 13;
// Keep stdin open.
bool stdin_open = 14;
// Network mode.
string network_mode = 15;
}
// Response to create container.
message CreateContainerResponse {
// Container ID.
string id = 1;
// Warnings during creation.
repeated string warnings = 2;
}
// Request to start a container.
message StartContainerRequest {
// Container ID or name.
string id = 1;
}
// Request to stop a container.
message StopContainerRequest {
// Container ID or name.
string id = 1;
// Timeout in seconds before kill.
uint32 timeout = 2;
}
// Request to kill a container.
message KillContainerRequest {
// Container ID or name.
string id = 1;
// Signal to send.
string signal = 2;
}
// Request to remove a container.
message RemoveContainerRequest {
// Container ID or name.
string id = 1;
// Force removal of running container.
bool force = 2;
// Remove associated volumes.
bool volumes = 3;
}
// Request to list containers.
message ListContainersRequest {
// Show all containers (not just running).
bool all = 1;
// Maximum number of containers to return.
int32 limit = 2;
// Show sizes.
bool size = 3;
// Filters as JSON-encoded map.
string filters = 4;
}
// Response to list containers.
message ListContainersResponse {
// List of containers.
repeated ContainerSummary containers = 1;
}
// Summary information about a container.
message ContainerSummary {
// Container ID.
string id = 1;
// Container names.
repeated string names = 2;
// Image name.
string image = 3;
// Image ID.
string image_id = 4;
// Command.
string command = 5;
// Creation timestamp.
int64 created = 6;
// State (running, exited, etc.).
string state = 7;
// Status string.
string status = 8;
// Port bindings.
repeated PortBinding ports = 9;
// Labels.
map<string, string> labels = 10;
// Size in bytes (rw layer).
int64 size_rw = 11;
// Size of root filesystem.
int64 size_root_fs = 12;
}
// Request to inspect a container.
message InspectContainerRequest {
// Container ID or name.
string id = 1;
// Include size information.
bool size = 2;
}
// Detailed container information.
message ContainerInfo {
// Container ID.
string id = 1;
// Container name.
string name = 2;
// Creation timestamp.
Timestamp created = 3;
// Path to container command.
string path = 4;
// Arguments to command.
repeated string args = 5;
// Container state.
ContainerState state = 6;
// Image reference.
string image = 7;
// Container configuration.
ContainerConfig config = 8;
// Network settings.
NetworkSettings network_settings = 9;
// Mount points.
repeated MountPoint mounts = 10;
}
// Container state information.
message ContainerState {
// Current status.
string status = 1;
// Is container running.
bool running = 2;
// Is container paused.
bool paused = 3;
// Is container restarting.
bool restarting = 4;
// Is OOM killed.
bool oom_killed = 5;
// Is container dead.
bool dead = 6;
// Container PID.
int32 pid = 7;
// Exit code.
int32 exit_code = 8;
// Error message.
string error = 9;
// Start time.
string started_at = 10;
// Finish time.
string finished_at = 11;
}
// Container configuration.
message ContainerConfig {
// Hostname.
string hostname = 1;
// Domain name.
string domainname = 2;
// User.
string user = 3;
// Working directory.
string working_dir = 4;
// Command.
repeated string cmd = 5;
// Entrypoint.
repeated string entrypoint = 6;
// Environment variables.
repeated string env = 7;
// Image.
string image = 8;
// Labels.
map<string, string> labels = 9;
// TTY allocation.
bool tty = 10;
// Open stdin.
bool open_stdin = 11;
}
// Network settings.
message NetworkSettings {
// IP address.
string ip_address = 1;
// Gateway.
string gateway = 2;
// MAC address.
string mac_address = 3;
// Network ID.
string network_id = 4;
}
// Mount point information.
message MountPoint {
// Mount type.
string type = 1;
// Source.
string source = 2;
// Destination.
string destination = 3;
// Read-only.
bool rw = 4;
}
// Request for container logs.
message LogsRequest {
// Container ID or name.
string container_id = 1;
// Follow log output.
bool follow = 2;
// Show stdout.
bool stdout = 3;
// Show stderr.
bool stderr = 4;
// Show timestamps.
bool timestamps = 5;
// Only logs since this time (Unix timestamp).
int64 since = 6;
// Only logs until this time (Unix timestamp).
int64 until = 7;
// Number of lines from end ("all" means all).
string tail = 8;
}
// Log entry.
message LogEntry {
// Stream type: stdout or stderr.
string stream = 1;
// Log message.
bytes message = 2;
// Timestamp.
Timestamp timestamp = 3;
}
// Request to create an exec instance.
message ExecCreateRequest {
// Container ID or name.
string container_id = 1;
// Command to run.
repeated string cmd = 2;
// Attach stdin.
bool attach_stdin = 3;
// Attach stdout.
bool attach_stdout = 4;
// Attach stderr.
bool attach_stderr = 5;
// Allocate TTY.
bool tty = 6;
// Environment variables.
repeated string env = 7;
// Working directory.
string working_dir = 8;
// User to run as.
string user = 9;
// Run in privileged mode.
bool privileged = 10;
}
// Response to create exec.
message ExecCreateResponse {
// Exec ID.
string id = 1;
}
// Request to start an exec instance.
message ExecStartRequest {
// Exec ID.
string id = 1;
// Detach from exec.
bool detach = 2;
// TTY mode.
bool tty = 3;
// Console size (height, width).
repeated uint32 console_size = 4;
}
// Exec output.
message ExecOutput {
// Stream type: stdout or stderr.
string stream = 1;
// Output data.
bytes data = 2;
}
// Attach input.
message AttachInput {
// Input data.
bytes data = 1;
// Resize terminal.
bool resize = 2;
// Terminal height.
uint32 height = 3;
// Terminal width.
uint32 width = 4;
}
// Attach output.
message AttachOutput {
// Stream type.
string stream = 1;
// Output data.
bytes data = 2;
}
// Request to wait for a container.
message WaitContainerRequest {
// Container ID or name.
string id = 1;
// Condition to wait for: not-running, next-exit, removed.
string condition = 2;
}
// Response when container exits.
message WaitContainerResponse {
// Exit code.
int64 status_code = 1;
// Error message if any.
string error = 2;
}
// Request to pause a container.
message PauseContainerRequest {
// Container ID or name.
string id = 1;
}
// Request to unpause a container.
message UnpauseContainerRequest {
// Container ID or name.
string id = 1;
}
// Request for container stats.
message ContainerStatsRequest {
// Container ID or name.
string id = 1;
}
// Container stats response.
message ContainerStatsResponse {
// CPU usage in nanoseconds.
uint64 cpu_usage = 1;
// System CPU usage in nanoseconds.
uint64 system_cpu_usage = 2;
// Number of online CPUs.
uint32 online_cpus = 3;
// Memory usage in bytes.
uint64 memory_usage = 4;
// Memory limit in bytes.
uint64 memory_limit = 5;
// Network bytes received.
uint64 network_rx_bytes = 6;
// Network bytes transmitted.
uint64 network_tx_bytes = 7;
// Block I/O read bytes.
uint64 block_read_bytes = 8;
// Block I/O write bytes.
uint64 block_write_bytes = 9;
// Number of PIDs.
uint32 pids = 10;
}
// Request for container top (process list).
message ContainerTopRequest {
// Container ID or name.
string id = 1;
// ps arguments (optional).
string ps_args = 2;
}
// Container top response.
message ContainerTopResponse {
// Column titles.
repeated string titles = 1;
// Process rows (each row is a list of values).
repeated ProcessRow processes = 2;
}
// A single process row.
message ProcessRow {
// Values for each column.
repeated string values = 1;
}