Controller Reference

Protocol Documentation

proto/composia/controller/v1/task.proto
proto/composia/controller/v1/system.proto
proto/composia/controller/v1/backup.proto
proto/composia/controller/v1/container.proto
proto/composia/controller/v1/node.proto
proto/composia/controller/v1/repo.proto
proto/composia/controller/v1/secret.proto
proto/composia/controller/v1/service.proto
Scalar Value Types

proto/composia/controller/v1/task.proto

CreateMigrationRollbackRequest

CreateMigrationRollbackRequest selects safe recovery actions for one migration task.

Field	Type	Description
task_id	string	task_id identifies the original migrate task.
rollback_dns	bool	rollback_dns syncs DNS back to the source node.
deploy_source	bool	deploy_source starts the service on the source node again.
stop_target	bool	stop_target stops the service on the migration target node.
cleanup_target	bool	cleanup_target is reserved for a future destructive cleanup workflow.

FailLostTaskExecutionRequest

Field	Type	Label	Description
task_id	string
error_summary	string

GetTaskRequest

GetTaskRequest identifies one task by ID.

Field	Type	Label	Description
task_id	string

GetTaskResponse

GetTaskResponse describes one task, including step state and log metadata.

Field	Type	Label	Description
task_id	string
type	TaskType		type identifies the controller task kind.
source	TaskSource		source identifies what triggered the task.
service_name	string
node_id	string
status	TaskStatus		status is the latest task status.
created_at	google.protobuf.Timestamp		created_at is the task creation timestamp.
started_at	google.protobuf.Timestamp		started_at is unset until task execution begins.
finished_at	google.protobuf.Timestamp		finished_at is unset until task execution reaches a terminal state.
repo_revision	string		repo_revision is the repo revision used when the task started.
error_summary	string
steps	TaskStepSummary	repeated	steps lists recorded step state snapshots in execution order.
triggered_by	string		triggered_by identifies the actor that created the task.
result_revision	string		result_revision is the repo revision produced by the task, when applicable.
attempt_of_task_id	string		attempt_of_task_id links this task to the prior task it retried.
execution_state	string		execution_state exposes offered, accepted, lease_lost, or completed for agent tasks.
lease_expires_at	google.protobuf.Timestamp

ListTasksRequest

ListTasksRequest filters task results by included and excluded values.

Field	Type	Label	Description
status	TaskStatus	repeated	status includes only tasks matching one of these statuses.
service_name	string	repeated	service_name includes only tasks for these services.
page_size	uint32		page_size is the requested page size.
page	uint32		page is the 1-based page number.
node_id	string	repeated	node_id includes only tasks for these nodes.
type	TaskType	repeated	type includes only tasks of these types.
exclude_status	TaskStatus	repeated	exclude_status removes tasks matching these statuses.
exclude_service_name	string	repeated	exclude_service_name removes tasks for these services.
exclude_node_id	string	repeated	exclude_node_id removes tasks for these nodes.
exclude_type	TaskType	repeated	exclude_type removes tasks of these types.

ListTasksResponse

ListTasksResponse returns one page of task summaries.

Field	Type	Label	Description
tasks	TaskSummary	repeated
total_count	uint32

ResolveTaskConfirmationRequest

ResolveTaskConfirmationRequest resolves a task in awaiting_confirmation state.

Field	Type	Description
task_id	string
decision	TaskConfirmationDecision	decision resolves the confirmation gate.
comment	string

RunTaskAgainRequest

RunTaskAgainRequest identifies the task to retry as a new task.

Field	Type	Label	Description
task_id	string

TailTaskLogsRequest

TailTaskLogsRequest identifies the task log stream to follow.

Field	Type	Label	Description
task_id	string

TailTaskLogsResponse

TailTaskLogsResponse carries one incremental log chunk.

Field	Type	Label	Description
content	string

TaskActionResponse

TaskActionResponse reports the async task created by a command RPC.

Field	Type	Description
task_id	string
status	TaskStatus	status is the initial status of the created task.
repo_revision	string	repo_revision is the repo revision associated with the created task.

TaskStepSummary

TaskStepSummary describes one recorded step within a task.

Field	Type	Description
step_name	TaskStepName
status	TaskStatus	status is the latest step status.
started_at	google.protobuf.Timestamp	started_at is unset when the step has not started.
finished_at	google.protobuf.Timestamp	finished_at is unset until the step finishes.

TaskSummary

TaskSummary describes one task in list results.

Field	Type	Description
task_id	string
type	TaskType	type identifies the controller task kind.
status	TaskStatus	status is the latest task status.
service_name	string
node_id	string
created_at	google.protobuf.Timestamp	created_at is the task creation timestamp.

TaskConfirmationDecision

TaskConfirmationDecision identifies how an operator resolved a confirmation gate.

Name	Number	Description
TASK_CONFIRMATION_DECISION_UNSPECIFIED	0
TASK_CONFIRMATION_DECISION_APPROVE	1
TASK_CONFIRMATION_DECISION_REJECT	2

TaskSource

TaskSource identifies what created a task.

Name	Number	Description
TASK_SOURCE_UNSPECIFIED	0
TASK_SOURCE_WEB	1
TASK_SOURCE_CLI	2
TASK_SOURCE_OTHERS	3
TASK_SOURCE_SCHEDULE	4
TASK_SOURCE_SYSTEM	5
TASK_SOURCE_AUTO_DEPLOY	6

TaskStatus

TaskStatus identifies a task lifecycle status.

Name	Number	Description
TASK_STATUS_UNSPECIFIED	0
TASK_STATUS_PENDING	1
TASK_STATUS_RUNNING	2
TASK_STATUS_AWAITING_CONFIRMATION	3
TASK_STATUS_SUCCEEDED	4
TASK_STATUS_FAILED	5
TASK_STATUS_CANCELLED	6

TaskStepName

TaskStepName identifies one recorded task step.

