User Guide

Building the USB Image from Source

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 need a Linux host and a USB drive (4 GB or larger). The build uses Arch Linux tooling (pacstrap, mkinitcpio, arch-chroot), but you do not need to be running Arch — on any other distro make image automatically runs the build inside a same-architecture Arch container. Install the host dependencies with the bundled target for your distro:

• make deps — Arch (and derivatives) or Fedora/RHEL
• make deps-debian — Debian or Ubuntu

These pull in everything the build and VM tooling need — make, podman, arch-install-scripts, squashfs-tools, parted, e2fsprogs, dosfstools, qemu, and libvirt.

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

The simplest way is make flash, which builds the image if it is stale and writes it to a USB device. To do it by hand, note that the build produces a dated, arch-suffixed file (e.g. town-os-2026-07-25-x86_64.img) — write it with dd:

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

# Write the image (replace the filename and /dev/sdX with your device)
sudo dd if=town-os-YYYY-MM-DD-x86_64.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).
# Names follow <name>.<repo>.<tld> — .home is the default network's TLD
dig @<town-os-ip> gitea.default.home

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

Choosing a Resolution Mode

Names that don't belong to one of your networks are resolved according to the resolution mode, which you set under Settings → DNS Resolution in the dashboard. Three modes are available:

• Automatic (recommended) — the default. Tries to resolve iteratively from the root servers first, then falls back through DoH/DoT, a local forwarder, and finally a public resolver, sticking with whichever tier last worked. This keeps recursion's privacy where the network allows it, and degrades gracefully on networks that filter outbound DNS.
• Recursive only — resolves everything iteratively from the root servers with no fallback. Guarantees no query is ever handed to a third-party resolver, but every external name fails on networks that block or hijack outbound port 53 (hotels, captive portals, some ISPs).
• Forward — always sends unmatched queries to upstream resolvers (Google Public DNS by default). This is the classic forwarding behavior.

Blocking Ads and Malicious Domains

rolodex can screen queries against DNSBL (domain blocklists) and RBL (IP blocklists) providers, giving you network-wide ad and threat blocking without a separate Pi-hole. Manage these under DNS → Blocklists. Town OS never downloads or caches blocklist feeds — providers are queried on demand as regular DNS zones.

• Provider zones — enable a category (DNSBL or RBL), then add provider zones. One-click suggestions include well-known lists such as Spamhaus (dbl.spamhaus.org, zen.spamhaus.org), SURBL, URIBL, SpamCop, and Barracuda; you can also add any custom zone. Each provider has its own on/off switch.
• Local entries — block a specific domain or IP by hand. Blocking a domain returns NXDOMAIN for forward lookups; you can note a reason for each entry.

Publishing Services in DNS

By default every installed package service is published in DNS under its network's TLD so you can reach it by name. Under DNS → Services you can toggle publishing per service — an unpublished service keeps running but is no longer resolvable by name. Each service's fully-qualified name follows the pattern <name>.<repo>.<tld> (for the default network, that TLD is .home).

Networks and Remote Access

Town OS groups your services into networks. Every box starts with a built-in network called home — it is LAN-only, resolves names under .home, and has no tunnel. To reach your services securely from outside your house, create additional networks: each one is a WireGuard overlay paired with its own DNS TLD, managed under Dashboard → Networks (admin only).

The Default Network

• Always present, can't be removed. The home network is created automatically and is where packages land unless you pick another.
• Local only. It has no WireGuard transport — .home names resolve on your LAN and are deliberately never exposed to remote peers.
• Uses the .home TLD, which comes from the dns_tld setting.

Creating a Network for Remote Access

Click Create Network and give it a name (for example office) and, optionally, a TLD (it defaults to the network name). Town OS then:

• Generates a WireGuard interface with a deterministic overlay subnet drawn from the 10.64.0.0/10 range, with the box itself as the .1 address.
• Claims the network's TLD (TLDs are unique per box — creating a network with a TLD another network already owns is rejected).
• Runs a per-network DNS resolver on the overlay so joined devices can resolve that network's names.

The Remote access switch on each row brings the WireGuard interface up or down. Turning it off cuts remote access while leaving the containers running and reachable locally.

