Agent Internal Reference

Protocol Documentation

proto/composia/agent/v1/agent.proto
Scalar Value Types

proto/composia/agent/v1/agent.proto

AcknowledgeTaskRequest

Field	Type	Label	Description
task_id	string
execution_id	string

AcknowledgeTaskResponse

Field	Type	Label	Description
lease_expires_at	google.protobuf.Timestamp

AgentTask

AgentTask describes one executable task assigned to an agent.

Field	Type	Label	Description
task_id	string		task_id is the controller task ID assigned to the agent.
type	AgentTaskType		type identifies the task kind assigned by the controller.
service_name	string		service_name is the logical service name.
node_id	string		node_id is the target node ID for the task.
repo_revision	string		repo_revision is the desired repo revision for this task.
service_dir	string		service_dir is the task service directory path within the bundle.
data_names	string	repeated	data_names lists selected data entries for backup-like tasks.
params_json	string		params_json stores task-type-specific JSON parameters.
execution_id	string		execution_id identifies this specific delivery and rejects stale reports.
lease_expires_at	google.protobuf.Timestamp		lease_expires_at is the controller deadline for acknowledging or renewing this execution.

ContainerInfo

ContainerInfo describes one container for list views.

Field	Type	Label	Description
id	string
name	string		name is the runtime container name.
image	string
state	string		state is the low-level Docker state value.
status	string		status is the Docker status string intended for display.
created	string		created is the container creation timestamp string.
labels	ContainerInfo.LabelsEntry	repeated	labels is the container label map.
ports	string	repeated	ports contains display-formatted published port mappings.
networks	string	repeated	networks lists connected Docker network names.
image_id	string		image_id is the resolved image ID.

ContainerInfo.LabelsEntry

Field	Type	Label	Description
key	string
value	string

DockerQueryRunContainerExecRequest

DockerQueryRunContainerExecRequest runs a non-interactive command in one local container.

Field	Type	Label
container_id	string
command	string	repeated
stdin	bytes
timeout_seconds	uint32
max_output_bytes	uint64

DockerQueryRunContainerExecResponse

DockerQueryRunContainerExecResponse returns the collected exec result.

Field	Type	Label	Description
exit_code	int32
stdout	string
stderr	string
timed_out	bool
stdout_truncated	bool
stderr_truncated	bool
started_at	google.protobuf.Timestamp
finished_at	google.protobuf.Timestamp
duration	string

DockerQueryTask

DockerQueryTask describes one synchronous Docker query assigned to an agent.

Field	Type	Description
query_id	string	query_id is the controller-generated query ID.
node_id	string	node_id is the target node ID for the query.
list_containers	ListContainersRequest
inspect_container	InspectContainerRequest
list_networks	ListNetworksRequest
inspect_network	InspectNetworkRequest
list_volumes	ListVolumesRequest
inspect_volume	InspectVolumeRequest
list_images	ListImagesRequest
inspect_image	InspectImageRequest
container_logs	GetContainerLogsRequest
run_container_exec	DockerQueryRunContainerExecRequest

DockerStats

DockerStats describes a node-level Docker usage snapshot.

Field	Type	Description
containers_total	uint32
containers_running	uint32	containers_running is the number of running containers.
containers_stopped	uint32	containers_stopped is the number of stopped containers.
containers_paused	uint32	containers_paused is the number of paused containers.
images	uint32	images is the number of local Docker images.
networks	uint32	networks is the number of local Docker networks.
volumes	uint32	volumes is the number of local Docker volumes.
volumes_size_bytes	uint64	volumes_size_bytes is the total reported volume size in bytes.
disks_usage_bytes	uint64	disks_usage_bytes is the Docker-reported disk usage in bytes.
docker_server_version	string

GetContainerLogsRequest

GetContainerLogsRequest fetches logs for one local container.

Field	Type	Description
container_id	string	container_id is the runtime container ID.
tail	string	tail is forwarded to the Docker log tail option.
timestamps	bool	timestamps includes Docker timestamps in the returned log output.

GetContainerLogsResponse

GetContainerLogsResponse returns one streamed log chunk.

Field	Type	Label	Description
content	string

GetServiceBundleRequest

GetServiceBundleRequest identifies the task whose bundle should be streamed.

Field	Type	Description
task_id	string	task_id is the controller task ID whose bundle should be streamed.
service_dir	string	service_dir overrides the task service directory for multi-service bundle consumers.
execution_id	string

GetServiceBundleResponse

GetServiceBundleResponse carries one binary chunk from a task bundle stream.

Field	Type	Description
service_name	string	service_name is the logical service name.
repo_revision	string	repo_revision is the repo revision packaged in the bundle.
relative_root	string	relative_root is the relative root path for the streamed bundle contents.
data	bytes	data contains one chunk of the bundle payload.

HeartbeatRequest

HeartbeatRequest is the lightweight keepalive sent by an agent.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
agent_version	string	agent_version is the agent version string.
sent_at	google.protobuf.Timestamp	sent_at is the agent time when the heartbeat was sent.
runtime	NodeRuntimeSummary

HeartbeatResponse

HeartbeatResponse acknowledges a heartbeat with the controller receive time.

Field	Type	Label	Description
received_at	google.protobuf.Timestamp

ImageInfo

ImageInfo describes one Docker image for list views.

Field	Type	Label	Description
id	string
repo_tags	string	repeated	repo_tags lists named tags referencing the image.
size	int64		size is the image size in bytes.
virtual_size	int64		virtual_size is the virtual image size in bytes.
created	string		created is the image creation timestamp string.
repo_digests	string	repeated	repo_digests lists immutable digest references for the image.
architecture	string		architecture is the image CPU architecture string.
os	string		os is the image operating system string.
author	string		author is the image author metadata, when present.
containers_count	uint32		containers_count is the number of containers using the image.
is_dangling	bool		is_dangling reports whether the image is dangling.

InspectContainerRequest

InspectContainerRequest identifies one local container.

Field	Type	Label	Description
container_id	string		container_id is the runtime container ID.

InspectContainerResponse

InspectContainerResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

InspectImageRequest

InspectImageRequest identifies one local image.

Field	Type	Label	Description
image_id	string		image_id is the runtime image ID.

InspectImageResponse

InspectImageResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

InspectNetworkRequest

InspectNetworkRequest identifies one local network.

Field	Type	Label	Description
network_id	string		network_id is the runtime network ID.

InspectNetworkResponse

InspectNetworkResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

InspectVolumeRequest

InspectVolumeRequest identifies one local volume.

Field	Type	Label	Description
volume_name	string		volume_name is the runtime volume name.

InspectVolumeResponse

InspectVolumeResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

ListContainersRequest

ListContainersRequest requests all local Docker containers.

Field	Type	Description
page_size	uint32	page_size is the requested page size.
page	uint32	page is the 1-based page number.
search	string	search is a case-insensitive substring match across key fields.
sort_by	string	sort_by identifies the field used to sort results.
sort_desc	bool	sort_desc reverses the sort order when true.

ListContainersResponse

ListContainersResponse returns local container summaries.

Field	Type	Label	Description
containers	ContainerInfo	repeated
total_count	uint32

ListImagesRequest

ListImagesRequest requests all local Docker images.

Field	Type	Description
page_size	uint32	page_size is the requested page size.
page	uint32	page is the 1-based page number.
search	string	search is a case-insensitive substring match across key fields.
sort_by	string	sort_by identifies the field used to sort results.
sort_desc	bool	sort_desc reverses the sort order when true.

ListImagesResponse

ListImagesResponse returns local image summaries.

Field	Type	Label	Description
images	ImageInfo	repeated
total_count	uint32

ListNetworksRequest

ListNetworksRequest requests all local Docker networks.