Name	Number	Description
TASK_STEP_NAME_UNSPECIFIED	0
TASK_STEP_NAME_RENDER	1
TASK_STEP_NAME_PULL	2
TASK_STEP_NAME_BACKUP	3
TASK_STEP_NAME_COMPOSE_DOWN	4
TASK_STEP_NAME_COMPOSE_UP	5
TASK_STEP_NAME_TRANSFER	6
TASK_STEP_NAME_RESTORE	7
TASK_STEP_NAME_DNS_UPDATE	8
TASK_STEP_NAME_CADDY_SYNC	9
TASK_STEP_NAME_CADDY_RELOAD	10
TASK_STEP_NAME_IMAGE_CHECK	11
TASK_STEP_NAME_INIT	12
TASK_STEP_NAME_PRUNE	13
TASK_STEP_NAME_AWAITING_CONFIRMATION	14
TASK_STEP_NAME_PERSIST_REPO	15
TASK_STEP_NAME_FINALIZE	16
TASK_STEP_NAME_DOCKER_START	17
TASK_STEP_NAME_DOCKER_STOP	18
TASK_STEP_NAME_DOCKER_RESTART	19
TASK_STEP_NAME_DOCKER_REMOVE	20
TASK_STEP_NAME_CLOUDFLARE_TUNNEL_SYNC	21

TaskType

TaskType identifies a controller task kind.

Name	Number	Description
TASK_TYPE_UNSPECIFIED	0
TASK_TYPE_DEPLOY	1
TASK_TYPE_STOP	2
TASK_TYPE_RESTART	3
TASK_TYPE_UPDATE	4
TASK_TYPE_BACKUP	5
TASK_TYPE_RESTORE	6
TASK_TYPE_MIGRATE	7
TASK_TYPE_DNS_UPDATE	8
TASK_TYPE_CADDY_SYNC	9
TASK_TYPE_CADDY_RELOAD	10
TASK_TYPE_IMAGE_CHECK	11
TASK_TYPE_PRUNE	12
TASK_TYPE_RUSTIC_INIT	13
TASK_TYPE_RUSTIC_FORGET	14
TASK_TYPE_RUSTIC_PRUNE	15
TASK_TYPE_DOCKER_START	16
TASK_TYPE_DOCKER_STOP	17
TASK_TYPE_DOCKER_RESTART	18
TASK_TYPE_MIGRATE_ROLLBACK	20
TASK_TYPE_DOCKER_REMOVE_CONTAINER	21
TASK_TYPE_DOCKER_REMOVE_NETWORK	22
TASK_TYPE_DOCKER_REMOVE_VOLUME	23
TASK_TYPE_DOCKER_REMOVE_IMAGE	24
TASK_TYPE_CLOUDFLARE_TUNNEL_SYNC	25

TaskService

TaskService exposes task queries, log streaming, retry operations, and confirmation resolution.

Method Name	Request Type	Response Type	Description
ListTasks	ListTasksRequest	ListTasksResponse	ListTasks returns task summaries using include and exclude filters.
GetTask	GetTaskRequest	GetTaskResponse	GetTask returns the full detail for one task.
TailTaskLogs	TailTaskLogsRequest	TailTaskLogsResponse stream	TailTaskLogs streams incremental log content for one task.
RunTaskAgain	RunTaskAgainRequest	TaskActionResponse	RunTaskAgain starts a new task based on an existing task.
FailLostTaskExecution	FailLostTaskExecutionRequest	TaskActionResponse	FailLostTaskExecution resolves a lease-lost task after an operator verifies its outcome.
ResolveTaskConfirmation	ResolveTaskConfirmationRequest	TaskActionResponse	ResolveTaskConfirmation resumes or rejects a task waiting for manual confirmation.
CreateMigrationRollback	CreateMigrationRollbackRequest	TaskActionResponse	CreateMigrationRollback starts a rollback task from a failed or rejected migration.

Top

proto/composia/controller/v1/system.proto

AccessTokenSummary

AccessTokenSummary describes one controller access token without exposing the token string.

Field	Type	Description
name	string	name is the operator-facing token name.
enabled	bool	enabled reports whether this token may be used.
comment	string	comment is the optional operator note attached to the token.

BackupConfigSummary

BackupConfigSummary describes optional backup integration state.

Field	Type	Label	Description
has_rustic	bool		has_rustic reports whether Rustic backup integration is configured.

Capability

Capability describes whether a feature or action may currently be used.

Field	Type	Label	Description
enabled	bool
reason_code	CapabilityReasonCode		reason_code explains why the capability is disabled when enabled is false.

DNSConfigSummary

DNSConfigSummary describes optional DNS integration state.

Field	Type	Label	Description
has_cloudflare	bool		has_cloudflare reports whether Cloudflare DNS integration is configured.

GetCapabilitiesRequest

GetCapabilitiesRequest requests global controller-backed feature availability.

GetCapabilitiesResponse

GetCapabilitiesResponse returns global feature availability for the web UI.

Field	Type	Label	Description
global	GlobalCapabilities

GetCurrentConfigRequest

GetCurrentConfigRequest requests the active redacted controller config.

GetCurrentConfigResponse

GetCurrentConfigResponse contains redacted config summaries only.

Field	Type	Label	Description
listen_addr	string		listen_addr is the controller listen address.
git	GitConfigSummary		git is the configured Git sync summary for the controller repo.
nodes	NodeConfigSummary	repeated	nodes lists configured execution nodes.
access_tokens	AccessTokenSummary	repeated	access_tokens lists token metadata without returning secret token values.
dns	DNSConfigSummary		dns describes optional DNS integration configuration.
backup	BackupConfigSummary		backup describes optional backup integration configuration.
secrets	SecretsConfigSummary		secrets describes the active secrets provider configuration.

GetSystemStatusRequest

GetSystemStatusRequest requests the current controller runtime state.

GetSystemStatusResponse

GetSystemStatusResponse describes the current controller runtime state.

Field	Type	Description
version	string	version is the controller version string.
now	google.protobuf.Timestamp	now is the controller time when the response was generated.
configured_node_count	uint64	configured_node_count is the number of nodes present in config.
online_node_count	uint64	online_node_count is the number of nodes with a recent heartbeat.
service_count	uint64	service_count is the total number of declared services.
running_service_count	uint64	running_service_count is the number of declared services with at least one running instance.

GitConfigSummary

GitConfigSummary describes controller Git sync settings without credentials.

Field	Type	Description
remote_url	string	remote_url is the configured Git remote URL.
branch	string	branch is the tracked Git branch name.
pull_interval	string	pull_interval stores the configured pull interval duration string.
has_auth	bool	has_auth reports whether Git auth is configured, not the auth value itself.
author_name	string	author_name is the Git author name for controller-created commits.
author_email	string	author_email is the Git author email for controller-created commits.

GlobalCapabilities

GlobalCapabilities describes controller-wide feature availability.

Field	Type	Label	Description
backup	Capability
dns	Capability
secrets	Capability
rustic_maintenance	Capability

