gVisor - uRPC
In gVisor, uRPC (Micro RPC) is a custom, lightweight Remote Procedure Call protocol used for control-plane communication between runsc management processes and the running sandbox components (the Sentry and Gofer).
To understand why uRPC exists, it is important to distinguish gVisor's Control Plane from its Data/Filesystem Plane.
Control Plane vs. Filesystem Plane
gVisor splits inter-process communication into two distinct categories:
- The Control Plane (uRPC): Used by
runscCLI subcommands (likerunsc start,runsc exec,runsc kill,runsc pause, andrunsc checkpoint) to issue management commands to the Sentry (runsc-sandbox) or Gofer (runsc-gofer) over a Unix Domain Socket (the control socket). - The Filesystem Plane (LISAFS / Directfs): Used for file operations between the Sentry and Gofer (previously handled by legacy 9P). LISAFS handles file metadata, directory walks, and byte transfers via shared-memory ring buffers.
What Exactly is pkg/urpc?
pkg/urpc is a minimalist RPC framework implemented in Go on top of pkg/unet (gVisor's internal Unix domain socket package).
- Sequential Dispatch: Unlike general-purpose network RPC systems that manage large concurrency pools,
urpchandlers process requests sequentially per connection, keeping state synchronization predictable and lightweight. - Low Overhead: Designed strictly for local host IPC over Unix domain sockets rather than TCP networks. It avoids heavy dependencies like HTTP/2, Protobuf, or gRPC runtime scaffolding.
- File Descriptor Passing Support: Crucially,
urpcsupports passing raw host file descriptors alongside RPC messages via LinuxSCM_RIGHTSancillary data.
Why not use standard net/rpc?
A primary reason gVisor developed urpc instead of using Go's standard library net/rpc is File Descriptor Passing:
- Go's standard
net/rpconly serializes and transmits encoded data payloads (such as JSON or Gob) across sockets. - In gVisor's architecture, the host-side
runscsupervisor frequently needs to pass open OS file descriptors (such as stdio pipes, terminal PTY file descriptors, cgroup handles, or namespaces) across the Unix socket into the Sentry or Gofer. pkg/urpcintegrates directly withpkg/unetto transfer file descriptors viaSCM_RIGHTSalongside the RPC payloads.
Common uRPC Services in gVisor
Inside runsc/boot, the Sentry exposes several uRPC control services:
containerManager(boot.containerManager): Handles container lifecycle RPCs:CreateSubcontainer: Creates a subcontainer within an existing pod sandbox.StartRoot: Starts the root application container.StartExec: Launches anexecprocess inside an already running container.Wait/WaitPID: Waits for a container or specific PID to exit.Signal/SignalContainer: Dispatches POSIX signals to sandboxed processes.
lifecycle/state: Manages sandbox pausing, resuming, and checkpoint/restore operations.debug: Provides runtime introspection, dumping goroutine stacks, or controlling tracing options dynamically.
Source Code Reference
The implementation is located under:
pkg/urpc/: Core RPC client and server logic.pkg/unet/: Low-level Unix domain socket transport with FD passing.runsc/boot/controller.go: Controller and RPC server implementation in the Sentry.
Summary
uRPC is gVisor's internal control-plane backbone. It enables the runsc supervisory binary to command and orchestrate the sandboxed guest kernel (Sentry) and file proxy (Gofer) over Unix domain sockets with support for file descriptor passing. For filesystem data access, gVisor uses LISAFS and Directfs, reserving uRPC for sandbox management and lifecycle orchestration.

- gVisor
- gVisor - runsc
- gVisor - Sentry
- gVisor - Gofer
- gVisor - nvproxy
- gVisor - vDSO
- gVisor - Platforms
- gVisor - 9p
- gVisor - LISAFS
- gVisor - BPF
- gVisor - Filesystem
- gVisor - KVM
- gVisor - systrap
- gVisor - systrap vs KVM
- gVisor - verify
- gVisor - Core Scheduling
- gVisor - CPU Stunning
- gVisor - CPUID
- gVisor vs Container
- gVisor - Scheduler
- gVisor - Abstractions
- gVisor - Root Container
- gVisor - Source Code
- gVisor - uRPC
- gVisor - MemoryFile
