gVisor - Source Code
runsc/sandbox vs runsc/boot
runsc/sandbox is outside of sandbox, runsc/boot is inside the sandbox.
runsc/sandboxis outside the sandbox (Host-side): It is the management component that runs on the host. It is responsible for setting up the environment, creating the namespaces, and spawning the actual sandbox process. If you look atrunsc/sandbox/sandbox.go, it usesexec.Commandto launch the runsc boot process and then communicates with it over a Unix Domain Socket using RPCs (likeboot.ContMgrRootContainerStart).runsc/bootis inside the sandbox (Guest-side): It is the entry point for the Sentry process. Oncerunsc/sandboxspawns it, it runs inside the restricted environment (the sandbox). It initializes the guest kernel, sets up the virtualized network/filesystem, and starts executing the containerized application. ThecontainerManageracts as the RPC server inside this isolated environment, listening for commands from the host-side runsc/sandbox component.
Is runsc/boot still alive after the boot?
Yes, absolutely. The name "boot" is slightly misleading—it doesn't just bootstrap the environment and exit.
The runsc boot process becomes the Sentry (the guest kernel). It stays alive for the entire lifetime of the sandbox.
The controller.go file defines the containerManager and a urpc server. This RPC server runs continuously inside the sandbox. The host-side runsc process connects to this server over a Unix Domain Socket to control the sandbox dynamically. If the boot process died, the host would have no way to interact with the sandbox.
Key Repository Directory Structure
For developers navigating the gVisor repository, the codebase is organized as follows:
| Path | Purpose |
|---|---|
runsc/ |
The OCI-compliant runtime CLI binary. |
runsc/sandbox/ |
Host-side supervisor managing namespaces, cgroups, and spawning runsc boot. |
runsc/boot/ |
Sandbox entry point; bootstraps the Sentry kernel and runs the uRPC control server. |
runsc/container/ |
Container lifecycle abstractions and root container orchestration. |
pkg/sentry/ |
The Sentry user-space application kernel. |
pkg/sentry/kernel/ |
Core kernel subsystems: Task, ThreadGroup, signal handling, and futexes. |
pkg/sentry/syscalls/linux/ |
Pure-Go implementations of 200+ Linux system calls. |
pkg/sentry/platform/ |
Platform engines: systrap (default), kvm (virtualization), and ptrace (deprecated). |
pkg/sentry/vfs/ |
Virtual File System layer (VFS2). |
pkg/sentry/fsimpl/ |
Filesystem drivers: gofer, tmpfs, devpts, proc, and sys. |
pkg/sentry/memmap/ |
Memory management subsystem and MemoryFile. |
pkg/sentry/devices/nvproxy/ |
nvproxy GPU driver proxy and ioctl validation. |
pkg/sentry/devices/tpuproxy/ |
Google Cloud TPU hardware proxy. |
pkg/tcpip/ |
Netstack: Complete pure-Go TCP/IP network stack. |
pkg/lisafs/ |
LISAFS binary filesystem protocol with shared-memory ring buffers. |
pkg/urpc/ |
uRPC control-plane RPC framework supporting FD passing. |
pkg/unet/ |
Unix domain socket transport layer and SCM_RIGHTS helpers. |
pkg/abi/ |
ABI structures and definitions for Linux system calls and NVIDIA drivers. |
Recommended Reading
Sponsored
OS & Virtualization
Operating Systems: Three Easy Pieces
By Remzi & Andrea Arpaci-DusseauView on AmazonVirtualization
gVisor
- 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