NodeConfigSummary

NodeConfigSummary describes one configured node entry.

Field	Type	Description
id	string	id is the stable node identifier used across controller and agents.
display_name	string	display_name is the human-readable node label.
enabled	bool	enabled reports whether the node is eligible for controller actions.
public_ipv4	string	public_ipv4 is empty when no public IPv4 address is configured.
public_ipv6	string	public_ipv6 is empty when no public IPv6 address is configured.

ReloadControllerConfigRequest

ReloadControllerConfigRequest requests an in-process controller config reload.

ReloadControllerConfigResponse

ReloadControllerConfigResponse confirms that the reload was accepted.

Field	Type	Label	Description
accepted	bool		accepted is true when the current config passed reload validation and was scheduled.

SecretsConfigSummary

SecretsConfigSummary describes the active secrets provider setup.

Field	Type	Description
provider	string	provider is the configured secrets provider name.
has_identity	bool	has_identity reports whether an identity source is configured.
has_recipient	bool	has_recipient reports whether a recipient source is configured.

CapabilityReasonCode

CapabilityReasonCode explains why a capability is disabled.

Name	Number	Description
CAPABILITY_REASON_CODE_UNSPECIFIED	0
CAPABILITY_REASON_CODE_MISSING_BACKUP_INTEGRATION	1
CAPABILITY_REASON_CODE_MISSING_BACKUP_DEFINITION	2
CAPABILITY_REASON_CODE_MISSING_RESTORE_DEFINITION	3
CAPABILITY_REASON_CODE_MISSING_MIGRATE_DEFINITION	4
CAPABILITY_REASON_CODE_MISSING_DNS_INTEGRATION	5
CAPABILITY_REASON_CODE_MISSING_SECRETS_CONFIG	6
CAPABILITY_REASON_CODE_MISSING_CADDY_INFRA	7
CAPABILITY_REASON_CODE_MISSING_SERVICE_META	8
CAPABILITY_REASON_CODE_SERVICE_NOT_DECLARED	9
CAPABILITY_REASON_CODE_SERVICE_DNS_NOT_DECLARED	10
CAPABILITY_REASON_CODE_SERVICE_NOT_CADDY_MANAGED	11
CAPABILITY_REASON_CODE_NODE_DISABLED	12
CAPABILITY_REASON_CODE_NODE_OFFLINE	13
CAPABILITY_REASON_CODE_NODE_NOT_ELIGIBLE	14
CAPABILITY_REASON_CODE_NODE_NOT_RUSTIC_MANAGED	15
CAPABILITY_REASON_CODE_MISSING_ELIGIBLE_RUSTIC_NODE	16
CAPABILITY_REASON_CODE_MISSING_ONLINE_RUSTIC_NODE	17
CAPABILITY_REASON_CODE_BACKUP_NOT_SUCCEEDED	18
CAPABILITY_REASON_CODE_BACKUP_ARTIFACT_MISSING	19
CAPABILITY_REASON_CODE_MISSING_RESTORE_TARGET_NODE	20
CAPABILITY_REASON_CODE_MISSING_CLOUDFLARE_TUNNEL_INTEGRATION	21
CAPABILITY_REASON_CODE_SERVICE_NOT_CLOUDFLARE_TUNNEL_MANAGED	22

SystemService

SystemService exposes read-only controller status and config summary data.

Method Name	Request Type	Response Type	Description
GetSystemStatus	GetSystemStatusRequest	GetSystemStatusResponse	GetSystemStatus returns the current controller status and node counts.
ReloadControllerConfig	ReloadControllerConfigRequest	ReloadControllerConfigResponse	ReloadControllerConfig validates and applies the controller config without replacing the process.
GetCurrentConfig	GetCurrentConfigRequest	GetCurrentConfigResponse	GetCurrentConfig returns the active controller config as a redacted summary.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	GetCapabilities returns global feature availability for the current controller state.

Top

proto/composia/controller/v1/backup.proto

BackupActionCapabilities

BackupActionCapabilities describes whether backup-scoped actions may run.

Field	Type	Label	Description
restore	Capability

BackupSummary

BackupSummary describes one backup record in list results.

Field	Type	Description
backup_id	string
task_id	string	task_id links the backup record to the originating task.
service_name	string
data_name	string
status	string	status is the latest backup status string.
started_at	string	started_at is the backup start timestamp string.
finished_at	string	finished_at is empty until the backup reaches a terminal state.
node_id	string

GetBackupRequest

GetBackupRequest identifies one backup record by ID.

Field	Type	Label	Description
backup_id	string

GetBackupResponse

GetBackupResponse describes one backup record in detail.

Field	Type	Description
backup_id	string
task_id	string	task_id links the backup record to the originating task.
service_name	string
data_name	string
status	string	status is the latest backup status string.
started_at	string	started_at is the backup start timestamp string.
finished_at	string	finished_at is empty until 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.
actions	BackupActionCapabilities	actions describes whether backup-scoped actions may currently run.
node_id	string

ListBackupsRequest

ListBackupsRequest filters backup records by included and excluded values.

Field	Type	Label	Description
service_name	string	repeated	service_name includes only backups for these services.
status	string	repeated	status includes only backups matching one of these status strings.
data_name	string	repeated	data_name includes only backups for these service data entries.
page_size	uint32		page_size is the requested page size.
page	uint32		page is the 1-based page number.
node_id	string	repeated	node_id includes only backups for these source nodes.
exclude_service_name	string	repeated	exclude_service_name removes backups for these services.
exclude_status	string	repeated	exclude_status removes backups matching these status strings.
exclude_data_name	string	repeated	exclude_data_name removes backups for these service data entries.
exclude_node_id	string	repeated	exclude_node_id removes backups for these source nodes.

ListBackupsResponse

ListBackupsResponse returns one page of backup records.

Field	Type	Label	Description
backups	BackupSummary	repeated
total_count	uint32

RestoreBackupRequest

RestoreBackupRequest identifies the backup record and target node for one restore task.

Field	Type	Label	Description
backup_id	string
node_id	string		node_id identifies the destination node for the restore task.

BackupCommandService

BackupCommandService starts backup-related actions.

Method Name	Request Type	Response Type	Description
RestoreBackup	RestoreBackupRequest	TaskActionResponse	RestoreBackup starts an async restore task from one backup record.

BackupQueryService

BackupQueryService exposes backup record queries.

