Skip to content

API reference

Weft's API surface is gRPC, defined in weft-proto. Every CLI command, every driver plugin, every dashboard call ultimately speaks gRPC against a weft agent. The REST surface is a typed generated layer for the browser dashboard ; it doesn't expose anything the gRPC surface doesn't.

For a short tour, see API overview. The page below is the in-depth reference.

gRPC surface — weft-proto

Source : openweft/weft-proto.

The proto repo defines :

  • Service contracts — one per resource family (ProjectService, MicrovmService, VolumeService, NetworkService, SecurityGroupService, HostService, ImageService, ScriptService, FlavorService, EventService, AdminService, AuthService).
  • Message types — request / response payloads, resource messages, shared enums.
  • Streaming RPCs — EventService.Subscribe and the per-VM event streams the CLI / dashboard subscribe to.

Generated Go stubs are committed under weft-proto/gen/. Other-language stubs (TypeScript, Python) are generated on demand — see the Taskfile.yml in the proto repo.

Driver plugin surface — weft-driver-plugin

The contract between weft-agent and the hypervisor drivers is a separate proto module : openweft/weft-driver-plugin. Implementing a new hypervisor driver means satisfying the four services this module declares :

  • HypervisorService — VM lifecycle (Create / Start / Stop / Remove, event stream).
  • NetworkService — driver-side network resource creation (per-driver TAP / virtio-net setup).
  • VolumeService — driver-side volume mount / unmount.
  • ImageService — driver-side image fetch + materialise.

Drivers are go-plugin subprocesses ; the agent dials them over a unix socket. See Architecture : data plane for the plugin lifecycle.

Networking control-plane surface — weft-network-proto

openweft/weft-network-proto defines the gRPC service the weft-network daemon exposes :

  • RouterService — router lifecycle.
  • LoadBalancerService — LB lifecycle, including health checks.
  • DNSService — DNS zone + record management.
  • SchedulingRuleService — placement / anti-affinity / DC pinning.

weft-agent dials it to fetch desired state ; the dashboard's networking panels dial it directly through the agent's RPC proxy.

REST surface — weft-webui (huma)

The dashboard generates its REST API from Go using huma. The committed spec lives at weft-webui/web/openapi.json (~277 kB, tracked as linguist-generated=true).

  • TypeScript client : web/api.gen.ts (generated by openapi-typescript + openapi-fetch).
  • Regenerate after a contract change : task gen-api in the weft-webui repo.

The REST surface is dashboard-only. External integrations should use the gRPC contract directly — it's the canonical surface, has the streaming RPCs, and is the source of truth.

Authentication

OIDC, JWT-based. Tokens issued by dex (or your federated IdP) and carried in the gRPC metadata authorization: Bearer <jwt> header. See Security.

The CLI acquires tokens via weft login and caches them under $XDG_CONFIG_HOME/weft/credentials.json. The Terraform provider reads the same cache, or accepts an explicit token.

Live events

weft events --vm <name> (CLI) and the dashboard's per-VM activity feed both subscribe to the same NATS event bus. Subjects are scoped per-VM ; the agent forwards them to clients over the EventService.Subscribe streaming RPC, no direct NATS exposure.

Gap tracking

The Terraform provider's coverage of the gRPC contract is tracked in terraform-provider-weft/GAPS.md. That file is the operator-relevant scoreboard — if a field is in proto and missing from Terraform, GAPS.md is where it lives until a PR closes the gap.

Transport layers

weft-agent accepts gRPC over three transport flavours, depending on where the caller is :

Transport When Source
unix:// Local CLI on the same host. Standard gRPC-go.
tcp:// (mTLS) Cross-host CLI, dashboard, Terraform, other agents. Standard gRPC-go.
SSH-multiplexed weft up driving a freshly-installed agent. grpc-transports/ssh.
WireGuard tunnel Cross-cluster federation (roadmap). grpc-transports/wireguard.

The SSH and WireGuard transports are vendored from the grpc-transports org — separate projects with their own release cadence.

Cross-references