Warning

This is not meant for novice users. This is for those who (1) really like sandboxed apps, (2) like to tweak the permissions of their apps, and (3) are comfortable using the command line.

And of course, don’t trust strange scripts on the internet without at first reading them and understanding them.

About

This script uses flatpak as the sandbox, which is convenient as it allows you to use existing tools like Flatseal to configure the sandbox.

I built this because I like my apps sandboxed. I will mostly use it for playing games. This will let me tailor the permissions the games need perfectly, ie no network for single player games and network for multiplayer games.

And to answer the question of “Why not Steam/Heroic/Bottles/Lutris”. There’s a few reasons. This script keeps games sandboxed from each other, is lighterweight, and was made for my own enjoyment.

I’ve also been working on a bubblewrap version that reuses host binaries and libraries which I may share later. It’s lighter weight and in theory more secure (less shared with host, better for browsers thanks to having access to unprivileged namespaces).

But anyways…

How to use

There are two files. The script, called “sandbox”, and the template flatpak manifest, called “sandbox.yml”.

To run the script, manually install “sandbox.yml” to ~/.local/share/sandbox/sandbox.yml. Or, you can edit the script and update the variable TEMPLATE_PATH to where ever you want.

Then, to create a new sandbox, you just need to run ./sandbox app-name.

The script roughly does the follow

  1. Makes sure you entered a valid app name
  2. Makes sure you have flatpak-builder installed (will install it if not, also note the script uses a user remote)
  3. Builds an empty flatpak that depends on Freedesktop 25.08 runtime
  4. Installs the flatpak

The first time the app is run (flatpak run my.custom.app-name), a script will be created inside the sandboxed home called “start”. On subsequent launches, this is executable that will be run.

Say if I wanted to play a Windows game, I would set the start script to umu ./path/to/game.exe.

But it can do anything. I also tested with the firefox .tar.xz and it worked without issue.

The script

sandbox.yml

app-id: domain.publisher.Name
runtime: org.freedesktop.Platform
runtime-version: '25.08'
sdk: org.freedesktop.Sdk
command: launcher
finish-args:
  - --persist=.

modules:
  - name: launcher-setup
    buildsystem: simple
    build-commands:
      - mkdir -p /app/bin
      # verify if 'start' exists. If not, create a default Hello World script.
      - |
        sh -c 'cat > /app/bin/launcher <<EOF
        #!/bin/sh
        TARGET="\$HOME/start"
        
        if [ ! -f "\$TARGET" ]; then
          echo "Creating default start script at \$TARGET..."
          echo "#!/bin/sh" > "\$TARGET"
          echo "echo Hello World from the sandbox!" >> "\$TARGET"
          chmod +x "\$TARGET"
        fi
        
        exec "\$TARGET" "\$@"
        EOF'
      - chmod +x /app/bin/launcher

sandbox:

#!/bin/bash

# bash safety options
# -e exits on failure
# -u exits on unknown variables
# -o pipefail exits on failed pipe
set -euo pipefail

################################################################################
### Usage Clause ###
####################

# make sure argument is provided for APP_NAME
if (( $# != 1)); then
    echo "Error: too few or too many arguments"
    echo "Usage: $0 app-name"
    exit 1
fi

################################################################################
### Configuration ###
#####################

# app details
DOMAIN="my"
PUBLISHER="custom"
APP_NAME="$1"

# flatpak manifest template location
TEMPLATE_PATH="$HOME/.local/share/sandbox/sandbox.yml"

################################################################################
### Functions ###
#################

# make sure flatpak version of flatpak-builder is installed
# installs it if necessary
check_dependencies() {
    if ! flatpak list --app | grep -q org.flatpak.Builder; then
        echo "flatpak-builder is not installed, installing now..."
        flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
        flatpak --user install --noninteractive flathub org.flatpak.Builder
    fi
}

# make sure a string only contains letters, numbers, and dashes
validate_string() {
    local input="$1"
    local var_name="$2"
    if [[ ! "$input" =~ ^[a-zA-Z0-9-]+$ ]]; then
        echo "Error: $var_name ('$input') contains invalid characters."
        echo "Allowed: letters, numbers, and dashes only."
        exit 1
    fi
}

cleanup() {
    # check if WORK_DIR exists to avoid errors if mktemp failed
    if [[ -d "$WORK_DIR" ]]; then
        echo "Cleaning up temporary directory..."
        rm -rf "$WORK_DIR"
    fi
}

################################################################################
### Execution ###
#################

# ensure flatpak-builder is installed on host or as flatpak
check_dependencies

# validate DOMAIN, PUBLISHER, and APP_NAME
validate_string "$DOMAIN" "DOMAIN"
validate_string "$PUBLISHER" "PUBLISHER"
validate_string "$APP_NAME" "APP_NAME"

# finalize app ID
APP_ID="$DOMAIN.$PUBLISHER.$APP_NAME"

# create temporary directory in current directory
WORK_DIR=$(mktemp -d -p "$PWD")

# check if WORK_DIR was created
if [[ ! "$WORK_DIR" || ! -d "$WORK_DIR" ]]; then
    echo "Error: could not create temp dir"
    exit 1
fi

# run cleanup function on successful exit or on failure
trap cleanup EXIT

# copy flatpak manifest to WORK_DIR
cp "$(realpath "$TEMPLATE_PATH")" "$WORK_DIR/$APP_ID.yml"

# edit the app ID of the flatpak manifest
sed -i "s/domain.publisher.Name/$APP_ID/g" "$WORK_DIR/$APP_ID.yml"

# build the flatpak
flatpak run --filesystem="$WORK_DIR" org.flatpak.Builder \
    --user \
    --force-clean \
    --repo="$WORK_DIR/$PUBLISHER" \
    "$WORK_DIR/build_dir" \
    "$WORK_DIR/$APP_ID.yml"

# install the flatpak
flatpak --user install --noninteractive --reinstall "$WORK_DIR/$PUBLISHER" "$APP_ID"

Developer @ashx64@lemmy.world