Method Name	Request Type	Response Type	Description
ListBackups	ListBackupsRequest	ListBackupsResponse	ListBackups returns backup records with filtering and pagination.
GetBackup	GetBackupRequest	GetBackupResponse	GetBackup returns one backup record by ID.

Top

proto/composia/controller/v1/container.proto

GetContainerLogsRequest

GetContainerLogsRequest fetches logs for one container.

Field	Type	Description
node_id	string
container_id	string
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

OpenContainerExecRequest

OpenContainerExecRequest starts an interactive exec session.

Field	Type	Label	Description
node_id	string
container_id	string
command	string	repeated	command stores the exec command and arguments.
rows	uint32		rows is the initial terminal row count.
cols	uint32		cols is the initial terminal column count.

OpenContainerExecResponse

OpenContainerExecResponse returns the session identity and websocket path.

Field	Type	Label	Description
session_id	string		session_id identifies the created interactive exec session.
websocket_path	string		websocket_path is the controller websocket path for the interactive tunnel.

RemoveContainerRequest

RemoveContainerRequest identifies one node-scoped container deletion.

Field	Type	Label	Description
node_id	string
container_id	string
force	bool
remove_volumes	bool

RemoveImageRequest

RemoveImageRequest identifies one node-scoped image deletion.

Field	Type	Label	Description
node_id	string
image_id	string
force	bool

RemoveNetworkRequest

RemoveNetworkRequest identifies one node-scoped network deletion.

Field	Type	Label	Description
node_id	string
network_id	string

RemoveVolumeRequest

RemoveVolumeRequest identifies one node-scoped volume deletion.

Field	Type	Label	Description
node_id	string
volume_name	string

RunContainerActionRequest

RunContainerActionRequest identifies one node-scoped container action.

Field	Type	Label	Description
node_id	string
container_id	string
action	ContainerAction

RunContainerExecRequest

RunContainerExecRequest runs a non-interactive command in one container.

Field	Type	Label	Description
node_id	string
container_id	string
command	string	repeated	command stores the exec command and arguments.
stdin	bytes		stdin carries optional bytes written before stdin is closed.
timeout_seconds	uint32		timeout_seconds bounds command runtime on the agent.
max_output_bytes	uint64		max_output_bytes limits each stdout/stderr stream; zero uses the agent default.

RunContainerExecResponse

RunContainerExecResponse returns the completed 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

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.

DockerCommandService

DockerCommandService exposes node-scoped Docker command entrypoints.

Method Name	Request Type	Response Type	Description
RunContainerAction	RunContainerActionRequest	TaskActionResponse	RunContainerAction starts an async action for one container on one node.
RemoveContainer	RemoveContainerRequest	TaskActionResponse	RemoveContainer starts an async deletion for one container on one node.
GetContainerLogs	GetContainerLogsRequest	GetContainerLogsResponse stream	GetContainerLogs streams log text for one container.
OpenContainerExec	OpenContainerExecRequest	OpenContainerExecResponse	OpenContainerExec opens an interactive exec session for one container.
RunContainerExec	RunContainerExecRequest	RunContainerExecResponse	RunContainerExec runs a non-interactive exec command and returns collected output.
RemoveNetwork	RemoveNetworkRequest	TaskActionResponse	RemoveNetwork starts an async deletion for one network on one node.
RemoveVolume	RemoveVolumeRequest	TaskActionResponse	RemoveVolume starts an async deletion for one volume on one node.
RemoveImage	RemoveImageRequest	TaskActionResponse	RemoveImage starts an async deletion for one image on one node.

Top

proto/composia/controller/v1/node.proto

ContainerInfo

ContainerInfo describes one container for node-scoped 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

DockerStats

DockerStats describes the latest Docker usage snapshot for one node.

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

ForgetNodeRusticRequest

ForgetNodeRusticRequest forgets backup snapshots for one node and dataset.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
service_name	string	service_name narrows the operation to one service.
data_name	string	data_name narrows the operation to one service data entry.

ForgetNodeRusticResponse

ForgetNodeRusticResponse returns the created maintenance task ID.

Field	Type	Label	Description
task_id	string

GetNodeDockerStatsRequest

GetNodeDockerStatsRequest identifies the node whose Docker stats should be returned.

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

GetNodeDockerStatsResponse

GetNodeDockerStatsResponse returns the latest known Docker stats snapshot.

Field	Type	Label	Description
stats	DockerStats

GetNodeRequest

GetNodeRequest identifies one node by ID.

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

GetNodeResponse

GetNodeResponse returns one node summary.

Field	Type	Label	Description
node	NodeSummary		node contains the requested configured node. The RPC returns NotFound when the requested node does not exist.

ImageInfo

ImageInfo describes one Docker image for node-scoped 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.
created	string		created is the image creation timestamp string.
repo_digests	string	repeated	repo_digests lists immutable digest references for the image.
virtual_size	int64		virtual_size is the virtual image size in bytes.
architecture	string		architecture is the image CPU architecture string.
os	string		os is the image operating system string.
containers_count	uint32		containers_count is the number of containers using the image.
is_dangling	bool		is_dangling reports whether the image is dangling.
author	string		author is the image author metadata, when present.

InitNodeRusticRequest

InitNodeRusticRequest initializes the Rustic repository on one node.

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

InitNodeRusticResponse

InitNodeRusticResponse returns the created maintenance task ID.

Field	Type	Label	Description
task_id	string

InspectNodeContainerRequest

InspectNodeContainerRequest identifies one node-scoped container.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.
container_id	string		container_id is the runtime container ID.

InspectNodeContainerResponse

InspectNodeContainerResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

InspectNodeImageRequest

InspectNodeImageRequest identifies one node-scoped image.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.
image_id	string		image_id is the runtime image ID.

InspectNodeImageResponse

InspectNodeImageResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

InspectNodeNetworkRequest

InspectNodeNetworkRequest identifies one node-scoped network.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.
network_id	string		network_id is the runtime network ID.

InspectNodeNetworkResponse

InspectNodeNetworkResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

InspectNodeVolumeRequest

InspectNodeVolumeRequest identifies one node-scoped volume.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.
volume_name	string		volume_name is the runtime volume name.

InspectNodeVolumeResponse

InspectNodeVolumeResponse returns raw Docker inspect JSON.

Field	Type	Label	Description
raw_json	string

ListNodeContainersRequest

ListNodeContainersRequest identifies the node whose containers should be listed.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
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.

ListNodeContainersResponse

ListNodeContainersResponse returns node-scoped container summaries.