Field	Type	Description
page_size	uint32	page_size is the requested page size.
page	uint32	page is the 1-based page number.
search	string	search is a case-insensitive substring match across key fields.
sort_by	string	sort_by identifies the field used to sort results.
sort_desc	bool	sort_desc reverses the sort order when true.

ListNetworksResponse

ListNetworksResponse returns local network summaries.

Field	Type	Label	Description
networks	NetworkInfo	repeated
total_count	uint32

ListVolumesRequest

ListVolumesRequest requests all local Docker volumes.

Field	Type	Description
page_size	uint32	page_size is the requested page size.
page	uint32	page is the 1-based page number.
search	string	search is a case-insensitive substring match across key fields.
sort_by	string	sort_by identifies the field used to sort results.
sort_desc	bool	sort_desc reverses the sort order when true.

ListVolumesResponse

ListVolumesResponse returns local volume summaries.

Field	Type	Label	Description
volumes	VolumeInfo	repeated
total_count	uint32

NetworkInfo

NetworkInfo describes one Docker network for list views.

Field	Type	Label	Description
id	string
name	string		name is the runtime network name.
driver	string		driver is the Docker network driver name.
scope	string		scope is the Docker network scope.
internal	bool		internal reports whether the network is internal-only.
attachable	bool		attachable reports whether standalone containers may attach to the network.
created	string		created is the network creation timestamp string.
labels	NetworkInfo.LabelsEntry	repeated	labels is the network label map.
subnet	string		subnet is the primary IPv4 subnet, when available.
gateway	string		gateway is the primary IPv4 gateway, when available.
containers_count	uint32		containers_count is the number of connected containers.
ipv6_enabled	bool		ipv6_enabled reports whether IPv6 is enabled for the network.

NetworkInfo.LabelsEntry

Field	Type	Label	Description
key	string
value	string

NodeRuntimeSummary

NodeRuntimeSummary reports basic runtime capacity for a node.

Field	Type	Description
docker_server_version	string	docker_server_version is the local Docker Engine version string.
disk_total_bytes	uint64	disk_total_bytes is the total disk capacity visible to the agent.
disk_free_bytes	uint64	disk_free_bytes is the currently free disk capacity visible to the agent.

OpenContainerLogTunnelRequest

OpenContainerLogTunnelRequest carries one container log tunnel frame to the controller.

Field	Type	Description
session_id	string	session_id identifies the container log session.
kind	string	kind identifies the frame type carried in this message.
content	string	content carries one log chunk for chunk frames.
error_message	string	error_message contains the frame-level failure summary, when present.
error_code	string	error_code carries a Connect-style lowercase code string such as not_found.

OpenContainerLogTunnelResponse

OpenContainerLogTunnelResponse carries one container log tunnel frame to the agent.

Field	Type	Description
session_id	string	session_id identifies the container log session.
kind	string	kind identifies the frame type carried in this message.
container_id	string	container_id identifies the target container for the log session.
tail	string	tail is forwarded to the Docker log tail option for the session.
timestamps	bool	timestamps includes Docker timestamps in streamed log chunks.

OpenExecTunnelRequest

OpenExecTunnelRequest carries one frame for an interactive exec session.

Field	Type	Label	Description
session_id	string		session_id identifies the interactive exec session.
kind	string		kind identifies the frame type carried in this message.
payload	bytes		payload holds raw terminal or control bytes for the frame.
rows	uint32		rows is the terminal row count carried by resize frames.
cols	uint32		cols is the terminal column count carried by resize frames.
node_id	string		node_id identifies the node that should execute the command.
container_id	string		container_id identifies the target container for the exec session.
command	string	repeated	command stores the exec command and arguments.

OpenExecTunnelResponse

OpenExecTunnelResponse carries one frame back to the controller side.

