Skip to content


Repository files navigation



Nanos is a new kernel designed to run one and only one application in a virtualized environment. It has several constraints on it compared to a general purpose operating system such as Windows or Linux - namely it's a single process system with no support for running multiple programs nor does it have the concept of users or remote administration via ssh.

Read more about the Nanos Charter here.

  1. Getting Started
  2. Documentation
  3. Support

Getting Started

Please use the ops orchestrator to run your applications with Nanos unless you plan on hacking on Nanos itself. Many ready-to-use examples for running applications on Nanos using ops are available here.

Quick Start

Install ops && nanos:

curl -sSfL | sh



It is highly encouraged to use ops to build and run your applications using Nanos unless you are planning on modifying Nanos. ops provides sensible defaults for most users and incorporates our understanding of how to appropriately best use Nanos. It is also currently highly coupled to Nanos.

If you are running in a vm already (which is a bad idea) you'll need to specify that you don't want hardware acceleration. For instance you can run Nanos in virtualbox on a mac but it will be slow and hard to configure.

You can build and run on mac and linux. Nanos supports KVM on linux and HVF on osx currently for acceleration. ops has facilities to deploy to public clouds (AWS, GCE, Azure, and many others).

Building From Source on a Mac

Install Homebrew:

/usr/bin/ruby -e "$(curl -fsSL"

Grab Dependencies:

This installs the correct toolchain and will install an up-to-date qemu. It is highly recommended to be running the latest qemu otherwise you might run into issues.

For Intel-based Macs:

brew update && brew install nasm go wget ent
brew tap nanovms/homebrew-toolchains
brew install x86_64-elf-binutils
brew tap nanovms/homebrew-qemu
brew install nanovms/homebrew-qemu/qemu

For ARM-based Macs (M1/M2):

brew update && brew install go wget ent qemu aarch64-elf-gcc aarch64-elf-binutils
# To build and link runtime tests or aarch64 linux user programs:
brew tap nanovms/homebrew-toolchains
brew install aarch64-linux-binutils

Create a Chroot: (this isn't absolutely necessary)

For Intel-based Macs:

mkdir target-root && cd target-root && wget && tar xzf target-root.tar.gz

For ARM-based Macs (M1/M2):

mkdir target-root && cd target-root && wget && tar xzf arm64-target-root-new.tar.gz

You should also set the environment variable NANOS_TARGET_ROOT to the path of target-root created above in order to create the example and test images.

Building From Source on Linux

Nanos doesn't need too many dependencies on Linux.

To build you need to install nasm && qemu:

sudo apt-get install qemu-system-x86 nasm

For tests you'll also need the following installed:

sudo apt-get install ent ruby


curl --proto '=https' --tlsv1.2 -sSf | sh

If you wish to use FUSE you'll also want to install

sudo apt-get install libfuse-dev fuse

To build:

make run-noaccel


You can find more documentation on the ops docs site


In an effort for transparency and to collect, categorize, and document benchmarks we will start listing them here. The aims should be to be as reproducible and contain as much information as possible:

Go on GCloud: 18k req/sec

Rust on GCloud: 22k req/sec

Node.JS on AWS: 2k req/sec

Node.JS on GCloud: 4k req/sec


To run tests:

make test-noaccel

Development Running Instructions

For Nanos try running the first example first:

make run

To try a different target currently found in test/runtime/ you can:

  1. cp the manifest file to target.manifest
  2. add your code and set a target in test/runtime/Makefile
make TARGET=mynewtarget run

You may also wish to use ops to develop locally. If that's the case a commonly used idiom is to simply copy the 3 required files to an appropriate release:

cp output/tools/bin/mkfs ~/.ops/0.1.17/.
cp output/platform/pc/boot/boot.img ~/.ops/0.1.17/.
cp output/platform/pc/bin/kernel.img ~/.ops/0.1.17/.


Pull Requests

We accept pull requests as long as it conforms to our style and stated goals. We may reject prs if they violate either of these conditions.

If you are planning on spending more than a day to fix something it's probably wise to approach the topic in an issue with your planned fix before commiting to work.

Also, NanoVMs has paid kernel engineers with internal roadmaps so it's wise to check in with us first before grabbing a tkt. Tickets tagged 'low-priority' have a lower probability of collision.

Reporting Bugs

Please scan the issue list first to see if we are already tracking the bug.

Please attach debugging output (--trace in ops). Please provide the config.json and anything else that allows us to reproduce the issue.


TFS is the current filesystem utilized by Nanos.

Optional Manifest Debugging Flags

thread tracing:

futex_trace: t

syscall tracing:

debugsyscalls: t

Read more about Security here.


Debugging Help

Manual Networking Setup

Build Envs

Reference Materials


How are you using Nanos? Take this very short survey and help us grow the project. It will take just a minute but help us out!

Feedback Form

Who is Using Nanos?

If you are using Nanos for a project at your company or organization feel free to open up a PR and list your project/company below.

Getting Help

We run a public mailing list at:

for general questions. We also have a discussion forum.


If you'd like more in-depth help reach out to the nanovms folks via drift or email engineering.

If you need something done now or want immediate attention to an issue NanoVMs offers paid support plans.

If you need email support you will need to sign up for a support plan.