Field	Type	Label	Description
containers	ContainerInfo	repeated
total_count	uint32

ListNodeImagesRequest

ListNodeImagesRequest identifies the node whose images should be listed.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
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.

ListNodeImagesResponse

ListNodeImagesResponse returns node-scoped image summaries.

Field	Type	Label	Description
images	ImageInfo	repeated
total_count	uint32

ListNodeNetworksRequest

ListNodeNetworksRequest identifies the node whose networks should be listed.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
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.

ListNodeNetworksResponse

ListNodeNetworksResponse returns node-scoped network summaries.

Field	Type	Label	Description
networks	NetworkInfo	repeated
total_count	uint32

ListNodeVolumesRequest

ListNodeVolumesRequest identifies the node whose volumes should be listed.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
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.

ListNodeVolumesResponse

ListNodeVolumesResponse returns node-scoped volume summaries.

Field	Type	Label	Description
volumes	VolumeInfo	repeated
total_count	uint32

ListNodesRequest

ListNodesRequest requests all configured nodes.

ListNodesResponse

ListNodesResponse returns all configured nodes.

Field	Type	Label	Description
nodes	NodeSummary	repeated

NetworkInfo

NetworkInfo describes one Docker network for node-scoped 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

NodeActionCapabilities

NodeActionCapabilities describes whether node-scoped actions may run.

Field	Type	Label	Description
caddy_sync	Capability
caddy_reload	Capability
rustic_maintenance	Capability

NodeSummary

NodeSummary describes one configured node.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
display_name	string	display_name is the human-readable node label.
enabled	bool	enabled reports whether the node is eligible for controller actions.
is_online	bool	is_online reports whether the node has a recent heartbeat.
last_heartbeat	string	last_heartbeat is the last recorded heartbeat timestamp string.
actions	NodeActionCapabilities	actions describes whether node-scoped actions may currently run.

PruneNodeDockerRequest

PruneNodeDockerRequest prunes one Docker resource class on a node.

Field	Type	Label	Description
node_id	string		node_id is the stable node identifier.
target	string		target identifies which Docker resource group to prune.

PruneNodeDockerResponse

PruneNodeDockerResponse returns the created maintenance task ID.

Field	Type	Label	Description
task_id	string

PruneNodeRusticRequest

PruneNodeRusticRequest prunes backup data for one node and dataset.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
service_name	string	service_name narrows the operation to one service.
data_name	string	data_name narrows the operation to one service data entry.

PruneNodeRusticResponse

PruneNodeRusticResponse returns the created maintenance task ID.

Field	Type	Label	Description
task_id	string

ReloadNodeCaddyRequest

ReloadNodeCaddyRequest identifies the node whose Caddy instance should be reloaded.

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

ReloadNodeCaddyResponse

ReloadNodeCaddyResponse returns the created maintenance task ID.

Field	Type	Label	Description
task_id	string

SyncNodeCaddyFilesRequest

SyncNodeCaddyFilesRequest syncs Caddy files for one node.

Field	Type	Description
node_id	string	node_id is the stable node identifier.
service_name	string	service_name optionally narrows the sync to one service.
full_rebuild	bool	full_rebuild forces a full Caddy file rebuild instead of an incremental sync.

SyncNodeCaddyFilesResponse

SyncNodeCaddyFilesResponse returns the created maintenance task ID.

Field	Type	Label	Description
task_id	string

VolumeInfo

VolumeInfo describes one Docker volume for node-scoped 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

DockerQueryService

DockerQueryService exposes read-only Docker resource queries for one node.

Method Name	Request Type	Response Type	Description
ListNodeContainers	ListNodeContainersRequest	ListNodeContainersResponse	ListNodeContainers lists containers on one node.
InspectNodeContainer	InspectNodeContainerRequest	InspectNodeContainerResponse	InspectNodeContainer returns raw Docker inspect JSON for one container.
ListNodeNetworks	ListNodeNetworksRequest	ListNodeNetworksResponse	ListNodeNetworks lists networks on one node.
InspectNodeNetwork	InspectNodeNetworkRequest	InspectNodeNetworkResponse	InspectNodeNetwork returns raw Docker inspect JSON for one network.
ListNodeVolumes	ListNodeVolumesRequest	ListNodeVolumesResponse	ListNodeVolumes lists volumes on one node.
InspectNodeVolume	InspectNodeVolumeRequest	InspectNodeVolumeResponse	InspectNodeVolume returns raw Docker inspect JSON for one volume.
ListNodeImages	ListNodeImagesRequest	ListNodeImagesResponse	ListNodeImages lists images on one node.
InspectNodeImage	InspectNodeImageRequest	InspectNodeImageResponse	InspectNodeImage returns raw Docker inspect JSON for one image.

NodeMaintenanceService

NodeMaintenanceService triggers async maintenance work on one node.

Method Name	Request Type	Response Type	Description
SyncNodeCaddyFiles	SyncNodeCaddyFilesRequest	SyncNodeCaddyFilesResponse	SyncNodeCaddyFiles starts a task to sync Caddy files on one node.
ReloadNodeCaddy	ReloadNodeCaddyRequest	ReloadNodeCaddyResponse	ReloadNodeCaddy starts a task to reload Caddy on one node.
PruneNodeDocker	PruneNodeDockerRequest	PruneNodeDockerResponse	PruneNodeDocker starts a task to prune Docker resources on one node.
InitNodeRustic	InitNodeRusticRequest	InitNodeRusticResponse	InitNodeRustic starts a task to initialize the Rustic repository on one node.
ForgetNodeRustic	ForgetNodeRusticRequest	ForgetNodeRusticResponse	ForgetNodeRustic starts a task to forget Rustic snapshots for one node.
PruneNodeRustic	PruneNodeRusticRequest	PruneNodeRusticResponse	PruneNodeRustic starts a task to prune Rustic data on one node.

NodeQueryService

NodeQueryService exposes read-only node and node-scoped task queries.

Method Name	Request Type	Response Type	Description
ListNodes	ListNodesRequest	ListNodesResponse	ListNodes returns all configured nodes with current online state.
GetNode	GetNodeRequest	GetNodeResponse	GetNode returns one node by ID.
GetNodeDockerStats	GetNodeDockerStatsRequest	GetNodeDockerStatsResponse	GetNodeDockerStats returns the latest Docker stats snapshot for one node.

Top

proto/composia/controller/v1/repo.proto

CreateRepoDirectoryRequest

CreateRepoDirectoryRequest creates one repo-relative directory path.

Field	Type	Description
path	string	path is the repo-relative directory path to create.
base_revision	string	base_revision protects against writing on top of an unexpected HEAD.
commit_message	string	commit_message is used for the generated Git commit.

DeleteRepoPathRequest

DeleteRepoPathRequest deletes one repo-relative path.

Field	Type	Description
path	string	path is the repo-relative path to delete.
base_revision	string	base_revision protects against writing on top of an unexpected HEAD.
commit_message	string	commit_message is used for the generated Git commit.

GetRepoFileRequest

GetRepoFileRequest addresses one repo-relative file path.

Field	Type	Label	Description
path	string

GetRepoFileResponse

GetRepoFileResponse returns a repo file and its text content.

Field	Type	Description
path	string	path is the repo-relative path that was read.
content	string	content is the file content as text.
size	int64	size is the file size in bytes.

GetRepoHeadRequest

GetRepoHeadRequest requests the current controller repo state.

GetRepoHeadResponse

GetRepoHeadResponse describes the current repo state known to the controller.

Field	Type	Description
head_revision	string	head_revision is the current HEAD commit ID.
branch	string
has_remote	bool
clean_worktree	bool	clean_worktree reports whether there are uncommitted local changes.
sync_status	string	sync_status is the controller's repo sync status string.
last_sync_error	string	last_sync_error contains the most recent sync failure, when present.
last_successful_pull_at	string	last_successful_pull_at is the last successful pull timestamp string.

ListRepoCommitsRequest

ListRepoCommitsRequest pages commit history with an opaque cursor.

Field	Type	Label	Description
page_size	uint32		page_size is the requested page size.
cursor	string		cursor is an opaque pagination cursor from a previous response.

ListRepoCommitsResponse

ListRepoCommitsResponse returns one page of commits.

Field	Type	Label	Description
commits	RepoCommitSummary	repeated
next_cursor	string		next_cursor is empty when there are no more results.

ListRepoFilesRequest

ListRepoFilesRequest lists repo entries under path.

Field	Type	Label	Description
path	string		path is repo-relative. An empty path refers to the repo root.
recursive	bool		recursive includes all descendants under path when true.

ListRepoFilesResponse

ListRepoFilesResponse returns repo entries for the requested path.

Field	Type	Label	Description
entries	RepoFileEntry	repeated

MoveRepoPathRequest

MoveRepoPathRequest moves one repo-relative path to another.

Field	Type	Description
source_path	string	source_path is the existing repo-relative path to move.
destination_path	string	destination_path is the new repo-relative path.
base_revision	string	base_revision protects against writing on top of an unexpected HEAD.
commit_message	string	commit_message is used for the generated Git commit.

RepoCommitSummary

RepoCommitSummary describes one commit in repo history.

Field	Type	Description
commit_id	string
subject	string	subject is the commit subject line.
committed_at	string	committed_at is the commit timestamp string.

RepoFileEntry

RepoFileEntry describes one direct child entry in the repo tree.

Field	Type	Description
path	string	path is a repo-relative path.
name	string	name is the final path segment.
is_dir	bool	is_dir reports whether the entry is a directory.
size	int64	size is the file size in bytes. Directories may report zero.

RepoValidationError

RepoValidationError identifies one validation problem in repo content.

Field	Type	Description
path	string	path is the repo-relative path where validation failed.
line	uint32	line is the 1-based line number when the error maps to one line.
message	string	message is a human-readable validation failure description.

RepoWriteResult

RepoWriteResult reports the commit and sync result for a repo write.

Field	Type	Description
commit_id	string	commit_id is the Git commit created for the write.
sync_status	string	sync_status is the repo sync state after the write.
push_error	string	push_error contains the last push error when sync_status is failed.
last_successful_pull_at	string	last_successful_pull_at is the last successful pull timestamp string.

SyncRepoRequest

SyncRepoRequest asks the controller to refresh repo state from its remote.

SyncRepoResponse

SyncRepoResponse returns the repo state after a sync attempt.

Field	Type	Description
head_revision	string	head_revision is the current HEAD commit ID after the sync attempt.
branch	string	branch is the currently checked out branch name.
sync_status	string	sync_status is the repo sync state after the sync attempt.
last_sync_error	string	last_sync_error contains the most recent sync failure, when present.
last_successful_pull_at	string	last_successful_pull_at is the last successful pull timestamp string.

UpdateRepoFileRequest

UpdateRepoFileRequest writes one file at a repo-relative path.

Field	Type	Description
path	string	path is the repo-relative path to update.
content	string	content is the full replacement file content.
base_revision	string	base_revision protects against writing on top of an unexpected HEAD.
commit_message	string	commit_message is used for the generated Git commit.

ValidateRepoRequest

ValidateRepoRequest asks the controller to validate repo content.

ValidateRepoResponse

ValidateRepoResponse returns all repo validation problems found.

Field	Type	Label	Description
errors	RepoValidationError	repeated

RepoCommandService

RepoCommandService applies changes to the controller Git repo.

Method Name	Request Type	Response Type	Description
UpdateRepoFile	UpdateRepoFileRequest	RepoWriteResult	UpdateRepoFile writes one file, creates a commit, and reports sync state.
CreateRepoDirectory	CreateRepoDirectoryRequest	RepoWriteResult	CreateRepoDirectory creates one directory, creates a commit, and reports sync state.
MoveRepoPath	MoveRepoPathRequest	RepoWriteResult	MoveRepoPath moves or renames one repo path.
DeleteRepoPath	DeleteRepoPathRequest	RepoWriteResult	DeleteRepoPath deletes one repo path.
SyncRepo	SyncRepoRequest	SyncRepoResponse	SyncRepo pulls or syncs the repo and returns the resulting state snapshot.

RepoQueryService

RepoQueryService exposes read-only views of the controller Git repo.

Method Name	Request Type	Response Type	Description
GetRepoHead	GetRepoHeadRequest	GetRepoHeadResponse	GetRepoHead returns current HEAD and sync metadata.
ListRepoFiles	ListRepoFilesRequest	ListRepoFilesResponse	ListRepoFiles lists direct children for one repo path.
GetRepoFile	GetRepoFileRequest	GetRepoFileResponse	GetRepoFile returns the content of one repo file.
ListRepoCommits	ListRepoCommitsRequest	ListRepoCommitsResponse	ListRepoCommits returns commit history using cursor pagination.
ValidateRepo	ValidateRepoRequest	ValidateRepoResponse	ValidateRepo runs repo validation and returns structured errors.

