User Guide

Creating the USB Drive

The Town OS USB image is built from the install repository. The build process produces a bootable image with a squashfs root filesystem and a GPT partition layout.

Prerequisites

You'll need a Linux system with the following tools installed:

• make — the build is driven entirely by Makefiles
• arch-install-scripts — for pacstrap bootstrapping
• squashfs-tools — for creating the compressed root filesystem
• parted and e2fsprogs, dosfstools — for partitioning and filesystem creation
• podman — for enabling systemd units inside the chroot
• An Arch Linux host system (required for pacstrap)
• A USB drive (4 GB or larger recommended)

Cloning and Building

git clone https://gitea.com/town-os/install.git
cd install
make image

Running make or make image builds the complete USB image. The process downloads the base system, installs Town OS components, compresses everything into a squashfs filesystem, and assembles the final disk image with a GPT partition table.

Partitioning and Squashfs

The resulting image uses a GPT layout with:

• A BIOS boot partition (1 MiB) for legacy BIOS booting
• An EFI system partition (64 MiB, FAT32) for UEFI booting
• A data partition (ext4) containing the squashfs root filesystem and GRUB

At boot time, Town OS mounts the squashfs as a read-only lower layer, with a tmpfs overlay on top. This means the OS runs entirely in RAM — the USB drive itself is only read at boot. All runtime changes happen in memory and are discarded on reboot, giving you a clean slate every time.

Writing the Image

Once the image is built, write it to your USB drive using dd:

# Find your USB device (e.g. /dev/sdb)
lsblk

# Write the image (replace /dev/sdX with your device)
sudo dd if=town-os.img of=/dev/sdX bs=4M status=progress conv=fsync

Double-check the target device — dd will overwrite whatever you point it at without confirmation.

Setting Up DNS on Your Router

Town OS includes rolodex, a DNS server that manages authoritative zones for your packages and forwards upstream queries. To use it as your network's DNS server, you need to tell your router to hand out the Town OS machine's IP address as the DNS server for your network. This way every device on your network automatically uses rolodex for DNS — no per-device configuration needed.

Find Your Town OS IP Address

You'll need the local IP address of your Town OS machine. You can find it by:

• Logging in to the dashboard at http://town-os.local after first-boot setup and selecting the internal IP shown on the dashboard — this is the address to use as your DNS server
• Running make vm-ip if you're using a VM
• Checking your router's DHCP client list for a device named "town-os"

For DNS to work reliably, your Town OS machine should have a static IP address or a DHCP reservation on your router. If the IP changes, DNS will break for your whole network.

Assign a Static IP or DHCP Reservation

Most routers let you reserve an IP address for a specific device based on its MAC address. This is usually found under LAN Settings, DHCP, or Address Reservation. Find the Town OS machine in the client list and reserve its current IP.

If your router doesn't support DHCP reservations, you can configure a static IP on the Town OS machine itself by adding it to town-os.yaml.

Change the DNS Server in Your Router

The exact steps vary by router brand, but the general process is the same:

1. Log in to your router's admin interface (usually 192.168.1.1 or 192.168.0.1)
2. Find the DHCP Settings, LAN Settings, or DNS Settings section
3. Change the Primary DNS Server to your Town OS machine's IP address
4. Optionally set a Secondary DNS Server as a fallback (e.g. 1.1.1.1 or 8.8.8.8) — this will be used if Town OS is unreachable
5. Save and apply the settings

After saving, devices on your network will pick up the new DNS server the next time they renew their DHCP lease. You can force this by disconnecting and reconnecting to the network, or by rebooting the device.

Common Router Interfaces

Verify It Works

After your device picks up the new DNS settings, verify that rolodex is handling your DNS queries:

# Check which DNS server your machine is using
nslookup example.com

# Or query Town OS directly
dig @<town-os-ip> example.com

# Query a package domain (if you have packages installed)
dig @<town-os-ip> mypackage.home

If example.com resolves correctly, rolodex is working and handling DNS for your network.

Building VMs from USB Images

The install repository includes scripts for launching Town OS in virtual machines, which is useful for testing and development without a physical USB drive.

QEMU

make qemu

Launches a QEMU VM with KVM acceleration, 4 IDE drives for storage testing, and bridge networking. The VM boots from the USB image and behaves identically to a physical installation.

