Building Container-Optimized OS from source

Container-Optimized OS is based on, and built using, tools from theopen-sourceChromium OS project. If you like, you can build a Container-Optimized OS image yourselfdirectly from the Container-Optimized OS source code.

Prerequisites

To build a Container-Optimized OS image, you'll need to install the followingtools on your development machine:

  • git andcurl
  • A package of Chromium scripts calleddepot_tools that includes tools likerepo andcros_sdk.

Obtaining the Container-Optimized OS source code

You can download the source code for Container-Optimized OS by using therepo tool that is included indepot_tools.

First, create a directory to store the source code. For example,cos-src inyour home directory:

mkdir $HOME/cos-srccd $HOME/cos-src

Now download source code using the following commands:

repo init https://cos.googlesource.com/cos/manifest.gitrepo sync
Note: Depending on your network speed, downloading the source code may takeseveral minutes.

Building a Container-Optimized OS image

To build Container-Optimized OS, you must create a suitablechrootenvironment. You can use thecros_sdk tool included indepot_tools to createand enter achroot that's ready for Container-Optimized OS compilation byrunning the following command in the source directory that you created in theprevious step:

cd $HOME/cos-srccros_sdk --enter

Once insidechroot, you can build the disk image. To buildContainer-Optimized OS, specifylakitu (x86 image) orlakitu-arm64(Arm image) for the board name as follows:

x86 image

build_packages--board=lakitubuild_image--board=lakitutest

Arm image

build_packages--board=lakitu-arm64build_image--board=lakitu-arm64test

In addition totest, you can build either abase, ordev imageby passing the appropriate parameter to the./build image script command. Ifyou don't specify a parameter,thedev image is built by default.

Thedev image contains some additional debug tools installed on top of thebase image. Thetest image includes the debug tools from thedev image aswell as tools necessary for running automatic Container-Optimized OS tests.

Note: You can log into atest image as the root user with the password"test0000", which can be useful if the SSH service is not accessible.

Attribution Requirements

When you produce a Container-Optimized OS image, you need to fulfill variousattribution requirements of third party licenses. The image generated by a buildcontains all relevant attribution information in/opt/google/chrome/resources/about_os_credits.html. As a separate buildartifact it is also available aslicense_credits.html file in the build outputdirectory.

Running Your Image

Once you've built your Container-Optimized OS image, you can run the imageusing KVM, or import the image to aCompute Engine instance.

Running in hypervisor

To boot your image in hypervisor, run the following command:

x86 image

kvm-m1024-nographic-netnic,model=virtio-netuser,hostfwd=tcp:127.0.0.1:9222-:22-hdasrc/build/images/lakitu/latest/chromiumos_test_image.bin

Arm image

sudoapt-getinstallqemu-system-armqemu-efiddif=/dev/zeroof=/tmp/flash0.imgbs=1Mcount=64ddif=/usr/share/qemu-efi/QEMU_EFI.fdof=/tmp/flash0.imgconv=notruncsudoqemu-system-aarch64-m1024-cpucortex-a57-Mvirt-nographic\-pflash/tmp/flash0.img\-devicevirtio-scsi-pci,id=scsi\-driveif=none,file=src/build/images/lakitu-arm64/latest/chromiumos_test_image.bin,id=hd0\-devicescsi-hd,drive=hd0,bootindex=0\-netnic\-netuser,hostfwd=tcp::9222-:22

Booting in this manner leaves the VM's serial port connected to your console,letting you log in without using SSH. If you're running atest image, you canlog in with the username/password pair "root/test0000".

Once the VM is started, you can access yourdev ortest image using SSH. ToSSH into the image, use the key generated for that image, as follows:

x86 image

sshroot@localhost-p9222-isrc/build/images/lakitu/latest/id_rsa

Arm image

sshroot@localhost-p9222-isrc/build/images/lakitu-arm64/latest/id_rsa

Running on Compute Engine

To import your image to a Compute Engine instance, you must compress the imageinto a.tar file. To compress the image, run the following command:

x86 image

tar-Sczfcompressed-image.tar.gzimages/lakitu/latest/chromiumos_image.bin--transform's|images/lakitu/latest/chromiumos_image.bin|disk.raw|'

Arm image

tar-Sczfcompressed-image.tar.gzimages/lakitu-arm64/latest/chromiumos_image.bin--transform's|images/lakitu-arm64/latest/chromiumos_image.bin|disk.raw|'

After you've created your.tar file, you can follow the instructions toimport an existing imagein the Compute Engine documentation.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-24 UTC.