Top

proto/composia/controller/v1/secret.proto

GetSecretRequest

GetSecretRequest identifies one decrypted secret file for a service.

Field	Type	Label	Description
service_name	string
file_path	string
service_dir	string

GetSecretResponse

GetSecretResponse returns one decrypted secret file.

Field	Type	Label	Description
service_name	string
file_path	string
content	string

UpdateSecretRequest

UpdateSecretRequest writes one decrypted secret file for a service.

Field	Type	Description
service_name	string
file_path	string	file_path is the repo-relative secret file path for the service.
content	string	content is the full decrypted secret file content to store.
base_revision	string	base_revision protects against writing on top of an unexpected HEAD.
commit_message	string	commit_message is used for the generated Git commit.
service_dir	string

SecretService

SecretService reads and updates encrypted secret files stored in the repo.

Method Name	Request Type	Response Type	Description
GetSecret	GetSecretRequest	GetSecretResponse	GetSecret returns the decrypted content for one service secret file.
UpdateSecret	UpdateSecretRequest	RepoWriteResult	UpdateSecret writes one secret file and reports the resulting repo sync state.

Top

proto/composia/controller/v1/service.proto

GetServiceImageUpdateChecksRequest

GetServiceImageUpdateChecksRequest identifies one service and optional node.

Field	Type	Label	Description
service_name	string
node_id	string

GetServiceImageUpdateChecksResponse

GetServiceImageUpdateChecksResponse returns latest image update checks.

Field	Type	Label	Description
checks	ServiceImageUpdateCheckSummary	repeated

GetServiceInstanceRequest

GetServiceInstanceRequest identifies one service instance by service and node.

Field	Type	Description
service_name	string	service_name is the logical service name.
node_id	string	node_id identifies the node hosting the requested instance.
include_containers	bool	include_containers includes instance container details when true.

GetServiceInstanceResponse

GetServiceInstanceResponse returns one service instance detail.

Field	Type	Label	Description
instance	ServiceInstanceDetail		instance contains the requested service instance. The RPC returns NotFound when the requested instance does not exist.

GetServiceRequest

GetServiceRequest addresses one service by logical name.

Field	Type	Label	Description
service_name	string		service_name is the logical service name.
include_containers	bool		include_containers includes per-instance container details when true.

GetServiceResponse

GetServiceResponse describes one service and all known instances.

Field	Type	Label	Description
name	string
runtime_status	string		runtime_status is the controller's aggregated status string.
updated_at	string		updated_at is the last known status update timestamp string.
nodes	string	repeated	nodes lists the declared target nodes for this service.
enabled	bool		enabled reports the desired-state enabled flag for this service.
directory	string		directory is the service directory inside the repo.
instances	ServiceInstanceDetail	repeated	instances lists per-node runtime details known to the controller.
actions	ServiceActionCapabilities		actions describes whether service-scoped actions may currently run.

GetServiceWorkspaceRequest

GetServiceWorkspaceRequest identifies one top-level service workspace folder.

Field	Type	Label	Description
folder	string

GetServiceWorkspaceResponse

GetServiceWorkspaceResponse returns one top-level repo service workspace.

Field	Type	Label	Description
workspace	ServiceWorkspaceSummary

ImageUpdateSelection

ImageUpdateSelection identifies one configured image update to apply.

Field	Type	Label	Description
image_name	string
target_tag	string
use_detected	bool

ListServiceInstancesRequest

ListServiceInstancesRequest addresses one service by logical name.

Field	Type	Label	Description
service_name	string		service_name is the logical service name.

ListServiceInstancesResponse

ListServiceInstancesResponse returns known instances for one service.

Field	Type	Label	Description
instances	ServiceInstanceSummary	repeated

ListServiceWorkspacesRequest

ListServiceWorkspacesRequest requests all top-level service workspaces.

ListServiceWorkspacesResponse

ListServiceWorkspacesResponse returns top-level repo service workspaces.

Field	Type	Label	Description
workspaces	ServiceWorkspaceSummary	repeated

ListServicesRequest

ListServicesRequest filters services by runtime status and page.

Field	Type	Description
runtime_status	string	runtime_status narrows results to one aggregated status string when set.
page_size	uint32	page_size is the requested page size.
page	uint32	page is the 1-based page number.

ListServicesResponse

ListServicesResponse returns one page of service summaries.

Field	Type	Label	Description
services	ServiceSummary	repeated
total_count	uint32		total_count is the total number of matches before pagination.

MigrateServiceRequest

MigrateServiceRequest moves a service from one node to another.

Field	Type	Description
service_name	string
source_node_id	string	source_node_id identifies the current source node.
target_node_id	string	target_node_id identifies the destination node.

RunServiceActionRequest

RunServiceActionRequest starts an async action for a service.

Field	Type	Label	Description
service_name	string		service_name is the logical service name.
action	ServiceAction		action is the async operation to start.
node_ids	string	repeated	node_ids optionally narrows the action to selected nodes.
data_names	string	repeated	data_names narrows backup-like actions to selected data entries.
compose_recreate_mode	ComposeRecreateMode		compose_recreate_mode controls deploy/update container recreation behavior.
image_updates	ImageUpdateSelection	repeated	image_updates applies selected configured image updates before running update.
use_all_detected_image_updates	bool		use_all_detected_image_updates applies every detected image update for the service.
backup_before_update	bool	optional	backup_before_update overrides the service config cascade for this request.
base_revision	string		base_revision protects repo-backed image updates against stale HEAD writes.
commit_message	string		commit_message is used for repo-backed image update commits.

RunServiceActionResponse

RunServiceActionResponse returns every queued task and any repo write side effect.

Field	Type	Label	Description
tasks	TaskActionResponse	repeated
repo_write	RepoWriteResult

ServiceActionCapabilities

ServiceActionCapabilities describes whether service-scoped actions may run.

Field	Type	Label	Description
backup	Capability
restore	Capability
migrate	Capability
dns_update	Capability
caddy_sync	Capability
cloudflare_tunnel_sync	Capability

ServiceContainerSummary

ServiceContainerSummary describes one container belonging to a service instance.

Field	Type	Description
container_id	string	container_id is the runtime container ID.
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.
compose_project	string	compose_project is the Compose project label, when present.
compose_service	string	compose_service is the Compose service label, when present.

