Tutorials/Apptainer-FakerootAndSandbox

Apptainer Sandbox: Modifying Containers Interactively

Important: Before you begin, make sure the following are in place:

• You are running on a compute node, not a login node. Request an interactive session first (e.g. via srun or your scheduler).
• Your .sif image files should be stored on Lustre (e.g. in your scratch space), not in your home directory. SIF files can be large and will eat through your home quota fast.
• Set your Apptainer cache to Lustre as well. Add this to your session (or your .bashrc):

export APPTAINER_CACHEDIR=$myScratch/apptainer_cache

Getting Started

Load the required modules:

module reset
module load utilities Apptainer

What is a Sandbox?

In the previous tutorial we used overlays to make changes on top of a read-only SIF image. Another approach is to convert the image into a sandbox — a regular directory on disk that contains the full filesystem of the container. Because it is just a directory, you can write to it directly.

This makes it easy to interactively install software, edit config files, and generally tinker with the container before converting it back into a portable SIF file.

Pulling as a Sandbox

First, create a temporary directory and pull the Ubuntu 24.04 image directly as a sandbox:

sandbox=$(mktemp -d)
apptainer pull $sandbox/ubuntu --sandbox docker://ubuntu:24.04

Instead of producing a single .sif file, this creates a directory at $sandbox/ubuntu that contains the entire container filesystem. You can ls it to see the familiar Linux directory structure:

ls $sandbox/ubuntu

You should see directories like bin, etc, usr, var, and so on — just like a normal Linux root filesystem.

Entering the Sandbox

Now let's open an interactive shell inside the sandbox:

apptainer shell --containall --writable --fakeroot $sandbox/ubuntu

We are using three flags here, each doing something important:

Flag	What it does
--containall (or -C)	Fully isolates the container from the host system. Your home directory, host environment variables, and host filesystems are not mounted into the container. This gives you a clean environment.
--writable (or -w)	Allows you to make changes to the container's filesystem. Without this flag, even a sandbox would be mounted read-only.
--fakeroot (or -f)	Makes it look like you are running as root inside the container. This is needed because package managers like apt expect root privileges to install software.

Your prompt should change to Apptainer>, indicating you are now inside the container.

Installing Software

From inside the container, update the package lists and install nano, cowsay and fortune-mod:

Apptainer> apt-get update
Apptainer> apt-get install -y nano cowsay fortune-mod

Once the installation finishes, clean up the apt cache to keep the image small:

Apptainer> apt-get clean

Fixing the PATH

In Ubuntu, cowsay and fortune are installed into /usr/games/, which is not in the default PATH for non-interactive shells. If we were to build a SIF from this sandbox right now, running fortune or cowsay would fail with a "command not found" error.

We need to add /usr/games to the container's PATH. Apptainer reads environment settings from files in /.singularity.d/env/. Run this command inside the container:

Apptainer> echo 'export PATH=/usr/games:${PATH}' >> /.singularity.d/env/90-environment.sh

This appends a line to the environment script that ensures /usr/games is on the PATH every time the container runs.

Editing the Runscript

The runscript is the command that gets executed when you use apptainer run on the container. It lives at /.singularity.d/runscript. Let's edit it so that our container does something fun by default.

Open the runscript with nano:

Apptainer> nano /.singularity.d/runscript

You should see something like:

#!/bin/sh
OCI_ENTRYPOINT=''
# ...various lines...
exec "$@"

Add fortune | cowsay on the line just above the final exec "$@", so the end of the file looks like this:

fortune | cowsay
exec "$@"

Save and exit nano (Ctrl+O, Enter, Ctrl+X).

Now exit the container:

Apptainer> exit

Building the Final SIF Image

Convert the sandbox back into a portable SIF file:

apptainer build fortune.sif $sandbox/ubuntu

This compresses the entire sandbox directory into a single fortune.sif file.

Running It

Now for the moment of truth:

apptainer run fortune.sif

You should see a random fortune displayed inside a speech bubble from a friendly cow. Something like:

 ________________________________________
/ You will be awarded some great honor. \
\                                        /
 ----------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Every time you run it, you get a different fortune.

Cleaning Up

Remove the temporary sandbox directory:

rm -rf $sandbox

Summary

Step	Command
Create temp directory	sandbox=$(mktemp -d)
Pull as sandbox	apptainer pull $sandbox/ubuntu --sandbox docker://ubuntu:24.04
Enter sandbox	apptainer shell --containall --writable --fakeroot $sandbox/ubuntu
Install software	apt-get update && apt-get install -y nano cowsay fortune-mod && apt-get clean
Fix PATH	echo 'export PATH=/usr/games:${PATH}' >> /.singularity.d/env/90-environment.sh
Edit runscript	nano /.singularity.d/runscript
Exit container	exit
Build SIF from sandbox	apptainer build fortune.sif $sandbox/ubuntu
Run it	apptainer run fortune.sif
Clean up	rm -rf $sandbox