vantage-docs/docs/reference/grpc-api.md

id, title, sidebar_label

id	title	sidebar_label
grpc-api	gRPC API	gRPC API

The agent-facing API, on port 9090, over TLS. Agents dial out to it; nothing dials an agent.

Service

service Vantage {
  rpc Register(RegisterRequest)              returns (RegisterResponse);
  rpc SyncKeys(SyncRequest)                  returns (SyncResponse);
  rpc UploadGeneratedKey(UploadKeyRequest)   returns (UploadKeyResponse);
  rpc ReportUpdates(ReportUpdatesRequest)    returns (ReportUpdatesResponse);
  rpc ReportInventory(InventoryReport)       returns (InventoryReportResponse);
  rpc SyncMonitors(SyncMonitorsRequest)      returns (SyncMonitorsResponse);
  rpc ReportChecks(ReportChecksRequest)      returns (ReportChecksResponse);
  rpc CommandStream(stream AgentMessage)     returns (stream ServerCommand);
}

The full message definitions live in proto/vantage/v1/vantage.proto.

Authentication

Register presents the single-use, one-hour pre-registration token and receives a permanent agent token. Every other call presents that agent token.

The control plane stores only the SHA-256 of the agent token. The plaintext exists in the agent's 0600 config file and nowhere else, so a token cannot be read back out of the control plane.

Unary calls

RPC	Direction	Frequency
Register	once, at enrolment	once
SyncKeys	agent asks for desired key state	every 30s (poll_interval)
UploadGeneratedKey	agent returns a keypair it generated	on demand
ReportUpdates	pending OS package updates	hourly
ReportInventory	CPU, memory, disk, kernel	metrics 30s, static 15 min
SyncMonitors	agent asks which checks it should run	periodically
ReportChecks	agent returns check results	after each check cycle

SyncKeys doubles as the heartbeat. A server that stops calling it is marked offline by a sweep that runs every two minutes.

The command stream

CommandStream is the only streaming RPC and the only push path.

sequenceDiagram
    participant A as Agent
    participant S as Server
    A->>S: AgentReady (authenticate)
    S-->>A: ServerCommand (RunStepCmd)
    A-->>S: StepOutputChunk (repeated)
    A-->>S: StepResult
    S-->>A: ServerCommand (CleanupWorkspaceCmd)
    A-->>S: CommandResult

The agent authenticates once with AgentReady, then the server pushes commands and the agent replies with CommandResult, StepResult or StepOutputChunk.

Commands

Command	Effect
GenerateKeyCmd	Generate an SSH keypair on the machine
DeleteKeyCmd	Remove a generated key by label
UpdateAgentCmd	Download and replace the agent binary with a target version
ApplyUpdatesCmd	Apply pending OS package updates
RunStepCmd	Execute one workflow step
CleanupWorkspaceCmd	Recursively remove the run's working directory

Why poll for keys and push for commands

A 30-second delay on a key change is fine, and polling needs no reconnection logic to survive a dropped link. Clicking Run on a workflow and waiting up to 30 seconds is not fine. Hence one of each.

Network requirements

Every managed machine needs outbound TCP to GRPC_HOST. Nothing needs to reach the machine. Watch for middleboxes that permit the short Register call but drop the long-lived command stream — that failure looks like a server that registers and then goes offline.