gVisor: An Application Kernel That Replaces the Host Kernel Surface for Containers

The Problem: Containers Share a Kernel, and That Is a Risk

The README is blunt: containers are not a sandbox. A single shared host kernel means a single vulnerability can lead to container escape. gVisor exists to close that gap. It is for teams that run untrusted or potentially malicious code in containers and cannot accept the risk of a shared kernel. It is not for everyone. If your containers run trusted code and your threat model is limited to external network attacks, the overhead of gVisor may not be justified. The target user is someone who wants the operational convenience of containers but needs a stronger isolation boundary than the default Docker or Kubernetes runtime provides.

The Mechanism: A Userspace Kernel That Implements Linux by Way of Linux

gVisor is not a syscall filter like seccomp-bpf, and it is not a VM in the VirtualBox sense. It is an application kernel written in Go that runs in userspace and implements a Linux-like interface. When a container runs under gVisor, its syscalls are intercepted by this userspace kernel, which then translates them into host operations. The README says gVisor 'implements Linux by way of Linux.' That means it does not virtualize hardware; it uses the host kernel as a resource provider, but it limits the host kernel surface that the application can touch. The result is a security boundary that sits between the application and the host kernel, reducing the attack surface without the resource footprint of a full VM. The architecture is distinct from both seccomp filtering and hardware virtualization, which is why the README spends time explaining what gVisor is not.

Getting It Running: Build from Source with Make or Bazel

The README provides concrete build instructions. You need Linux 5.6 or later and Docker version 17.09.0 or greater. The recommended path is to build a release tarball using the Makefile. The command is: make release-tarball DESTINATION=bin/. This produces a gvisor.tar.bz2 file that you extract to /usr/local/bin with sudo tar -C /usr/local/bin -xf bin/gvisor.tar.bz2. The tarball contains runsc, the containerd-shim-runsc-v1 shim, and sidecar binaries that runsc expects in a gvisor-bin/ directory next to itself. You can also build specific targets, for example make build TARGETS="//pkg/tcpip:tcpip" to build the Netstack TCP/IP library. For direct Bazel builds, the README warns it is not recommended due to extra overhead, but you can use bazelisk and run bazel build -c opt //debian:gvisor-release-tar. Testing is possible with make unit-tests and make tests, or specific targets like make test TARGETS="//runsc:version_test". There is also a macOS path for running some tests, but it requires bazel 8 and is limited to certain packages.

The go Branch: A Convenience That Does Not Build runsc

A notable quirk is the synthetic go branch. It exists so that external Go projects can import gVisor subpackages, like the Netstack userspace networking stack, using standard go tooling. The README gives the example: go get gvisor.dev/gvisor/pkg/tcpip/transport/tcp@go. However, the go branch is not supported for building runsc. The README states plainly: 'runsc builds from this branch are not supported.' runsc requires several binaries that are not written in Go, so the go branch is a best-effort convenience for library consumers, not a way to build the runtime. This is a real limitation if you are tempted to use go get to pull down the whole project. You must use the Bazel-based build on master to get a working runtime. The go branch is maintained as a reflection of master, but direct development on it is not supported.

Limitations and Failure Modes: Performance, Compatibility, and Build Complexity

The README does not hide the trade-offs. gVisor is not a drop-in replacement for the Linux kernel. It implements a Linux-like interface, which means some syscalls may behave differently or not be supported. Applications that rely on obscure or very recent kernel features may break. Performance is another concern: because every syscall goes through a userspace kernel, there is overhead compared to native containers. The README claims lower resource footprint and fast startup compared to VMs, but it does not claim parity with native containers. The build process is also a barrier. The project uses Bazel, and the README says using Bazel directly is not recommended due to extra overhead. The Makefile wraps Bazel in a build container, which simplifies things, but you still need Docker and a recent Linux kernel. If you are on an older kernel or an unsupported architecture (only x86_64 and ARM64 are supported), you cannot build or run gVisor. The wrong tool would be any environment where you need full Linux syscall compatibility or where every millisecond of latency matters.

Alternatives: VMs and Syscall Filters Take Different Approaches

The README explicitly contrasts gVisor with two alternatives. First, syscall filters like seccomp-bpf and tools like firejail or AppArmor. These do not implement a kernel; they restrict which syscalls an application can make. This is a lighter approach with less overhead, but it does not provide the same level of isolation because the host kernel is still directly exposed for the allowed syscalls. Second, VMs like VirtualBox or QEMU. A VM provides strong isolation by running a separate guest kernel, but it requires virtualized hardware, which means higher resource usage and slower startup. gVisor sits in between: it gives many security benefits of a VM without the hardware virtualization overhead. The choice depends on your threat model. If you need to run truly untrusted code and can afford the resource cost, a VM might be more appropriate. If you only need to reduce the attack surface for semi-trusted code, a syscall filter might be enough. gVisor is the middle path, and it is not always the best one.

Maintenance and License: Apache-2.0 with a Governance Structure

gVisor is licensed under Apache-2.0, which is permissive for commercial use, but you should review the license terms for your specific use case. The project has a governance model described in GOVERNANCE.md and a list of known production users in ADOPTERS.md. The repository is actively maintained, with a recent release named 20260817.0, indicating a date-based versioning scheme. The build system is Bazel, which has a learning curve. The README mentions a .bazelversion file to pin the Bazel version, and it suggests using bazelisk to manage that. Upgrading gVisor likely means rebuilding the release tarball and redeploying the binaries. There is no package manager installation described; you build from source. That is a maintenance cost. The go branch is a best-effort convenience, but it is not a stable API for runsc. If you depend on gVisor for production, you should track the release cadence and test new versions against your workloads before deploying.

Editorial conclusion

Adopt gVisor if you run untrusted or multi-tenant container workloads and need stronger isolation than standard container runtimes, and if you can accept the performance overhead and Linux compatibility limits. Do not adopt it for latency-sensitive or high-throughput workloads, or for workloads that require the full Linux syscall surface. Before adopting, verify that your specific workloads pass the gVisor test suites, check the ADOPTERS.md list for similar use cases, and review the SECURITY.md policy for known limitations. gVisor is a deliberate trade-off: it trades raw performance for a smaller host kernel attack surface, and that trade-off is only worth it if your threat model demands it.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes