Concepts

Town OS is built around a set of core ideas. Understanding these concepts will help you make sense of how everything fits together — from defining a package to managing a running service.

Packages

A package is a self-contained YAML definition of a containerized service, pulled from a git repository. Each package specifies its container image, networking port mappings, storage volumes, environment variables, and interactive questions — everything needed to run the service. Packages declare supplies tags (like http, database, cache) to describe their capabilities. The default repository ships with 140+ pre-built packages.

Questions

When you install a package, Town OS may present interactive prompts called questions. Your responses fill @variable@ template placeholders throughout the package definition — setting hostnames, ports, credentials, and other options. Each question has a typed validator (hostname, port, bytes, volume, archive, duration, or free-form text) and an optional default value, so configuration errors are caught before the service ever starts.

Services

Once a package is installed, it becomes a service — a running container managed by a systemd unit. Town OS gives you start, stop, and restart control, live log streaming via Server-Sent Events, cursor-based journal pagination, and the ability to enable or disable services. Services are isolated from each other and from the host system.

Networking

Town OS includes rolodex, a standards-compliant DNS server with full DNSSEC validation and DANE support, providing ad and malware blocking for every connected device. Rolodex can also serve as a personal trust root for your network. Each package declares its own port mappings — external ports exposed to the host and internal ports available only between containers. Port values support @variable@ templates so users can choose ports at install time. UPnP forwarding, tunnels, and VPN attachments are handled automatically.

Storage

All data is stored on btrfs subvolumes with per-package isolation. Each volume has a mountpoint inside the container, a configurable quota (e.g. 512mb, 2gb), and optional uid/gid ownership. Volumes can be pre-populated from container images using the archives feature. Data persists across package reinstalls and upgrades — your files are never lost when you update a service.

Repositories

Packages are organized into repositories — git repos containing a packages/ directory with versioned YAML definitions. Every Town OS installation includes the default repository, but anyone can create and share custom repositories. Repositories are ordered — later entries override earlier ones when package names collide. A featured.json file can highlight selected packages in the UI.

Templates & Notes

The @variable@ template system connects user responses from questions to environment variables, port mappings, volume quotas, and more. Built-in variables like @LOCAL_EXTERNAL_HOST@ and @LOCAL_INTERNAL_HOST@ are always available. After installation, notes display key metadata like connection URLs, credentials, or contact information — with optional type validation for url, phone, and email.