API Architecture & Protocols

PiVirt exposes modern, high-performance APIs through multiple protocols tailored for cloud orchestration, internal service meshes, and web clients.

API Protocols

GraphQL (Console)

Transport: HTTP POST at /graphql; WebSocket (graphql-transport-ws) for subscriptions
Auth: SSO bearer token; console tickets for the VNC/serial routes
Scope: the director only — tenant root project(id), operator root admin; every mutation returns a Task
See GraphQL API

ConnectRPC (Primary)

Transport: HTTP/2 with gRPC-Web fallback
Encoding: Protobuf (binary) + JSON (browser)
Auth: mTLS with PiTrust certificates
Features: Unary, server/client/bidirectional streaming
Endpoint: https://agent.pilab.hu:8443

gRPC (Internal)

Transport: Raw HTTP/2
Used for: pivirtd ↔ agent, iscsiman ↔ agent
Auth: mTLS with service-specific certificates
Endpoints:
- pivirtd: localhost:9001
- iscsiman: localhost:9002

REST/HTTP (Web UIs)

Transport: HTTP/1.1 or HTTP/2
Encoding: JSON
Auth: OIDC/JWT tokens
Endpoint: https://agent.pilab.hu:8443/api/v1

API Services

Service	Package	Description
VMService	`pivirt.vm.v1`	Virtual machine lifecycle
StorageService	`pivirt.storage.v1`	Storage volume management
NetworkService	`pivirt.network.v1`	Network configuration
ClusterService	`pivirt.cluster.v1`	Cluster management
NodeService	`pivirt.node.v1`	Node management
AuthService	`pivirt.auth.v1`	Authentication & authorization

API Versioning

PiVirt uses semantic versioning for APIs:

pivirt.<service>.v<major>.<minor>

Example: pivirt.vm.v1.VirtualMachine

API Documentation

Proto Files

Proto files are located in the virtpb repository:

virtpb/proto/pilab/
├── agent/v1/        # Agent v1 services
├── agent/v2/        # Agent v2 services
├── pivirtd/v1/      # Hypervisor daemon
├── director/v1/     # Director v1 (deprecated)
├── director/v2/     # Director v2 (task queue)
├── frontend/v1/     # Web frontend API
├── cli/v1/          # CLI API
├── ws/v1/           # WebSocket events
├── network/v2/      # Virtual networking
└── common/v1/       # Shared messages

Generated Code

Generated code is available in the virtpb module:

Go: go.pilab.hu/cloud/virtpb/pilab/...
Proto definitions: virtpb/proto/pilab/...

Authentication

ConnectRPC/gRPC

# Using mTLS
grpcurl \
  -cert ~/.config/pvcli/client.crt \
  -key ~/.config/pvcli/client.key \
  -cacert ~/.config/pvcli/ca.crt \
  agent.pilab.hu:8443 \
  pivirt.vm.v1.VMService/ListVMs

REST/HTTP

# Using JWT token
curl -H "Authorization: Bearer $TOKEN" \
  https://agent.pilab.hu:8443/api/v1/vms

Rate Limiting

# agent config
server:
  connectrpc:
    rate_limit:
      enabled: true
      requests_per_second: 100
      burst: 200

Error Handling

Error Codes

Code	Description
`OK`	Success
`INVALID_ARGUMENT`	Invalid request parameters
`NOT_FOUND`	Resource not found
`ALREADY_EXISTS`	Resource already exists
`PERMISSION_DENIED`	Insufficient permissions
`INTERNAL`	Internal server error
`UNAVAILABLE`	Service unavailable

Error Response

{
  "code": 5,
  "message": "VM not found",
  "details": [
    {
      "@type": "type.googleapis.com/pivirt.ErrorDetail",
      "resource": "virtualmachine",
      "name": "web-01",
      "namespace": "production"
    }
  ]
}

SDKs

Go

import "go.pilab.hu/cloud/virtpb/pilab/agent/v1"

client, err := vm.NewVMServiceClient(conn)
vms, err := client.ListVMs(ctx, &vm.ListVMsRequest{})

TypeScript

import { VMServiceClient } from '@pilab/pivirt';

const client = new VMServiceClient('https://agent.pilab.hu:8443');
const vms = await client.listVMs({});

Python

from pivirt.vm.v1 import VMServiceClient

client = VMServiceClient('https://agent.pilab.hu:8443')
vms = client.list_vms()