gRPC API

The gRPC API is used only by tyrd. Human operators use the REST API. See proto/agent.proto and proto/events.proto for the canonical definitions.

Endpoint

• Host: <server>:7700
• Transport: HTTP/2 with mTLS. Agent must present a client certificate issued during enrollment.
• Protocol: gRPC.

Services

AgentService.Register

One-shot RPC. First-boot bootstrap.

rpc Register(RegisterRequest) returns (RegisterResponse);

message RegisterRequest {
  string agent_name = 1;
  string enrollment_token = 2;
  bytes  csr_pem = 3;         // PKCS#10 CSR generated by tyrd
  string kernel_version = 4;
  string arch = 5;            // "x86_64" or "aarch64"
}

message RegisterResponse {
  string agent_id = 1;         // UUID
  bytes  client_cert_pem = 2;  // signed by server CA
  bytes  ca_cert_pem = 3;
}

This is the only RPC that uses the enrollment token instead of mTLS. Used once per agent.

AgentService.Stream

Bidirectional persistent stream. This is where all runtime traffic happens.

rpc Stream(stream AgentMessage) returns (stream ServerMessage);

message AgentMessage {
  oneof payload {
    Heartbeat        heartbeat        = 1;
    EventBatch       event_batch      = 2;
    CapabilityReport capabilities     = 3;
  }
}

message ServerMessage {
  oneof payload {
    PolicyPush       policy           = 1;
    PingRequest      ping             = 2;
    ConfigUpdate     config           = 3;
  }
}

Connection lifecycle

1. tyrd starts → presents client cert → opens Stream.
2. Sends CapabilityReport (kernel version, which hooks it supports).
3. Server responds with PolicyPush containing the effective policy.
4. tyrd streams EventBatch messages (buffered, 100 events or 1s, whichever first).
5. Server responds occasionally with PolicyPush (when a reassignment happens).
6. Heartbeat every heartbeat_interval_s (default 30s).
7. On server restart: agent reconnects with exponential backoff. Events buffered during disconnect replay on reconnect.

Event format

Sent in EventBatch:

message Event {
  string event_id = 1;        // UUID v7
  string agent_id = 2;        // populated server-side
  string discovered_agent_id = 3;
  EventKind kind = 4;         // FILE_READ, FILE_WRITE, EXEC, NET_CONNECT, TLS
  string resource = 5;
  Verdict verdict = 6;        // ALLOW, DENY, ALERT
  Severity severity = 7;
  int64  pid = 8;
  string process_exe = 9;
  string cmdline = 10;
  int64  timestamp_ns = 11;
  map<string,string> metadata = 12;
}

Policy push

message PolicyPush {
  int64 policy_version = 1;       // monotonic
  bytes bpf_entries = 2;          // flat serialized map entries
  string cedar_text = 3;          // Cedar source for userspace evaluator
  repeated OverlayInfo overlays = 4;
}

The agent swaps the BPF maps atomically — no dropped syscall checks during hot-reload.

Backward compatibility

• Unknown fields are ignored on both sides (proto3 semantics).
• CapabilityReport lets the server gate features — a v0.5 agent without tls_capture support simply won’t be asked for TLS events.
• Breaking proto changes are documented in release notes.

Troubleshooting

• Handshake failure / UNAVAILABLE — usually cert/CA mismatch. Check /etc/tyr/ca.pem matches server’s /api/v1/ca.pem.
• UNAUTHENTICATED on first Register — enrollment token consumed, expired, or wrong.
• Stream drops every few seconds — network MTU issues or a proxy that doesn’t support HTTP/2 trailers.

→ Next: Architecture · REST API