HomeServerHQ is an all-in-one home server infrastructure. It is designed to be simple and easy for anyone to setup and use, even without any prior software/IT experience. The installation and management utility performs the full installation of both the HomeServer and RelayServer, along with an integrated suite of free and open source software tools in less than an hour.

Even if you are behind CGNAT, you can still host an email server and/or public websites from your home, and remotely access your HomeServer from anywhere with any of your trusted devices. But it goes beyond just that. Due to a fairly novel networking approach, you'll effectively be running your own private internet. Security and privacy are the primary goals - all settings are pre-configured with safe, sane, and secure defaults.

For full instructions, see https://wiki.homeserverhq.com/getting-started

To verify source code, see https://wiki.homeserverhq.com/tutorials/source-code-verification

Table of Contents

• Supported Distributions
• One-line Start Installation
• Manual Installation
• Setup A Demo
• Comparison of Features
  • Home Server
  • Networking
• FAQ

Supported Distributions

Distribution
Ubuntu 22.04 (Jammy Jellyfish)	Stable
Ubuntu 24.04 (Noble Numbat)	Experimental
Debian 12 (Bookworm)	Experimental
Mint 22 (Wilma)	Experimental

One-line Start Installation

wget -q4N https://homeserverhq.com/hshq.sh && bash hshq.sh

Manual Installation

To perform the installation directly via GitHub (in case the webserver is unavailable), run the following commands as the first non-root user (ID=1000) on a fresh Ubuntu 22.04 installation:

cd ~
mkdir -p hshq hshq/data hshq/data/lib
wget -q4N https://raw.githubusercontent.com/homeserverhq/hshq/main/hshq.sh
wget -q4 -O hshq/data/lib/hshqlib.sh https://raw.githubusercontent.com/homeserverhq/hshq/main/hshqlib.sh
bash hshq.sh

Setup a Demo

See https://wiki.homeserverhq.com/en/tutorials/setup-demo for instructions on how to setup a demo environment.

Comparison of Features

With respect to self-hosting on a home-based server, HomeServerHQ has made significant progress along two avenues - the home server itself and the networking aspect. Thus, the comparison metrics are separated into these two categories accordingly. There is a more in-depth discussion of the differences following each of the comparison tables.

Home Server

---

Feature	HSHQ	Cloudron	YunoHost	HomeLabOS	Umbrel	CasaOS
Fully configured email server	✔️	✔️	❌	❌	❌	❌
Fully configured VPN	✔️	❌	❌	❌	❌	❌
Fully configured firewalls	✔️	❌	❌	❌	❌	❌
Auto-configure supported services	✔️	❌	❌	❌	❌	❌
Auto-integrate supported services	✔️	❌	❌	❌	❌	❌
Auto-monitor supported services	✔️	❌	❌	❌	❌	❌
Automatic https	✔️	✔️	❌	❌	❌	❌
Privately network with other HomeServers	✔️	❌	❌	❌	❌	❌
Tunnel/masquerade outgoing network traffic for specific docker containers	✔️	❌	❌	❌	❌	❌
No ports open on home router	✔️	❌	❌	✔️	❌	❌
Host email server and/or websites from home (on the public internet), even behind multiple layers of NAT/CGNAT	✔️	❌	❌	❌	❌	❌
Access with any type of device (desktop/laptop/cellphone/tablet) from anywhere	✔️	✔️	✔️	✔️	❌	❌
Add unlimited devices to your VPN	✔️	❌	❌	❌	❌	❌
Add your own custom services	✔️	❌	❌	❌	❌	✔️
Safe and secure infrastructure	✔️	❌	❌	❌	❌	❌
Production ready	✔️	✔️	✔️	❌	✔️	❌
Federation / ActivityPub ready	✔️	❌	❌	❌	❌	❌
Cryptographically-signed source code	✔️	✔️	❌	❌	❌	❌
Bring you own equipment	✔️	✔️	✔️	✔️	✔️	✔️
No IT experience needed	✔️	❌	❌	❌	❌	❌
Simple installation	✔️	✔️	❌	❌	✔️	✔️
Add multiple domains to the same HomeServer	✔️	❌	❌	❌	❌	❌
Add multiple HomeServers to the same primary RelayServer	✔️	❌	❌	❌	❌	❌
Installs apps	✔️	✔️	✔️	✔️	✔️	✔️
Updates apps	✔️	✔️	❌	❌	❌	❌
Console-based management UI	✔️	❌	❌	✔️	❌	❌
Web-based management UI	✔️	✔️	✔️	❌	✔️	✔️
Shiny and Pretty Web UI	❌	✔️	✔️	❌	✔️	✔️
Simple and streamlined backup/restore procedures	✔️	✔️	✔️	✔️	❌	❌
100% free and open source - no strings attached	✔️	❌	✔️	✔️	✔️	✔️
# of Files in Source Code Repository (Auditing)	5	13724	380	917	775	227