VirtualBox

make virtualbox

Creates a VirtualBox VM with bridged networking and converts the raw disk image to VDI format. Bridged mode lets the VM appear as a regular device on your network.

Auto-Detection

make run

Automatically detects your hypervisor — prefers QEMU if available, falls back to VirtualBox.

Environment Variables

Serial Console

# Attach to the VM serial console
make serial

# Or manually via socat
socat -,rawer,escape=0x1d unix-connect:/tmp/town-os-serial.sock

# Detach with Ctrl-]

Finding the VM

# Get the VM's IP address
make vm-ip

# Or connect via mDNS
ssh root@town-os.local

RAID Installation

Disk provisioning is handled interactively by ttyforce during the first boot. All storage uses btrfs.

Automatic RAID Selection

ttyforce detects available disks, groups them by transport type (NVMe, SATA, etc.) and similar size, then automatically selects the RAID level based on disk count:

• 1 disk — single mode (no redundancy)
• 2 disks — RAID 1 (btrfs mirror)
• 3+ disks — RAID 5 (btrfs striped with parity)

The default mount point is /town-os. ttyforce creates @etc and @var subvolumes for overlayfs-compatible persistence.

Disk Detection

ttyforce automatically detects available storage devices. It identifies NVMe drives, SATA/SAS drives, and SD cards, while excluding the boot USB device and any removable media. The detection logic ensures that Town OS never touches the drive it booted from.

Overlay Filesystem

Regardless of storage backend, Town OS uses overlay mounts for /var and /etc persistence. The lower layer comes from the squashfs root, while the upper layer lives on the RAID/ZFS storage. This means system configuration and service data survive reboots while the base OS remains immutable.

Building a Package

Town OS packages are YAML files that describe how to run a containerized service. For the full specification, see the Packaging Format reference. This section covers the practical workflow.

Repository Structure

A package repository is a git repository with a packages/ directory. Each package gets a subdirectory containing versioned YAML definitions:

my-packages/
  packages/
    my-app/
      1.0.yaml
      2.0.yaml

Writing a Package Definition

A minimal package needs only an image field. A typical package includes a description, networking, volumes, and user-facing questions:

image: myapp:latest
description: My custom application
supplies: ["http"]
network:
  external:
    "@port@": "8080"
volumes:
  data:
    mountpoint: /app/data
    quota: 5gb
questions:
  port:
    query: "What external port should this app use?"
    type: port
    default: "9000"
notes:
  URL:
    value: "http://@LOCAL_EXTERNAL_HOST@:@port@"
    type: url

Template System

Use @variable@ syntax to reference question answers and built-in variables (@LOCAL_EXTERNAL_HOST@, @LOCAL_INTERNAL_HOST@). Templates work in environment variables, port mappings, quotas, and note values.

Testing Locally

Use the dev environment to test your package. Place your repository on disk, add it through the UI or repositories.json, and install your package. The dev environment provides the full Town OS stack for testing.

Adding a Repository

Add your package repository to Town OS through the UI (Packages → Repositories → Add Repository) or by editing repositories.json directly:

[
  ["default", "https://github.com/town-os/default-packages"],
  ["my-packages", "https://github.com/myuser/my-packages"]
]

Development Environment and Test Suite

The Town OS development environment runs the full stack locally using Podman containers. This is the fastest way to test changes, develop packages, and run the test suite.

Prerequisites

• Linux — required for btrfs and Podman rootful containers
• Podman — container runtime (rootful mode, with sudo)
• Go 1.25+ — for the backend API server
• Bun — for the frontend build and dev server
• btrfs-progs — for storage management
• QEMU — qemu-system-x86_64 and qemu-img for VM package support
• libsystemd — development headers for systemd integration
• golangci-lint — for Go linting
• Python 3 — for build and test scripts

Starting the Dev Environment

git clone https://gitea.com/town-os/town-os.git
cd town-os
make dev

This starts the full development stack with hot-reloading. Once it's ready, open the URL printed in the terminal to access the Town OS dashboard.

Dev Environment Commands

Running Tests

Integration Tests

Integration tests run inside a privileged Podman container that provides a real btrfs filesystem, systemd, and Podman-in-Podman. This ensures tests exercise the same code paths as a production installation. The test container is ephemeral — it's created fresh for each test run and cleaned up afterward.