Field	Type	Label	Description
session_id	string		session_id identifies the interactive exec session.
kind	string		kind identifies the frame type carried in this message.
payload	bytes		payload holds raw terminal or control bytes for the frame.
rows	uint32		rows is the terminal row count carried by resize frames.
cols	uint32		cols is the terminal column count carried by resize frames.
error	string		error contains the frame-level error message, when present.
container_id	string		container_id identifies the target container for the exec session.
command	string	repeated	command stores the exec command and arguments.

PullNextDockerQueryRequest

PullNextDockerQueryRequest identifies the node that is requesting a Docker query.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.

PullNextDockerQueryResponse

PullNextDockerQueryResponse indicates whether a Docker query was assigned.

Field	Type	Label	Description
has_query	bool		has_query is false when there is currently no Docker query to run.
query	DockerQueryTask		query is populated only when has_query is true.

PullNextTaskRequest

PullNextTaskRequest identifies the node that is requesting work.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.
execution_protocol	uint32		execution_protocol must be 1; legacy agents are not allowed to execute leased tasks.

PullNextTaskResponse

PullNextTaskResponse indicates whether a task was assigned.

Field	Type	Label	Description
has_task	bool		has_task is false when there is currently no task to run.
task	AgentTask		task is populated only when has_task is true.

RemoveContainerRequest

RemoveContainerRequest identifies one local container deletion.

Field	Type	Description
container_id	string	container_id is the runtime container ID.
force	bool	force deletes the container even if it is running.
remove_volumes	bool	remove_volumes also removes anonymous volumes attached to the container.

RemoveContainerResponse

RemoveContainerResponse acknowledges one local container deletion request.

RemoveImageRequest

RemoveImageRequest identifies one local image deletion.

Field	Type	Label	Description
image_id	string		image_id is the runtime image ID or reference.
force	bool		force deletes the image even if it has multiple tags or dependent stopped containers.

RemoveImageResponse

RemoveImageResponse acknowledges one local image deletion request.

RemoveNetworkRequest

RemoveNetworkRequest identifies one local network deletion.

Field	Type	Label	Description
network_id	string		network_id is the runtime network ID.

RemoveNetworkResponse

RemoveNetworkResponse acknowledges one local network deletion request.

RemoveVolumeRequest

RemoveVolumeRequest identifies one local volume deletion.

Field	Type	Label	Description
volume_name	string		volume_name is the runtime volume name.

RemoveVolumeResponse

RemoveVolumeResponse acknowledges one local volume deletion request.

RenewTaskLeaseRequest

Field	Type	Label	Description
task_id	string
execution_id	string

RenewTaskLeaseResponse

Field	Type	Label	Description
lease_expires_at	google.protobuf.Timestamp

ReportBackupResultRequest

ReportBackupResultRequest reports the result of one backup execution.

Field	Type	Description
backup_id	string	backup_id is the backup record ID being updated.
task_id	string	task_id is the controller task ID that triggered the backup.
service_name	string	service_name is the logical service name.
data_name	string	data_name is the service data entry that was backed up.
status	string	status is the latest backup status string observed by the agent.
started_at	google.protobuf.Timestamp	started_at is the backup start time.
finished_at	google.protobuf.Timestamp	finished_at is set when the backup reaches a terminal state.
artifact_ref	string	artifact_ref identifies the produced backup artifact, when present.
error_summary	string	error_summary contains the failure summary when the backup fails.
execution_id	string

ReportBackupResultResponse

ReportBackupResultResponse acknowledges a backup result update.

ReportDockerQueryResultRequest

ReportDockerQueryResultRequest reports the result of one direct Docker query.

Field	Type	Description
query_id	string	query_id is the controller-generated query ID.
node_id	string	node_id is the stable node identifier that executed the query.
list_containers	ListContainersResponse
inspect_container	InspectContainerResponse
list_networks	ListNetworksResponse
inspect_network	InspectNetworkResponse
list_volumes	ListVolumesResponse
inspect_volume	InspectVolumeResponse
list_images	ListImagesResponse
inspect_image	InspectImageResponse
container_logs	GetContainerLogsResponse
run_container_exec	DockerQueryRunContainerExecResponse
error_message	string	error_message contains the human-readable failure summary when the query fails.
error_code	DockerQueryErrorCode	error_code carries the normalized failure code when the query fails.

