gVisor - Source Code

runsc/sandbox vs runsc/boot

runsc/sandbox is outside of sandbox, runsc/boot is inside the sandbox.

  • runsc/sandbox is 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 at runsc/sandbox/sandbox.go, it uses exec.Command to launch the runsc boot process and then communicates with it over a Unix Domain Socket using RPCs (like boot.ContMgrRootContainerStart).
  • runsc/boot is inside the sandbox (Guest-side): It is the entry point for the Sentry process. Once runsc/sandbox spawns 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. The containerManager acts 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.