Project Structure

This page walks through every file and folder in a Strux project — what it's for, what you should edit, and what Strux manages for you. If you haven't created a project yet, start with Getting Started.

The scaffolded project

Running strux init my-kiosk creates this:

my-kiosk/
├── strux.yaml           # Project configuration
├── main.go              # Go backend entry point
├── go.mod / go.sum      # Go module files
├── frontend/            # Your web app (Vite project)
│   └── src/strux.d.ts   # Generated TypeScript types for the backend API
├── bsp/
│   └── qemu/            # Board profile for local testing
│       ├── bsp.yaml     # BSP configuration
│       ├── scripts/     # BSP lifecycle scripts (make-image.sh)
│       └── overlay/     # BSP-specific filesystem overlay
├── assets/
│   └── logo.png         # Splash screen logo
├── overlay/             # Global filesystem overlay
├── strux-update.key     # Update signing key (private — gitignored)
├── strux-update.pub     # Update verification key (public — built into images)
└── .gitignore

After your first build, a dist/ folder appears too — covered below.

strux.yaml

The project's main configuration: project name, which BSP to build by default, display layout, splash screen, root filesystem packages, QEMU options, and dev server settings. Every key is documented in the strux.yaml reference.

main.go and go.mod

Your Go backend. The template ships a small App struct whose exported fields and methods are automatically exposed to the frontend as a typed API — see the Backend guide. go.mod declares the dependency on the Strux runtime library (github.com/strux-dev/strux/pkg/runtime); strux init creates it for you.

frontend/

A completely normal Vite project — React, Vue, or vanilla TypeScript depending on the --template you picked. The one Strux-specific file is frontend/src/strux.d.ts: auto-generated TypeScript definitions for your Go backend's API. Don't edit it by hand; it's regenerated by strux types and at the start of every build. The Frontend guide covers all of this.

bsp/

Board Support Packages — one folder per hardware target. Each BSP describes how to build the OS for a specific board: kernel, bootloader, lifecycle scripts, and board-specific filesystem additions.

What's a BSP?

A Board Support Package is everything hardware-specific: which kernel to compile, which bootloader the board needs, what drivers and configuration it requires. Your app code stays the same across boards; the BSP changes. See BSP concepts.

Your project starts with one BSP, bsp/qemu/, containing:

bsp.yaml — the BSP configuration (architecture, kernel and bootloader settings, build scripts). Heavily commented in the template; full reference at bsp.yaml.
scripts/make-image.sh — the lifecycle script that assembles the final disk image.
overlay/ — files copied into the OS filesystem only when building this BSP.

Keep the qemu BSP

Do not delete bsp/qemu/. It's what lets strux dev and strux run work on your machine. Add BSPs for real hardware alongside it — see Writing a BSP.

assets/

Static assets used at build time. The template puts logo.png here — the boot splash image, referenced from strux.yaml under boot.splash.logo. Swap it for your own (it must be a PNG).

overlay/

The global root filesystem overlay: anything you put here is copied verbatim into the OS image, for every BSP.

What's a rootfs overlay?

The root filesystem (rootfs) is the / of your device's Linux system — all its files and directories. An overlay is a folder mirroring that structure: overlay/etc/myapp.conf in your project becomes /etc/myapp.conf on the device. It's the standard way to drop config files into the image.

Each BSP also has its own overlay/ for board-specific files; this top-level one applies to all builds.

strux-update.key / strux-update.pub

An RSA keypair generated by strux init, used to sign OS update bundles. The private key (strux-update.key) stays on your machine and is excluded by the generated .gitignore; the public key is built into your images so devices can verify updates. See Updates.

The dist/ folder

dist/ is created on your first build and holds everything Strux produces. It has five subfolders, each with different rules:

dist/
├── artifacts/    # User-editable build files — written once, then yours
├── cache/        # Compiled intermediate artifacts (per BSP)
├── output/       # Final images, ready to run or flash (per BSP)
├── temp/         # Runtime scratch files
└── flash/        # Flashing tool workspace (per BSP)

dist/artifacts/ — yours to edit

These files are copied from the CLI's embedded assets once, on first build, and never overwritten after that. Edit them freely to customize the OS — your changes persist across builds. They include the builder Dockerfile, init and service scripts (scripts/), systemd units (systemd/), the Plymouth boot splash config (plymouth/), and the source for the on-device Strux client, Cage compositor, and WPE extension. One exception: artifacts/logo.png is re-copied on every build from the location set in strux.yaml. See Artifacts and Customizing the OS. Also, if you upgrade to a newer version of Strux, you may need to delete the dist/artifacts folder so that Strux can recreate them as they may implement version-specific features. There is also an option to restore your dist/artifacts to the built-in version in the strux dev Terminal User Interface.

dist/cache/ — auto-generated, don't edit

Compiled intermediate results: the bundled frontend (shared across BSPs) and a per-BSP folder (e.g. cache/qemu/) holding the compiled Go app, Cage, the Strux client, kernel artifacts, and rootfs tarballs. This is what makes rebuilds fast — the build cache hashes each step's inputs and skips anything unchanged. Wipe it with strux build <bsp> --clean or simply delete the folder. Deleting the cahce folder can fix a lot of issues during build, with only caveat that the next build will be a complete rebuild.

Frontend and Backend — building your actual app.
Build Pipeline — what happens when you run strux build.
strux.yaml reference — every configuration key.