Your Cloud in Your Closet

Town OS is a self-hosted platform that boots from a USB drive and dedicates all of your computer's local storage to your data.

  • Updates to components arrive over the air.
  • The USB cannot be changed, enhancing security.
  • Almost everything is fixable with a reboot.
  • Core system upgrades are just a USB change.
Try It Out Quick Start Guide View on Gitea
Dashboard Dashboard Packages Packages Installation Installation Services Services

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. Packages can also be VMs or Windows applications via Proton, not just containers.

Write Town OS to a USB drive:

curl -sSLO https://town-os.github.io/install.sh && bash install.sh
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. See the Quick Start guide to write a USB drive and boot it, or use the VM instructions to try Town OS in a virtual machine with no risk to your hardware.

Built for Everyone

Smart Storage

Integrated, reliable storage that is not affected by the operating system at all.

  • Packages integrate with storage seamlessly — quotas can be managed per package
  • Archive and download volumes as compressed backups
  • Upload archives and maintain your own volumes manually if desired
  • RAID is automatically configured from existing disks, grouping for optimal redundancy at install time
  • Your data stays organized and protected

Integrated Networking

Manage your entire local network from one box.

  • Built-in DNS with DNSSEC validation and DANE support via rolodex
  • Ad and malware blocking for every device on your network
  • Automatic UPnP forwarding, tunnels, and VPN attachments
  • ACME certificate management coming soon
  • DHCP and full router functionality coming soon

Package Ecosystem

Install services with a click, configure through guided prompts. Create your own repositories alongside the defaults.

  • Make one for your neighborhood or multi-office business
  • Control your chain of coffee shops
  • Own your whole stack on your Mom & Pop ISP
  • Get your parents or kids safe with the tools you want them to use
  • Start a Mastodon network or Minecraft for your children's friends
  • Gitea, Jitsi, Plex, databases, web servers, and more
  • Publish static HTML sites directly from the UI
  • Networking and storage managed automatically per package

Friendly UI

A clean dashboard for everyone.

  • Manage services, storage, users, and packages
  • Built-in audit logging for every action
  • Live systemd journal integration for service logs
  • Grafana, Prometheus, and Node Exporter dashboards set up automatically
  • Available in 21 languages — community translations welcome
  • Safe and intuitive for non-technical users, powerful enough for admins

Fast, Flexible and Secure

The OS runs entirely in RAM — your disks are for your data.

  • Immutable operating system on USB — tamper-resistant by design
  • Over the air updates for components
  • Seamless upgrades — most things can be fixed by a reboot
  • Audit logging and live service logs
  • Per-volume quota management
  • Package upgrade detection with dashboard notification
  • Complete REST API — clients already exist and will be published soon

Open Source

Licensed under GNU AGPL 3.0.

  • Code is always available for examination — by security professionals, automated scanners and watchdogs alike
  • Must be released if packaged or changed by anyone
  • Nobody can take advantage of users without someone knowing

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.