Flake Pilot User Guide

Application Isolation - Secure Execution with a Native Feel

Flake Pilot registers, provisions and launches applications that are not installed on your host but are provided inside a runtime environment such as an OCI container or a Firecracker virtual machine. The registered application behaves like any other program on the system: it is called by its name, it reads and writes the data you point it to, and it returns its exit code to your shell. Everything that is needed to run it, the image, the engine and the provisioning of the instance, is handled behind that name.

An application registered this way is called a flake.

About This Guide

This guide is written for administrators and developers who want to provide isolated applications on a Linux host. It explains the concepts behind flakes, shows how to register applications for the podman and firecracker engines, describes the network setup for virtual machines and documents the layout of the flake configuration.

The guide is organized as follows:

• Introduction explains what Flake Pilot is, which components it consists of and which problems it solves.

• Installation describes how to install the packages or how to build the project from source.

• Getting Started prepares the host and registers a first application.

• Applications From a Container covers applications provided by OCI containers, including delta containers and layered setups.

• Applications From a Virtual Machine covers applications provided by Firecracker virtual machines.

• Firecracker Networking explains how a virtual machine is connected to the outside world.

• Firecracker Volumes explains how a local host path is shared with a virtual machine over NFS.

• Application Setup documents the registry layout, the flake configuration and the tools to inspect a running setup.

• How To Build Your Own App Images points to ways of building your own application images.

• Troubleshooting and Known Issues collects known issues and the switches which help to analyze them.

The command line of each tool is documented in the manual pages shipped with the packages, e.g man 8 flake-ctl or man 8 podman-pilot. This guide references them where the details matter.

Contents

• 1. Introduction
  • 1.1. What Is Flake Pilot
  • 1.2. Components
  • 1.3. Use Cases
  • 1.4. Choosing an Engine
• 2. Installation
  • 2.1. Installing the Packages
  • 2.2. Building From Source
  • 2.3. Privileges
  • 2.4. Next Steps
• 3. Getting Started
  • 3.1. System Wide and Rootless Registration
  • 3.2. Preparing the Environment
  • 3.3. Creating the User Setup
  • 3.4. Your First Flake
  • 3.5. Where to Continue
• 4. Applications From a Container
  • 4.1. Amazon’s SDK Utility as a Container App
  • 4.2. An Editor as a Delta Container
  • 4.3. Claude AI as a Container App
  • 4.4. Engine Options
  • 4.5. Deeper Isolation With krun
  • 4.6. Calling a Registered Container App
  • 4.7. Pilot Options as Part of the Registration
• 5. Applications From a Virtual Machine
  • 5.1. Pulling an Image
  • 5.2. A Shell as a Firecracker VM App
  • 5.3. Claude AI as a Firecracker VM App
  • 5.4. Registration Options in Short
• 6. Firecracker Networking
  • 6.1. The Concept
  • 6.2. The Commands
  • 6.3. The Result in the Flake Configuration
• 7. Firecracker Volumes
  • 7.1. Export a Local Path
  • 7.2. Release a Local Path
  • 7.3. Add a Volume to an Application
  • 7.4. Remove a Volume From an Application
  • 7.5. The Result in the Flake Configuration
• 8. Application Setup
  • 8.1. Listing Applications
  • 8.2. The Flake Registry
  • 8.3. Removing an Application
  • 8.4. Reference Documentation
• 9. How To Build Your Own App Images
  • 9.1. Examples
• 10. Troubleshooting and Known Issues
  • 10.1. Debugging a Flake
  • 10.2. Known Issues
  • 10.3. Feedback

Resources

• Source code and issue tracker: https://github.com/OSInside/flake-pilot

• Packages: https://build.opensuse.org/package/show/Virtualization:Appliances:Builder/flake-pilot

• Manual pages: https://github.com/OSInside/flake-pilot/tree/main/doc

Feedback is very much welcome.