Write Town OS to a USB drive:

curl -fsSL https://town-os.github.io/install.sh | bash
EARLY ALPHA

Town OS is under active development and is not yet ready for general use.

Town OS will format and use all detected local storage devices. Running it on a real computer will destroy your data.

A USB installer image is available for testing. If you just want to try it out safely, the VM instructions in the guide let you run Town OS in a virtual machine with no risk to your hardware.

Your Cloud in Your Closet

Town OS is a self-hosted platform that runs entirely from a USB drive. No installation. No cloud subscriptions. Just plug in and own your digital life.

View on Gitea See It in Action
💾

Write a USB Image

Build and write a bootable Town OS USB drive from source.

 🐛

Report a Bug

Gather logs, summarize errors, and file an issue on Gitea.

What is Town OS?

Town OS is a self-service platform that anyone can run at home, built for premier ease of use and reliability. It lives on a USB drive, runs entirely in memory, and dedicates all of your computer's storage to your stuff.

Upgrade by swapping a USB drive. Reset to a clean state by rebooting. No complicated installation procedures, no dependency on third-party cloud providers, and no monthly fees. Town OS puts you back in control.

Under the hood, Town OS manages storage with btrfs subvolumes, runs services in containers managed by systemd, and orchestrates networking automatically — including UPnP port forwarding, tunnel establishment, and per-package port mappings. It's a complete home server operating system built for real people.

Zero Installation

Boot from a USB drive. Town OS runs in RAM and uses your disks for data, not the OS.

Instant Recovery

Made a mistake? Reboot to return to a known-good state. Upgrade by replacing the USB drive.

Full Container Platform

Built for home and small office environments. Install services from package repositories with a clean UI — guided prompts configure each service, and networking and storage are managed automatically.

Getting Started

Clone the repository, run make dev, and open the URL shown in the terminal: 

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

Requires Linux with Podman, Go 1.25+, Bun, and btrfs-progs. See the getting started instructions for full prerequisites.

Built for Everyone

Smart Storage

btrfs-backed storage with per-package subvolumes, configurable quotas, and archive support. Volumes persist across reinstalls and upgrades — your data is organized and protected.

Integrated Networking

Manage your entire local network with rolodex, a standards-compliant DNS server with DNSSEC validation and DANE support — block advertisements and malware for every device in your home, and use it as a personal trust root for your network. Packages declare their own port mappings (external and internal), and Town OS handles UPnP forwarding, tunnels, and VPN attachments automatically.

Package Ecosystem

Install databases, web servers, media platforms, and collaboration tools with a click — configure through guided prompts. Anyone can create their own package repository and use it alongside the defaults.

Friendly UI

A clean, modern dashboard for managing services, storage, users, and packages. Designed to be safe and intuitive for non-technical users while powerful enough for admins.

Fast and Flexible

The OS runs entirely in RAM, so the system itself never touches your disks. Administrators get audit logging, live service logs, per-volume quota management, and a complete REST API with 51 endpoints.

Open Source

Licensed under GNU AGPL 3.0. The code is always available for examination, and must be released if it is packaged or changed by anyone else. Nobody can take advantage of Town OS users without someone knowing about it.

Default Package Repository

Every Town OS installation ships with the default-packages repository, which covers a broad range of self-hosted services:

Databases Web Servers Media Collaboration Monitoring Caching Search Messaging Storage Git Hosting

Packages like Gitea, Nginx, Plex, and most of the databases work today. The default repository also contains many experimental packages — pull requests to resolve issues with them are encouraged. You can also create your own private repositories — perfect for family, friends, or custom deployments.

Browse Packages on GitHub

Documentation

Concepts

Understand the core ideas behind Town OS — packages, questions, services, networking, storage, and repositories.

Packaging Format

Learn how packages are defined, how the template system works, and how to contribute your own packages.

API Reference

The complete API for controlling Town OS — 51 endpoints across accounts, storage, repositories, packages, systemd, settings, and audit.

Screenshots

See Town OS in action — the dashboard, package management, storage, and service supervision.