---

Probably the most central and useful aspect of an all-in-one approach is the idea of a one-click install. There are thousands of open-source projects that one can install, and clicking a single button to install it is very useful. You may even be enticed by the fancy web interfaces that some of these so called "all-in-one" projects employ - it seems professional and legitimate. However, in just about every case, you could have gotten that far by yourself with about the same amount of work. In general, you are being handed a much bigger workload, in that you have to configure and maintain it yourself. So these shiny and pretty web interfaces are nothing more than lipstick on a pig.

HomeServerHQ is a truly all-in-one approach - a cohesive integrated system, rather than just a disparate box of parts. Let's take an example, such as Nextcloud.

If you did a one-click install using these other so-called "all-in-one" projects, you would first have to start with creating an admin username/password. Then, if you want to tie in SMTP capabilities, i.e. for the system to send out informational emails, you would have to configure that as well. For creating additional users, you could utilize the built-in registration system, or if you have an LDAP server, you could use that instead, but you have to configure it. What about securely accessing it with the mobile app? What about monitoring the up/down status? What about some of the other integrations, such as video-conferencing with Jitsi, collaborative document editing with Collabora, anti-virus checking with ClamAV? The list goes on, and it's up to you to figure all of this out. It's not too difficult for a seasoned IT professional to do, but the time invested adds up, and Nextcloud is just one project.

On the other hand, when you install any supported service within HomeServerHQ's architecture, any and all available integrations are automatically performed on your behalf. Email is the natural connective tissue of the internet, and its no different in this case. Mailu was chosen as the mail server project. Of the total 60+ supported services, almost half of them have some sort of SMTP capability, which is fully configured during installation. Not every project employs LDAP for their user profiles, but the ones that do (around 15-20), have this configured as well.

Any new service is automatically:

• Imported into Portainer as a stack
• Added to Caddy in order to access via https
• Put behind Authelia for added protection
• Added to UptimeKuma for monitoring the up/down status
• Added to Heimdall - a beautiful home page with icons for all of the services

Almost half of the supported services use either MySQL/MariaDB or Postgres for their backend storage. So, these database containers are not only added to an internal network and viewable/queryable via SQLPad, but the database contents are also exported to flat file on an hourly basis with Ofelia. There are also numerous other smaller integrations as well, i.e. HomeAssistant data is sent to InfluxDB, Wazuh agents are installed on both HomeServer and RelayServer during Wazuh's installation, Single sign-on (SSO) with OIDC via Authelia for various services - the list goes on and on.

In short, all configuration options are investigated, and all integration options are exploited.

Networking

---

Feature	HSHQ	Tailscale	Headscale	Cloudflare Tunnels
Setup/Usage difficulty (1-10)	2	4	10	4
Decentralized	✔️	❌1	✔️	❌1
100% Open Source	✔️	❌2	✔️	❌
Host email server	✔️	❌	❌	❌
Host public website(s)	✔️	❌	❌	✔️
Port forwarding	✔️	❌	❌	❌
Connect remotely to private network	✔️	✔️	✔️	❌
Unlimited # of users	✔️	🔴3	✔️	✔️
Unlimited # of devices	✔️	❌	✔️	✔️
Prohibits unknown third-parties from having unencrypted access to your network traffic	✔️	❌	✔️	❌

¹Tailscale and Cloudflare are architecturally decentralized, yet from a corporate standpoint, there is only one Tailscale and one Cloudflare.

² Mostly open source, i.e. Mostly peaceful

³It depends on the pricing tier.

---

While the integrated systems approach is a significant improvement compared to other projects, the networking aspect puts HomeServerHQ into a class by itself. There is no other project on the planet that has anything like it - it's all entirely novel. To understand some of the background, we took the concept(s) of Cloudflare Tunnels, combined with the WireGuard capabilities expressed in Tailscale/Headscale, some influences from Stormblest/mistborn, the Cloud Bastion server component of HomeLabOS, as well as the overall idea of Federation popularized by Matrix.org. We originally set out to simply find a way around the self-hosting NAT/CGNAT issue(s) in an IPV4 world. But it turned into a much deeper and worthwhile exploration in which novel concepts emerged.

The reason why this approach is significantly safer and more secure than any other method is quite simple - NOTHING is exposed to the public internet. It is all PRIVATE networking and the data resides safe and sound in your home.