ReportDockerQueryResultResponse

ReportDockerQueryResultResponse acknowledges a Docker query result.

ReportDockerStatsRequest

ReportDockerStatsRequest reports the latest node Docker stats snapshot.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.
stats	DockerStats		stats is the current Docker usage snapshot for the node.

ReportDockerStatsResponse

ReportDockerStatsResponse acknowledges a Docker stats update.

ReportServiceImageStatesRequest

ReportServiceImageStatesRequest reports image digests observed by one agent.

Field	Type	Label
service_name	string
node_id	string
images	ServiceImageState	repeated
reported_at	google.protobuf.Timestamp
task_id	string
execution_id	string

ReportServiceImageStatesResponse

ReportServiceImageStatesResponse acknowledges image state updates.

ReportServiceImageUpdateChecksRequest

ReportServiceImageUpdateChecksRequest reports candidate image updates observed by one agent.

Field	Type	Label
service_name	string
node_id	string
checks	ServiceImageUpdateCheck	repeated
reported_at	google.protobuf.Timestamp
task_id	string
execution_id	string

ReportServiceImageUpdateChecksResponse

ReportServiceImageUpdateChecksResponse acknowledges image update check results.

ReportServiceInstanceStatusRequest

ReportServiceInstanceStatusRequest reports one service instance runtime snapshot.

Field	Type	Description
service_name	string	service_name is the logical service name.
node_id	string	node_id is the stable node identifier.
runtime_status	string	runtime_status is the latest instance status string observed by the agent.
reported_at	google.protobuf.Timestamp	reported_at is the time when the status snapshot was observed.
task_id	string
execution_id	string

ReportServiceInstanceStatusResponse

ReportServiceInstanceStatusResponse acknowledges a service status update.

ReportTaskStateRequest

ReportTaskStateRequest reports the latest task-level state from an agent.

Field	Type	Description
task_id	string	task_id is the controller task ID being updated.
status	AgentTaskStatus	status is the latest task status observed by the agent.
error_summary	string	error_summary contains the task failure summary when the task fails.
finished_at	google.protobuf.Timestamp	finished_at is set when the task reaches a terminal state.
execution_id	string	execution_id binds the terminal report to the current task delivery.

ReportTaskStateResponse

ReportTaskStateResponse acknowledges a task state update.

ReportTaskStepStateRequest

ReportTaskStepStateRequest reports the latest task step state from an agent.

Field	Type	Description
task_id	string	task_id is the controller task ID being updated.
step_name	AgentTaskStepName	step_name identifies the step being updated.
status	AgentTaskStatus	status is the latest step status observed by the agent.
started_at	google.protobuf.Timestamp	started_at is set when the step begins.
finished_at	google.protobuf.Timestamp	finished_at is set when the step reaches a terminal state.
execution_id	string

ReportTaskStepStateResponse

ReportTaskStepStateResponse acknowledges a task step state update.

RunContainerActionRequest

RunContainerActionRequest identifies one local container action.

Field	Type	Label	Description
container_id	string
action	ContainerAction

RunContainerActionResponse

RunContainerActionResponse acknowledges a local container action request.

ServiceImageState

ServiceImageState describes one compose service image digest observation.

Field	Type	Label	Description
compose_service	string
image_ref	string
local_digest	string
remote_digest	string
local_digest_observed	bool
remote_digest_observed	bool
check_status	string
error_summary	string

ServiceImageUpdateCheck

ServiceImageUpdateCheck describes one configured image update check result.

