Admin API

Table of Contents

• Admin Service API

• Scalar Value Types

Admin Service API (admin/admin.proto)

Services

AdminService

Method Name	Request Type	Response Type	Description
RegisterService	RegistryRequest	RegistryResponse	Register a remote agent or service
StartApplication	ApplicationRequest	StartResponse	Start a remote application
StartVM	StartVMRequest	StartResponse	Start a VM
StartService	StartServiceRequest	StartResponse	Start a remote service
PauseApplication	ApplicationRequest	ApplicationResponse	Pause (freeze) a remote application
ResumeApplication	ApplicationRequest	ApplicationResponse	Resume (un-freeze) a remote application
StopApplication	ApplicationRequest	ApplicationResponse	Stop a remote application
SetLocale	LocaleRequest	Empty	Set locale (broadcasted across system)
SetTimezone	TimezoneRequest	Empty	Set timezone (broadcasted across system)
Poweroff	Empty	Empty	System poweroff command
Reboot	Empty	Empty	System reboot command
Suspend	Empty	Empty	System suspend command
Wakeup	Empty	Empty	System wakeup command
GetUnitStatus	UnitStatusRequest	.systemd.UnitStatus	Get systemd unit status
GetStats	StatsRequest	.stats.StatsResponse	Get stats information
QueryList	Empty	QueryListResponse	Get list of monitored units
Watch	Empty	WatchItem	Get stream of monitored units
ListGenerations	Empty	ListGenerationsResponse	OTA
SetGeneration	SetGenerationRequest	SetGenerationResponse
NotifyUser	UserNotificationRequest	.notify.Status	Send user notification
Ctap	.ctap.CtapRequest	.ctap.CtapResponse	Perform CTAP action
Sysinfo	Empty	.stats.SysinfoResponse	Get host sysinfo values in one call

Messages

ApplicationRequest

Field	Type	Label	Description
AppName	string		Application name
VmName	string	optional	Name of the VM hosting the application
Args	string	repeated	Application arguments

ApplicationResponse

Field	Type	Label	Description
CmdStatus	string		Status of the RPC command
AppStatus	string		Status of the application

Cachix

Field	Type	Label	Description
Pin	string
CachixHost	string	optional	API url for cachix
Cache	string
Token	string	optional

CtapRequest

Field	Type	Label	Description
Req	string
Args	string	repeated
Payload	bytes

CtapResponse

Field	Type	Label	Description
Output	bytes

Empty

Empty message

Generation

Field	Type	Label	Description
Generation	int32
Date	string
NixosVersion	string
KernelVersion	string
ConfigurationRevision	string
Specialisations	string	repeated
Current	bool
StorePath	string

ListGenerationsResponse

Field	Type	Label	Description
List	Generation	repeated

LocaleRequest

Field	Type	Label	Description
assignments	locale.LocaleAssignment	repeated	List of locale assignments

QueryListItem

Field	Type	Label	Description
Name	string		Name of the unit
Description	string		Description of the unit
VmStatus	string		Status of the VM hosting the unit
TrustLevel	string		Trust Level (future use)
VmType	string		Type of the VM (future use)
ServiceType	string		Type of the service (future use)
VmName	string	optional	Name of the VM to query; None for host running services
AgentName	string	optional	Name of the managing agent; None for agents

QueryListResponse

Field	Type	Label	Description
List	QueryListItem	repeated	List of query responses

RegistryRequest

Field	Type	Label	Description
Name	string		Component name for registry entry
Parent	string		Parent component identifier (registry name)
Type	uint32		Component type
Transport	TransportConfig		TransportConfig
State	systemd.UnitStatus		Unit status of the component (systemd)

RegistryResponse

Field	Type	Label	Description
Error	string	optional	Error message

SetGenerationRequest

Field	Type	Label	Description
Cachix	Cachix

SetGenerationResponse

Field	Type	Label	Description
Finished	bool
Output	string	optional
Error	string	optional

StartResponse

Field	Type	Label	Description
registryId	string		Registry ID for newly started app, service or vm

StartServiceRequest

Field	Type	Label	Description
ServiceName	string		Name of the service to start
VmName	string		Name of the VM hosting service

StartVMRequest

Field	Type	Label	Description
VmName	string		Name of the VM to start

StatsRequest

Field	Type	Label	Description
VmName	string		VM name to query status information

TimezoneRequest

Field	Type	Label	Description
Timezone	string		String with timezone value. Format: tz database name, usually Area/City or Etc/GMT+3.

TransportConfig

Field	Type	Label	Description
Protocol	string		Protocol identifier, one of tcp, vsock, unix
Address	string		IPv4 address, vsock CID, or unix socket path
Port	string		Port number
Name	string		Host name

UnitStatusRequest

Field	Type	Label	Description
VmName	string		Name of the VM hosting the unit
UnitName	string		Name of the unit

UserNotificationRequest

Field	Type	Label	Description
VmName	string
Notification	notify.UserNotification

WatchItem

Field	Type	Label	Description
Initial	QueryListResponse
Added	QueryListItem
Updated	QueryListItem
Removed	QueryListItem

Scalar Value Types

.proto Type	Notes	Go Type
double		float64
float		float32
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64
uint32	Uses variable-length encoding.	uint32
uint64	Uses variable-length encoding.	uint64
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64
sfixed32	Always four bytes.	int32
sfixed64	Always eight bytes.	int64
bool		bool
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string
bytes	May contain any arbitrary sequence of bytes.	[]byte