To get a better understanding of how it all works, the best place to start is our Architecture video. As illustrated in the video, the main thing to understand is the concept of a two-server setup: a HomeServer and a RelayServer. The HomeServer is the physical equipment in your home where the data resides, and the RelayServer is a lightweight access point so that you can connect to your HomeServer from anywhere. The RelayServer is like your router - it handles all of the incoming and outgoing traffic of your network. But it is a smart router. Rather than doing a simple passthrough like a bastion host, we instead incorporated smarter relay tools to allow for more efficient routing of traffic.

For example, to route https traffic for any websites that you want to host on the public internet, the RelayServer has its own reverse proxy. As requests come in, they will be routed appropriately to the correct internal host. This allows for unlimited internal hosts(HomeServers), as well as unlimited domains on a single HomeServer. We also applied the same concept to the email relay. It is a simple Postfix relay that inspects and determines the correct internal host and routes the mail accordingly. The mail relay also has a few added features such as:

• Basic spam detection with RSpamD - to limit unwanted email from even being forwarded
• Store and Forward - holds the mail for up to 30 days if the internal server cannot be reached
• Additional virus detection using ClamAV can also be added with a few minor configuration changes

While https and email have some form of Server Name Indication, not all types of services do, so the typical bastion server-style approach can be applied to any of the remaining ports (or port ranges).

There are simple-to-use tools on the managing HomeServer to perform nearly every common task on the RelayServer in just a few seconds. This includes anything from:

• Adding/removing a new secondary domain - You can add any number of secondary domains to a single HomeServer
• Adding/removing an exposed subdomain - Allows web sites to be hosted on the public internet from an internal HomeServer via the RelayServer
• Adding/removing a port forwarding rule - passes traffic that arrives at a port (or range of ports) on the RelayServer to a port (or range of ports) on a specific internal host
• Adding/removing a LetsEncrypt certificate request passthrough - this allows LE certificates to be issued to backend services on the HomeServer (which solves the problem that some mobile apps encounter with certificates signed by a custom CA)

The networking features described so far are somewhat known and typical regarding the concept of a generic relay server. However, when looking at our internal networking infrastructure, some really cool concepts emerged. A large amount of credit is given to the elegant and versitile design pattern of WireGuard. The split-tunnelling capabilities coupled with the peer-to-peer nature of the protocol allows for very advanced networking techniques, yet requires only a few lines of simple and straightforward configuration.

When you first set up your RelayServer, you HomeServer creates an outgoing persistent tunnel to the RelayServer. This connection is the means in which mail is delivered as well as server-to-server communications within your private network - it is your PrimaryVPN. When you invite another HomeServer to host on your network, you are providing them with a tunnel into your network as well, and the RelayServer is the central access point for all of the connections. On the other side of the coin, when you join someone else's network, you are provided a tunnel into THEIR network, which ingresses via THEIR RelayServer.

Each time you host on a different network, a new corresponding reverse proxy instance is created to serve that network. This reverse proxy will request certificates from the hosting network, using the SmallStep integration with Caddy (ACME Protocol). There is a default set of services that are exposed to other networks, but each instance can be customized differently, depending on your preferences for that network. This is where the whole concept of "overlapping private internets" comes from - you can simultaneously host on different networks, while picking and choosing which services to expose on which networks.

The reason that a new reverse proxy instance is generated for each new network is because there is currently no such thing as conditional TLS, i.e. conditional based on the IP address of the requestor - no open source projects support this idea. Thus, each reverse proxy instance must serve certificates with a chain signed by the root certificate of that network (otherwise all servers and client devices on the network would have to install a root certificate for each HomeServer - a mess!). We could have opted to use something like LetsEncrypt or ZeroSSL throughout, but there's no reason to overload their servers with this much traffic, and it's against the true spirit and essence of self-hosting with open-source software - especially when the tools exist.

All of these processes take place seamlessly in the background, the user is typically never aware of anything. The DNS and TLS in most cases are handled automatically as well (there are some advanced use cases where manual intervention is needed). The only thing that they will see is the occasional automated email informing them of a new HomeServer joining or an existing one leaving. Even as the manager of a network, the process is as simple as a few button clicks. There are also simple-to-use tools to both manage your network as well as connections to other networks. To add another HomeServer to your network (or join your HomeServer to another network) requires a three-part, two-email exchange (to exercice proper public-key cryptography practices).

FAQ

Q: Why one big bash script?

A: The source code is composed of two bash scripts, hshq.sh and hshqlib.sh. hshq.sh is a simple wrapper script that invokes hshqlib.sh. hshq.sh will rarely, if ever, change. hshqlib.sh will be regularly updated. By putting (nearly) everything into a single script (hshqlib.sh), it makes it much easier to:

1. Version - Each new version respects the changes made in the prior one, and the entire file is self-consistent.
2. Audit - It is much easier to view and monitor the changes in ONE file as opposed to many files, especially across numerous deltas.
3. Sign Code - As each new version is generated and posted, it is signed with a detached signature. Before a new version is accepted and applied, it is first checked for a valid signature. See this link for more details.
4. Transfer - At around 50k lines (currently), the file is still only about 1.8 MB in size, which makes it very lightweight for downloading newly updated versions. Even though this is rather large for a bash script, it is a function-based approach - there are around 900 functions.

Q: Does this cost money?

A: Yes. But then again, EVERYTHING has a cost. The short answer: For a typical home setup, it will cost about $400 to buy the equipment (if you have nothing to work with) and about $15 per month ongoing costs. The long answer: For the equipment, here is a guide for an affordable setup with around 4-6 active users. For the ongoing costs, unless you have a static IP address with your internet service provider (ISP), you will likely have to rent a VPS from a provider for your RelayServer. The RelayServer serves numerous valuable functions, with the most important being an access point for your mobile devices when you are not at home. It is very lightweight on resources, so it should run about $5-$10 per month. Here is a link for more details. You'll also need a domain name, which runs about $10-$15 per year, i.e. ~$1 per month. And finally, if you want to have access to help and support, another $40 per year (~$4 per month). So ~$400 fixed investment, ~$15 per month ongoing. Aside from that, all of the source code for this project and all related projects is fully free and open source, with no strings attached.

Q: I have other questions. Where do I get help?

A: As mentioned in the previous answer, help/support can be obtained via a Professional Support Subscription, which currently costs $40 per year. This is the sole revenue source for this platform, there is no corporate backing with a hidden agenda. Purchasing a subscription is completely optional and has no bearing on the operational capabilities of your infrastructure. It is merely a place to go to obtain help. You could be a complete novice with a "dumb" question or a seasoned expert with a very complicated inquiry. All questions are welcome and will be treated with the highest level of professionalism. Regardless of how "dumb" you might think a question is, there's a good chance that someone else might want to know the same thing. So just by asking, you're helping out others. In other words, there's no such thing as a dumb question - only dumb people for not asking.

Q: I want to have this, but I have no idea what I'm doing. Where do I start?

A: Go to the Getting Started section on the Wiki and walk through each of the provided topics. There are accompanying videos to assist as well. If you have read through everything and watched the videos and something still isn't clear, then you might have to sign up for a support membership to ask. It's impossible to know what is unclear unless you convey it in the form of a question. This will allow us to better address these ambiguities for everyone going forward.

Q: Can I test this out before buying anything?

A: Yes, and in fact this is highly recommended. It is something that you can do right now for less than $5 if your servers are only up for a couple of days. Basically, you are going to simulate your HomeServer equipment with a virtual private server (VPS) from a cloud provider. This link provides a walkthrough of setting up both HomeServer and RelayServer VPS's using a sample provider.

Q: My ISP does not allow port forwarding nor a static IP, can I still host from home?

A: Yes, without question you can host from anywhere, regardless of your circumstances, even behind NAT/CGNAT. This is probabaly our largest contribution to the community. You will have to rent a VPS as a RelayServer, which is pretty cheap - between $5-$10 per month. But it will perform the function as the front-end to your entire infrastructure. If you watch the Architecture video, you'll get a better idea of what role the RelayServer fulfills.

Q: Can this run in a virtual machine (VM)?

A: Yes and No. It has been extensively tested on a Proxmox hypervisor with no problems - it works perfectly. With Windows as the host OS, some problems with respect to networking have been reported, so a Linux-based host is highly recommended. As long as the VM's operating system is on the supported list, then it should work in just about any environment, but its impossible to know without confirmed tests.

Q: Is this IPV4 or IPV6?

A: Currently, this is purely IPV4. Yes, this does unfortunately contribute to the IPV4 address exhaustion issue in the short term. Migrating to either dual-stack and/or fully IPV6 is the largest and most important item on our roadmap. Another big reason is the network collision probability. All VPN networking utilizes the 10.0.0.0/8 space, with each network peeling off a random /24 from this block. There are 65,536 possible networks in this space (256x256), thus the probability of a full collision is pretty low, i.e. you randomly select the same /24 block as someone you want to network with. However, a partial collision (at least two people you network with have the same /24 block), has a real possibility of occurring. This is a birthday paradox problem. In short, the probability hits 1% at around 36 networks, which is not too terrible. With regards to IPV6 in general, there are so many different aspects to consider, with the biggest being production-grade stability for the average non-IT person. The migration process must be both simple to perform, while also maintaining backwards compatibility. So it might take a year or so for this to be rolled out. Once we have integrated IPV6, it is game, set, and match.