Field	Type	Label
image_name	string
image_ref	string
policy_type	string
current_value	string
current_tag	string
current_digest	string
candidate_tag	string
candidate_digest	string
candidate_tags	string	repeated
update_available	bool
check_status	string
error_summary	string

UploadTaskLogsRequest

UploadTaskLogsRequest carries one ordered log chunk for a task.

Field	Type	Description
task_id	string	task_id is the controller task ID receiving the log chunk.
seq	uint64	seq is a monotonically increasing sequence number per task log stream.
sent_at	google.protobuf.Timestamp	sent_at is the agent time when this log chunk was sent.
content	string	content is the incremental log payload.
execution_id	string

UploadTaskLogsResponse

UploadTaskLogsResponse acknowledges received task log chunks.

Field	Type	Label	Description
task_id	string		task_id is the controller task ID receiving the acknowledgement.
last_confirmed_seq	uint64		last_confirmed_seq is the last sequence the controller accepted.

VolumeInfo

VolumeInfo describes one Docker volume for list views.

Field	Type	Label	Description
name	string		name is the runtime volume name.
driver	string		driver is the Docker volume driver name.
mountpoint	string		mountpoint is the volume mount path on the node.
scope	string		scope is the Docker volume scope.
created	string		created is the volume creation timestamp string.
labels	VolumeInfo.LabelsEntry	repeated	labels is the volume label map.
size_bytes	int64		size_bytes is the reported volume size in bytes.
containers_count	uint32		containers_count is the number of attached containers.
in_use	bool		in_use reports whether any container currently uses the volume.

VolumeInfo.LabelsEntry

Field	Type	Label	Description
key	string
value	string

AgentTaskStatus

AgentTaskStatus identifies a task lifecycle status reported by an agent.

Name	Number	Description
AGENT_TASK_STATUS_UNSPECIFIED	0
AGENT_TASK_STATUS_PENDING	1
AGENT_TASK_STATUS_RUNNING	2
AGENT_TASK_STATUS_AWAITING_CONFIRMATION	3
AGENT_TASK_STATUS_SUCCEEDED	4
AGENT_TASK_STATUS_FAILED	5
AGENT_TASK_STATUS_CANCELLED	6

AgentTaskStepName

AgentTaskStepName identifies a task step reported by an agent.

Name	Number	Description
AGENT_TASK_STEP_NAME_UNSPECIFIED	0
AGENT_TASK_STEP_NAME_RENDER	1
AGENT_TASK_STEP_NAME_PULL	2
AGENT_TASK_STEP_NAME_BACKUP	3
AGENT_TASK_STEP_NAME_COMPOSE_DOWN	4
AGENT_TASK_STEP_NAME_COMPOSE_UP	5
AGENT_TASK_STEP_NAME_TRANSFER	6
AGENT_TASK_STEP_NAME_RESTORE	7
AGENT_TASK_STEP_NAME_DNS_UPDATE	8
AGENT_TASK_STEP_NAME_CADDY_SYNC	9
AGENT_TASK_STEP_NAME_CADDY_RELOAD	10
AGENT_TASK_STEP_NAME_IMAGE_CHECK	11
AGENT_TASK_STEP_NAME_INIT	12
AGENT_TASK_STEP_NAME_PRUNE	13
AGENT_TASK_STEP_NAME_AWAITING_CONFIRMATION	14
AGENT_TASK_STEP_NAME_PERSIST_REPO	15
AGENT_TASK_STEP_NAME_FINALIZE	16
AGENT_TASK_STEP_NAME_DOCKER_START	17
AGENT_TASK_STEP_NAME_DOCKER_STOP	18
AGENT_TASK_STEP_NAME_DOCKER_RESTART	19
AGENT_TASK_STEP_NAME_DOCKER_REMOVE	20
AGENT_TASK_STEP_NAME_CLOUDFLARE_TUNNEL_SYNC	21

AgentTaskType

AgentTaskType identifies one executable task kind.

