Skip to content

Custom Runtimes

Custom runtimes can be created by customizing the filesystem of Linux distributions or entirely from scratch.

Base filesystem

Refer to the installation guide of your distribution for the procedure to obtain a base root filesystem.

⚠️ Only 64-bit Intel/AMD processors (x86_64) are supported on the network at the moment . Make sure you build runtimes on that architecture.

Debian Bullseye

mkdir ./rootfs
debootstrap --arch=amd64 --variant=minbase bullseye ./rootfs

Ubuntu 22.04

mkdir ./rootfs
debootstrap --arch=amd64 jammy ./rootfs

Following the next steps, you will be able to create and customize your own Debian based runtime:

1. Install required dependencies

First you need to install the required tools to be able to generate you own runtime.

Using Debian and Ubuntu systems:

sudo apt-get install debootstrap squashfs-tools

Using Nix:

nix-shell -p debootstrap squashfsTools

2. Obtain the build scripts

Download the files, and from the official runtime:

Customize these files to suit your needs.

3. Build a new runtime

Running the script as root will create a file named rootfs.squashfs:

sudo ./

4. Publish the runtime on

aleph file upload ./rootfs.squashfs
If this command fails due to an HTTP 413 Request Entity Too Large, then upload your root.squashfs using the IPFS desktop app or similar client. Then use the obtained CID with this command to pin it with the Aleph network:

aleph file pin <CID>

This command will provide you with the item_hash of the custom runtime, that you can then use when creating the program.