gvisor README

The project's README from github.com/google/gvisor. As one markdown file: README.md.

gVisor

Build status Issue reviver CodeQL gVisor chat code search

What is gVisor?

gVisor provides a strong layer of isolation between running applications and the host operating system. It is an application kernel that implements a Linux-like interface. Unlike Linux, it is written in a memory-safe language (Go) and runs in userspace.

gVisor includes an Open Container Initiative (OCI) runtime called runsc that makes it easy to work with existing container tooling. The runsc runtime integrates with Docker and Kubernetes, making it simple to run sandboxed containers.

What isn't gVisor?

gVisor takes a distinct third approach, providing many security benefits of VMs while maintaining the lower resource footprint, fast startup, and flexibility of regular userspace applications.

Why does gVisor exist?

Containers are not a sandbox. While containers have revolutionized how we develop, package, and deploy applications, using them to run untrusted or potentially malicious code without additional isolation is not a good idea. While using a single, shared kernel allows for efficiency and performance gains, it also means that container escape is possible with a single vulnerability.

gVisor is an application kernel for containers. It limits the host kernel surface accessible to the application while still giving the application access to all the features it expects. Unlike most kernels, gVisor does not assume or require a fixed set of physical resources; instead, it leverages existing host kernel functionality and runs as a normal process. In other words, gVisor implements Linux by way of Linux.

gVisor should not be confused with technologies and tools to harden containers against external threats, provide additional integrity checks, or limit the scope of access for a service. One should always be careful about what data is made available to a container.

Documentation

User documentation and technical architecture, including quick start guides, can be found at gvisor.dev.

Installing from source

gVisor builds on x86_64 and ARM64. Other architectures may become available in the future.

For the purposes of these instructions, bazel and other build dependencies are wrapped in a build container. It is possible to use bazel directly, or type make help for standard targets.

Requirements

Make sure the following dependencies are installed:

Building

Build a release tarball containing runsc, the containerd-shim-runsc-v1 containerd shim, and a few sidecar binaries that runsc expects to find in a gvisor-bin/ directory next to itself, then extract it to /usr/local/bin:

make release-tarball DESTINATION=bin/
sudo tar -C /usr/local/bin -xf bin/gvisor.tar.bz2

To build specific libraries or binaries, you can specify the target:

make build TARGETS="//pkg/tcpip:tcpip"

Building directly with Bazel (without Docker)

Using Bazel directly isn't recommended due to the extra overhead, but in order to get started:

After setting up dependencies, using Bazel is similar to the Makefile:

bazel build -c opt //debian:gvisor-release-tar-bz2

Testing

To run standard test suites, you can use:

make unit-tests
make tests

To run specific tests, you can specify the target:

# Makefile
make test TARGETS="//runsc:version_test"
# Bazel
bazel test //runsc:version_test

Mac OS

Some packages support running tests directly on macOS. At the time of this writing, gVisor requires bazel 8, which you can install via homebrew:

brew install bazel@8

# You can then run the tests, e.g.:
$(brew --prefix bazel@8)/bin/bazel test --macos_sdk_version=$(xcrun --show-sdk-version) -- //tools/nogo/... //tools/check{aligned,const,escape,linkname,locks,unsafe}/...

Using go get

This project uses bazel to build and manage dependencies. A synthetic go branch is maintained that is compatible with standard go tooling for convenience. This is useful for external packages and libraries that depend on gVisor subpackages (e.g. userspace networking via Netstack) to import gVisor Go code into their Go projects.

Select this branch explicitly with the go branch query. @latest resolves master, which requires Bazel and is not compatible with standard Go tooling:

go get gvisor.dev/gvisor/pkg/tcpip/transport/tcp@go

NOTE: runsc builds from this branch are not supported. gVisor and runsc require several binaries (some of which are not even written in Go) in order to function. The go branch is supported in a best effort capacity, and direct development on this branch is not supported. Development should occur on the master branch, which is then reflected into the go branch.

Community & Governance

See GOVERNANCE.md for project governance information.

See ADOPTERS.md for a list of known production users and adopters.

The gvisor-users mailing list and gvisor-dev mailing list are good starting points for questions and discussion.

Security Policy

See SECURITY.md.

Contributing

See Contributing.md.

gvisor (google/gvisor)

Searching Database…

19.7K ·GitHub
Gvisor
What is this?An application kernel for containers: it wraps running applications in a strong isolation layer from the host OS, implementing a Linux-like interface in memory-safe Go, entirely in userspace.
Is it a library I add to my code, or something that runs my containers?Neither a library nor a syscall filter — it ships an OCI runtime called runsc that plugs into Docker and Kubernetes, so your existing container tooling keeps working unchanged.
How do I run my existing containers under it?Install runsc and select it as the runtime for the containers you want sandboxed — it integrates with Docker and Kubernetes directly; quick start guides are at gvisor.dev.
How is it different from seccomp profiles, firejail, or a full VM?It is not a syscall filter like seccomp-bpf, not a wrapper like firejail or AppArmor, and not a VM — it is a third approach: VM-like security with the footprint and fast startup of a userspace app.
Containers already feel isolated — why would I need this?Plain containers share one host kernel, so a single kernel vulnerability can mean container escape; gVisor is for running untrusted or potentially malicious code without betting the host kernel on it.
Will it run on my ARM server, and what about macOS?It builds on x86_64 and ARM64; some packages can also run tests directly on macOS, but the sandbox runtime itself targets Linux hosts.
What trade-offs does its approach make compared to a full VM?You get many security benefits of a VM while keeping the low resource footprint, fast startup, and flexibility of a normal userspace application — gVisor runs as a regular process that leverages existing host kernel functionality.
Can I reuse gVisor components, like its network stack, in my own Go project?Yes — a maintained go branch is compatible with standard Go tooling, so external projects can import gVisor subpackages such as the Netstack userspace network stack. Note that runsc built from that branch is not supported.
Does sandboxing with gVisor mean I can run anything safely?Not quite — it limits the host kernel surface the application can reach, but the README stresses you should still be careful about what data you make available to a container; it is not a tool for hardening against external threats.
What are similar projects?runc, podman, clair, arcbox, containerd, smolvm, allox-os, firecracker
Which topics is it in?oci, x86, runtime, arm64, kernel, virtualization, systems-programming, containers, google, sandbox, security-tools, kubernetes
Creator
google
Size
1.3 GB
Stars
19.7K
Updated
CommitOct 17Releaserelease-20261012.0Oct 16
Age
8y
Commits · 90 Days