Name	Number	Description
AGENT_TASK_TYPE_UNSPECIFIED	0
AGENT_TASK_TYPE_DEPLOY	1
AGENT_TASK_TYPE_STOP	2
AGENT_TASK_TYPE_RESTART	3
AGENT_TASK_TYPE_UPDATE	4
AGENT_TASK_TYPE_BACKUP	5
AGENT_TASK_TYPE_RESTORE	6
AGENT_TASK_TYPE_MIGRATE	7
AGENT_TASK_TYPE_DNS_UPDATE	8
AGENT_TASK_TYPE_CADDY_SYNC	9
AGENT_TASK_TYPE_CADDY_RELOAD	10
AGENT_TASK_TYPE_IMAGE_CHECK	11
AGENT_TASK_TYPE_PRUNE	12
AGENT_TASK_TYPE_RUSTIC_INIT	13
AGENT_TASK_TYPE_RUSTIC_FORGET	14
AGENT_TASK_TYPE_RUSTIC_PRUNE	15
AGENT_TASK_TYPE_DOCKER_START	16
AGENT_TASK_TYPE_DOCKER_STOP	17
AGENT_TASK_TYPE_DOCKER_RESTART	18
AGENT_TASK_TYPE_DOCKER_REMOVE_CONTAINER	20
AGENT_TASK_TYPE_DOCKER_REMOVE_NETWORK	21
AGENT_TASK_TYPE_DOCKER_REMOVE_VOLUME	22
AGENT_TASK_TYPE_DOCKER_REMOVE_IMAGE	23
AGENT_TASK_TYPE_CLOUDFLARE_TUNNEL_SYNC	24

ContainerAction

ContainerAction identifies a container lifecycle action.

Name	Number	Description
CONTAINER_ACTION_UNSPECIFIED	0	CONTAINER_ACTION_UNSPECIFIED is invalid and should not be used.
CONTAINER_ACTION_START	1	CONTAINER_ACTION_START starts the container.
CONTAINER_ACTION_STOP	2	CONTAINER_ACTION_STOP stops the container.
CONTAINER_ACTION_RESTART	3	CONTAINER_ACTION_RESTART restarts the container.

DockerQueryErrorCode

DockerQueryErrorCode identifies the normalized error code for a Docker query.

Name	Number	Description
DOCKER_QUERY_ERROR_CODE_UNSPECIFIED	0
DOCKER_QUERY_ERROR_CODE_INVALID_ARGUMENT	1
DOCKER_QUERY_ERROR_CODE_NOT_FOUND	2
DOCKER_QUERY_ERROR_CODE_FAILED_PRECONDITION	3
DOCKER_QUERY_ERROR_CODE_PERMISSION_DENIED	4
DOCKER_QUERY_ERROR_CODE_DEADLINE_EXCEEDED	5
DOCKER_QUERY_ERROR_CODE_UNAVAILABLE	6
DOCKER_QUERY_ERROR_CODE_INTERNAL	7

AgentReportService

AgentReportService carries agent-to-controller runtime and task reports.

Method Name	Request Type	Response Type	Description
Heartbeat	HeartbeatRequest	HeartbeatResponse	Heartbeat reports that an agent is alive and includes runtime metadata.
ReportTaskState	ReportTaskStateRequest	ReportTaskStateResponse	ReportTaskState reports the latest state for one task.
ReportTaskStepState	ReportTaskStepStateRequest	ReportTaskStepStateResponse	ReportTaskStepState reports the latest state for one task step.
UploadTaskLogs	UploadTaskLogsRequest stream	UploadTaskLogsResponse stream	UploadTaskLogs streams log chunks from the agent to the controller.
ReportBackupResult	ReportBackupResultRequest	ReportBackupResultResponse	ReportBackupResult reports the result of one backup operation.
ReportServiceInstanceStatus	ReportServiceInstanceStatusRequest	ReportServiceInstanceStatusResponse	ReportServiceInstanceStatus reports the current status of one service instance.
ReportServiceImageStates	ReportServiceImageStatesRequest	ReportServiceImageStatesResponse	ReportServiceImageStates reports image digest observations for one service instance.
ReportServiceImageUpdateChecks	ReportServiceImageUpdateChecksRequest	ReportServiceImageUpdateChecksResponse	ReportServiceImageUpdateChecks reports candidate image updates for one service instance.
ReportDockerStats	ReportDockerStatsRequest	ReportDockerStatsResponse	ReportDockerStats reports the latest Docker stats snapshot for one node.
ReportDockerQueryResult	ReportDockerQueryResultRequest	ReportDockerQueryResultResponse	ReportDockerQueryResult reports the result of one direct Docker query.
OpenExecTunnel	OpenExecTunnelRequest stream	OpenExecTunnelResponse stream	OpenExecTunnel proxies interactive exec traffic between controller and agent.
OpenContainerLogTunnel	OpenContainerLogTunnelRequest stream	OpenContainerLogTunnelResponse stream	OpenContainerLogTunnel proxies live container log traffic between controller and agent.

AgentTaskService

AgentTaskService lets an agent pull work assigned to its node.

Method Name	Request Type	Response Type	Description
PullNextTask	PullNextTaskRequest	PullNextTaskResponse	PullNextTask returns the next available task for the requesting node.
AcknowledgeTask	AcknowledgeTaskRequest	AcknowledgeTaskResponse	AcknowledgeTask confirms that the agent durably accepted an offered task.
RenewTaskLease	RenewTaskLeaseRequest	RenewTaskLeaseResponse	RenewTaskLease extends an accepted task execution lease.
PullNextDockerQuery	PullNextDockerQueryRequest	PullNextDockerQueryResponse	PullNextDockerQuery returns the next in-memory Docker query for the requesting node.

BundleService

BundleService streams service bundles needed to execute a task.

Method Name	Request Type	Response Type	Description
GetServiceBundle	GetServiceBundleRequest	GetServiceBundleResponse stream	GetServiceBundle streams the task bundle as binary chunks.

DockerService

DockerService exposes Docker operations that run on the agent node.

Method Name	Request Type	Response Type	Description
ListContainers	ListContainersRequest	ListContainersResponse	ListContainers lists local Docker containers.
InspectContainer	InspectContainerRequest	InspectContainerResponse	InspectContainer returns raw Docker inspect JSON for one container.
RunContainerAction	RunContainerActionRequest	RunContainerActionResponse	RunContainerAction applies a lifecycle action to one container.
RemoveContainer	RemoveContainerRequest	RemoveContainerResponse	RemoveContainer deletes one container.
GetContainerLogs	GetContainerLogsRequest	GetContainerLogsResponse stream	GetContainerLogs streams log text for one container.
ListNetworks	ListNetworksRequest	ListNetworksResponse	ListNetworks lists local Docker networks.
InspectNetwork	InspectNetworkRequest	InspectNetworkResponse	InspectNetwork returns raw Docker inspect JSON for one network.
RemoveNetwork	RemoveNetworkRequest	RemoveNetworkResponse	RemoveNetwork deletes one network.
ListVolumes	ListVolumesRequest	ListVolumesResponse	ListVolumes lists local Docker volumes.
InspectVolume	InspectVolumeRequest	InspectVolumeResponse	InspectVolume returns raw Docker inspect JSON for one volume.
RemoveVolume	RemoveVolumeRequest	RemoveVolumeResponse	RemoveVolume deletes one volume.
ListImages	ListImagesRequest	ListImagesResponse	ListImages lists local Docker images.
InspectImage	InspectImageRequest	InspectImageResponse	InspectImage returns raw Docker inspect JSON for one image.
RemoveImage	RemoveImageRequest	RemoveImageResponse	RemoveImage deletes one image.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)

Last updated on Jul 16, 2026 • Renovate Bot

Local Development Controller Reference