Enrolling a Device

Open a network's Peers dialog, enter a device name, and click Add Peer. Town OS returns a ready-to-import WireGuard configuration — paste it into the WireGuard app on your phone or laptop.

Copy the config right away. It contains a freshly generated private key that is never stored — you cannot retrieve it later, and will have to enroll the device again if you lose it.

The generated config points the device's DNS at the box's overlay address, so your network's names resolve automatically once the tunnel is up. Leave the Runs rolodex DNS switch off for ordinary devices; enable it only for a peer that itself runs a rolodex DNS server you want to forward to.

WireGuard-Only Accounts

To let someone enroll their own devices without giving them run of the dashboard, create a WireGuard-only account (a checkbox on the Create User screen). Such an account:

• Is scoped to one or more specific networks — it can enroll peers only on those, and never on the home network.
• Is fail-closed: it can authenticate, enroll and refresh its own peers, and fetch the CA, but nothing else in the control plane.
• Enrolls expiring peers. Each enrollment carries a TTL (default 2 hours, set under Settings → WireGuard Peer TTL) and must be refreshed to stay connected; abandoned devices age out automatically. Peers an admin adds are permanent.

Watching and Disconnecting Peers

The Connected Peers panel on the Networks page lists every enrolled peer across all networks with its live handshake status, overlay IP, data transferred, and expiry. To forcibly cut a device off, use Disconnect — this removes the peer, tears its tunnel down immediately, and revokes its key, so the device cannot reconnect until it is enrolled again.

Installing Packages on a Network

The install dialog (and the Pages dialog) includes a Network selector. Whichever network you choose determines the service's DNS name and TLS certificate — a package installed on office resolves under .office and its certificate is issued for that name. Services on a non-default network are dual-homed: they resolve to the overlay address for tunnelled peers and to the LAN address for local clients. Reinstalling a package on a different network moves its DNS and certificates to that network's TLD.

For example, installing Jitsi on a network with the fart TLD publishes it at jitsi.default.fart. Once it's running, the service shows up on your Dashboard as a clickable link at that address, ready to open from any device on the 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. Use make qemu-fg to run it in the foreground with the serial console attached.

Booting a Physical USB (qemu-usb)

make qemu-usb USB_DEV=/dev/sdX

Boots QEMU in the foreground straight from a flashed physical USB stick instead of a built image — handy for confirming that a stick you just wrote actually boots. The device is opened read-only (snapshot), so guest writes are discarded and the real USB is never modified; the four virtual data disks are still attached for storage testing. This target does not build anything. On an x86_64 host, TARGET=aarch64 (or rpi) boots the stick under full-system emulation, so a foreign-arch image can be tested without the matching hardware.

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.

Hosting Static Sites

Beyond containerized packages, Town OS has built-in static site hosting, always on and managed under Dashboard → Pages. Each page is served by a shared web server behind the ingress and gets a DNS name and TLS certificate under its network's TLD, just like a package.

Content Sources

When you create a page you pick a name, a domain (defaults to the name), a network (defaults to home), and one of three content sources:

• Archive upload — upload a tarball of your site. The page waits in a pending state until you upload the archive.
• Git repository — clone from a repo URL. You can specify a branch (defaults to main), which is handy for sites published to gh-pages.
• Container image — extract a directory out of an OCI image.

Git and container pages provision asynchronously — the table shows a Provisioning… badge that resolves to active or error. Use Rebuild to pull the latest content for git and container pages; for an archive page, upload a new tarball instead.

How Pages Are Served

Each page lives on its own storage subvolume and is served directly over HTTP on port 80, while package services redirect port 80 to HTTPS. Because a page carries a network, its name resolves under that network's TLD and is reachable by your LAN and — if the network is a WireGuard overlay — by your enrolled remote devices.

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

Questions support several types beyond free text and port: secret (auto-generated when left blank), boolean (rendered as a checkbox), oauth (a Connect button that runs a provider's device-flow to obtain a token), and any question can be marked optional: true to allow it to be left blank. See the Packaging Format reference for the full list. At install time the operator also picks which network the package is served on.

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.