ServiceImageUpdateCheckSummary

ServiceImageUpdateCheckSummary describes the latest update check for one configured image.

Field	Type	Label
service_name	string
node_id	string
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
checked_at	string

ServiceInstanceDetail

ServiceInstanceDetail extends the instance summary with container details.

Field	Type	Label	Description
service_name	string		service_name is the logical service name.
node_id	string		node_id identifies the node hosting this instance.
runtime_status	string		runtime_status is the controller's current status string for this instance.
updated_at	string		updated_at is the last known status update timestamp string.
is_declared	bool		is_declared reports whether this instance is part of desired state.
containers	ServiceContainerSummary	repeated	containers lists runtime containers currently associated with the instance.
pending_deploy_revision	string		pending_deploy_revision is set when a repo change affects this service and a deploy is pending.

ServiceInstanceSummary

ServiceInstanceSummary describes one service instance on one node.

Field	Type	Description
service_name	string	service_name is the logical service name.
node_id	string	node_id identifies the node hosting this instance.
runtime_status	string	runtime_status is the controller's current status string for this instance.
updated_at	string	updated_at is the last known status update timestamp string.
is_declared	bool	is_declared reports whether this instance is part of desired state.
pending_deploy_revision	string	pending_deploy_revision is set when a repo change affects this service and a deploy is pending.

ServiceSummary

ServiceSummary describes one service for list views.

Field	Type	Description
name	string	name is the logical service name.
is_declared	bool	is_declared reports whether the service exists in desired state.
runtime_status	string	runtime_status is the controller's aggregated status string.
updated_at	string	updated_at is the last known status update timestamp string.
instance_count	uint32	instance_count is the number of known service instances.
running_count	uint32	running_count is the number of running service instances.
target_node_count	uint32	target_node_count is the number of declared target nodes.

ServiceWorkspaceSummary

ServiceWorkspaceSummary describes one top-level repo workspace and any merged service state.

Field	Type	Label	Description
folder	string		folder is the repo-relative top-level folder name for this workspace.
display_name	string		display_name is the preferred workspace label for operator-facing lists.
service_name	string		service_name is empty until the workspace has a parseable service name.
has_meta	bool		has_meta reports whether composia-meta.yaml exists in the workspace.
is_declared	bool		is_declared reports whether this workspace currently maps to a declared controller service.
runtime_status	string		runtime_status is the merged controller status or a workspace-local placeholder.
updated_at	string		updated_at is the last known controller update timestamp string.
nodes	string	repeated	nodes lists declared target nodes when the workspace meta is parseable.
enabled	bool		enabled reports the desired-state enabled flag when the workspace meta is parseable.
actions	ServiceActionCapabilities		actions describes whether service-scoped actions may currently run.

ComposeRecreateMode

ComposeRecreateMode controls whether docker compose up recreates containers.

Name	Number	Description
COMPOSE_RECREATE_MODE_UNSPECIFIED	0	COMPOSE_RECREATE_MODE_UNSPECIFIED uses the default automatic behavior.
COMPOSE_RECREATE_MODE_AUTO	1	COMPOSE_RECREATE_MODE_AUTO recreates when bind mounts need refreshed.
COMPOSE_RECREATE_MODE_NO_RECREATE	2	COMPOSE_RECREATE_MODE_NO_RECREATE runs docker compose up without forcing recreation.
COMPOSE_RECREATE_MODE_FORCE_RECREATE	3	COMPOSE_RECREATE_MODE_FORCE_RECREATE always passes –force-recreate.

ServiceAction

ServiceAction identifies an async action that targets a service.

Name	Number	Description
SERVICE_ACTION_UNSPECIFIED	0	SERVICE_ACTION_UNSPECIFIED is invalid and should not be used.
SERVICE_ACTION_DEPLOY	1	SERVICE_ACTION_DEPLOY creates or reconciles the service on target nodes.
SERVICE_ACTION_UPDATE	2	SERVICE_ACTION_UPDATE refreshes the running service from desired state.
SERVICE_ACTION_STOP	3	SERVICE_ACTION_STOP stops the service.
SERVICE_ACTION_RESTART	4	SERVICE_ACTION_RESTART restarts the service.
SERVICE_ACTION_BACKUP	5	SERVICE_ACTION_BACKUP triggers a backup task.
SERVICE_ACTION_DNS_UPDATE	6	SERVICE_ACTION_DNS_UPDATE refreshes DNS records for the service.
SERVICE_ACTION_CADDY_SYNC	7	SERVICE_ACTION_CADDY_SYNC syncs related Caddy configuration.
SERVICE_ACTION_CLOUDFLARE_TUNNEL_SYNC	8	SERVICE_ACTION_CLOUDFLARE_TUNNEL_SYNC syncs related Cloudflare Tunnel configuration.

ServiceCommandService

ServiceCommandService triggers service-level state changes and async actions.

Method Name	Request Type	Response Type	Description
RunServiceAction	RunServiceActionRequest	RunServiceActionResponse	RunServiceAction starts an async action for a service and returns all created tasks.
MigrateService	MigrateServiceRequest	TaskActionResponse	MigrateService starts an async service migration between two nodes.

ServiceInstanceService

ServiceInstanceService queries and operates on one concrete service instance.

Method Name	Request Type	Response Type	Description
ListServiceInstances	ListServiceInstancesRequest	ListServiceInstancesResponse	ListServiceInstances lists all instances for one service.
GetServiceInstance	GetServiceInstanceRequest	GetServiceInstanceResponse	GetServiceInstance returns the detail for one service instance on one node.

ServiceQueryService

ServiceQueryService exposes read-only service workspace, declared service, task, and backup queries.

Method Name	Request Type	Response Type	Description
ListServices	ListServicesRequest	ListServicesResponse	ListServices returns declared services with pagination.
ListServiceWorkspaces	ListServiceWorkspacesRequest	ListServiceWorkspacesResponse	ListServiceWorkspaces returns top-level repo service workspaces with merged controller state.
GetService	GetServiceRequest	GetServiceResponse	GetService returns the full detail for a single service.
GetServiceWorkspace	GetServiceWorkspaceRequest	GetServiceWorkspaceResponse	GetServiceWorkspace returns one top-level repo service workspace.
GetServiceImageUpdateChecks	GetServiceImageUpdateChecksRequest	GetServiceImageUpdateChecksResponse	GetServiceImageUpdateChecks returns latest configured image update checks for one service.

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

Agent Internal Reference Source Build