Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

StartOS

A Linux-based operating system purpose-built for running a personal server. Install, configure, and manage self-hosted services through a simple graphical interface — no command line required.

  • App store experience — discover and install services from a marketplace with one click
  • Built-in networking — LAN, Tor, VPN, and clearnet access managed through the UI
  • Encrypted backups — back up and restore services to physical drives or network shares
  • No accounts, no cloud — your server, your data, no third parties

Getting Started

User Manual

Learn More

Installing StartOS

This guide is for flashing StartOS to a USB drive, then installing it onto a desktop, laptop, or mini PC. For an up-to-date list of known-good hardware, please check out this forum post.

Download

  1. Visit the Github release page to find the latest version of StartOS.

  2. Under “ISO Downloads”, select the ISO for your architecture. StartOS is available in x86_64 (AMD64), aarch64 (ARM64), and RISC-V (RVA23). For x86_64 and aarch64, two variants are available:

    • Standard: Includes proprietary firmware and drivers for broader hardware compatibility, including display and wireless. Recommended for most users.

    • Slim (FOSS-only): 100% open source, containing no proprietary firmware or drivers. Only compatible with certain hardware, such as the Start9 Server Pure.

  3. Verify the SHA256 checksum against the one listed on GitHub (optional but recommended).

    • Mac. Open a terminal and run:

      openssl dgst -sha256 <filename>.iso

    • Linux. Open a terminal and run:

      sha256sum <filename>.iso

    • Windows. Open PowerShell and run:

      Get-FileHash <filename>.iso

Flash

  1. Download and install balenaEtcher onto your Linux, Mac, or Windows computer.

  2. Insert your USB drive into your computer.

  3. Open balenaEtcher.

  4. Click “Select Image” and select the .iso image you just downloaded.

  5. Click “Select Target” and select your microSD card.

    Warning

    BE ABSOLUTELY CERTAIN you have selected the correct target USB flash drive. Whatever target you select will be COMPLETELY ERASED!!

  6. Click “Flash!”. You may be asked to approve the unusually large disk target and/or enter your password. Both are normal.

Install

  1. Remove the newly-flashed USB drive from your computer and plug it into your server. Choose the fastest available USB 3.0+ port - typically this is blue or labeled “SS” (SuperSpeed).

  2. Power on your server, booting from USB.

    Tip

    Occasionally, you may need to make some changes in your BIOS, such as turning off Secure Boot, or allowing USB boot for install. See the Community Hub for guides or to get help.

  3. The StartOS install wizard will now be available at http://start.local. You can also use a monitor, keyboard, and mouse. This is known as “Kiosk Mode”.

  4. Choose “Re-Install” to preserve existing StartOS data, or “Factory Reset” to start fresh. After install is complete, you will be prompted to remove the USB drive and refresh the page.

User Manual

This section covers everything from initial setup and certificate trust to network access methods (LAN, VPN, Tor, Holesail, clearnet), service installation, backups, and system administration.

Initial Setup

  1. Connect your server to power and Ethernet.

  2. From a computer connected to the same Local Area Network (LAN) as your server, open a browser and visit http://start.local.

  3. Select a setup option:

    • Start fresh: Select this option if you are setting up a new server.

    • Restore from Backup: Select this option only if your existing StartOS data drive has been lost or corrupted. This is for disaster recovery only.

    • Transfer: Select this option if you are transferring your existing data from one drive to another.

  4. Set a strong master password. Make it good. Write it down. Resetting your password is non-trivial, but your data will be preserved.

  5. Set your server name. Your server’s unique .local hostname is derived from this name. You can change your server name later in System Settings.

  6. Following successful initialization, you will be prompted to download a StartOS-info.html. This file contains your server’s permanent .local URL and Root Certificate Authority (Root CA). It is recommended to save this file for future reference.

  7. Click “Continue to Login” and follow instructions for Trusting your Root CA

Trusting Your Root CA

In order to establish a secure (HTTPS) connection with your server on the local network, it is necessary to download and trust your server’s Root Certificate Authority (Root CA).

Note

You must repeat this guide for each device you want to connect to the server locally or using a VPN. This guide is not necessary for devices that will connect using Tor, Holesail, or clearnet.

Watch the video

Step 1 - Download

There are multiple ways to download your server’s Root CA.

  • Option 1: StartOS-info.html

    Following initial setup, you were required to download a StartOS-info.html file. Your Root CA can be downloaded from this file.

  • Option 2: HTTP LAN

    Visit your server’s HTTP (not HTTPS) .local address (http://your-server-name.local) or LAN IP address (http://192.168...).

  • Option 3: StartOS Dashboard

    If you are logged into your server, click the “System” tab or the “Start Menu” (upper right corner), then click “About this Server”.

  • Option 4: Yourself

    If you already have the Root CA on one device, you can send it to yourself using email or other messaging channel.

Step 2 - Trust

Select your platform:

  1. Locate your Root CA and double click it. Keychain Access will launch. You will be prompted for your Mac credentials. Select “Modify Keychain”.

  2. Press Command + Spacebar to launch a program, type in Keychain Access and select the resulting Keychain Access program to open it.

  3. Your server’s CA certificate will be displayed among the imported certificates in Keychain Access. Right-click on the imported CA cert and select Get Info:

  4. The details of your CA certificate will be displayed in a new dialog window. Click the “Trust” heading, then select “Always Trust” on Secure Sockets Layer (SSL) and X.509 Basic Policy.

    Click the red (x) button at the top left of the Local Root CA dialog window.

  5. You will then be prompted again for your Mac credentials. Click Update Settings:

  6. You will see your server’s CA certificate as trusted now, signified by a blue (+) sign and the CA cert information will now say “This certificate is marked as trusted for all users” in Keychain Access:

  7. If using Firefox, Thunderbird, or Librewolf, complete this final step.

3. Mozilla Apps (Firefox, Thunderbird, Librewolf)

Mozilla apps use their own certificate store and need extra configuration to trust your Root CA. Complete the steps above for your OS first, then follow the steps below.

For more background, see Mozilla’s blog post on why they maintain their own root certificate store.

  1. Open the app and enter about:config in the URL bar. Accept any warnings that appear.

  2. Search for security.enterprise_roots.enabled and set the value to “true”.

  3. Restart the app.

Private Access

Private access means only you and people you explicitly authorize can reach your server. There are four methods available, each with different use cases and tradeoffs.

  • LAN. Same local network. The fastest connection method. Uses mDNS or IP address.

  • VPN. Fast, private, personal access from anywhere in the world using a VPN server running on your router or VPS.

  • Tor. Anonymous .onion addresses on the private Internet. Requires installing the Tor service from the marketplace.

  • Holesail. Direct, encrypted peer-to-peer tunnels with no port forwarding or static IP required. Requires installing the Holesail service from the marketplace.

LAN

Connect to your server over your local network using its .local mDNS address or direct IP address. This is the fastest connection method, as traffic stays on your LAN and never reaches the Internet.

Use Case

Local connections are the fastest possible, as they do not reach out to the Internet. You must be connected to the same Local Area Network (LAN) as your server.

Watch the Video

Option 1: Local domain

During initial setup, you choose a server name, and your .local domain is derived from it. For example, a server named “My Cool Server” gets the domain my-cool-server.local. This domain uses Multicast DNS (mDNS) to serve as an alias for your server’s LAN IP address. You can change your server name at any time in System Settings.

Tip

The local domain is useful because, by default, your router will sometimes change your server’s IP address on the LAN. If your server’s LAN IP address changes, the local domain will continue to work, even if you move or get a new router!

Option 2: IP Address

Your router automatically assigns your server an IP address on the LAN. The address can be found (1) in your StartOS dashboard at System -> StartOS UI, (2) in your router dashboard, or (3) by pinging your server’s .local domain from the command line of a computer on the same network.

Important

Your router may unexpectedly change your server’s IP address on the LAN. To avoid this, we highly recommend assigning a static IP address. This becomes necessary if you intend to access your server via VPN or clearnet. It also makes the local domain unnecessary. All routers support setting a static IP address for devices on the LAN. Refer to your router’s user manual for detailed instructions.

Private Domains

A private domain is similar to your server’s local domain, except it also works for VPN connectivity, and it can be anything. It can be a real domain you control, a made up domain, or even a domain controlled by someone else.

Similar to your local domain, private domains can only be accessed when connected to the same LAN as your server, either physically or via VPN, and they require trusting your server’s Root CA.

Adding a Private Domain

  1. If you haven’t already, assign a static IP address to your server on the LAN. Refer to your router’s user manual for detailed instructions.

  2. On the service interface page, click “Add Domain” on the desired gateway table and select “Private Domain”.

  3. Enter a fully qualified domain name. It can be anything. For example: domain.com, private.domain.internal, nextcloud.private, nextcloud.fake-tld, or facebook.com.

  4. Click “Save”.

  5. StartOS will automatically test your DNS configuration. If the test passes, the domain is ready to use. If it fails, a setup modal will appear with instructions to configure your DNS server and the ability to re-test.

DNS for Private Domains

Private domains require your gateway to use StartOS for DNS. StartOS will test this automatically when you add a private domain and guide you through the setup if needed. For more details, see DNS.

VPN

Access your server privately from anywhere in the world by routing traffic through a VPN server on your router or a cloud VPS. Only authorized devices with the VPN configuration can reach your server.

Use Case

This connection method is ideal for fast, private, personal access from anywhere in the world using a VPN server running on your router or VPS. Only authorized devices have access to your server and installed services.

Tip

Private domains also work over VPN — see Private Domains.

Option 1: Router

Most modern routers include a VPN server feature. If so, it is usually the preferred method for private, remote access to your server.

  1. If you haven’t already, assign a static IP address to your server on the LAN. Refer to your router’s user manual for detailed instructions.

  2. Since home IP addresses can change without warning, we highly recommend setting up dynamic DNS. Many routers offer this as a built-in feature. If not, third-party services are available. Without dynamic DNS, a change to your home IP will disconnect all VPN clients until you re-download configuration files for each one.

  3. Enable your router’s VPN server. Refer to your router’s user manual for detailed instructions.

Option 2: StartTunnel

By default, StartTunnel exports wireguard config files that are configured for split tunneling, allowing you to use your StartTunnel VPN to access your StartOS server and installed services while also preventing it from being automatically used for all Internet traffic.

There are three reasons to select this option:

  1. Your router does not offer a VPN server.
  2. Your router’s VPN server is not automatically configured for split tunneling.
  3. You are already using StartTunnel for clearnet hosting, so most of the work is already done.

To use StartTunnel for private, remote VPN access, see StartTunnel.

Connecting Clients (WireGuard)

Once you have successfully enabled a VPN server on your router or added a StartTunnel gateway, follow the instructions below.

  1. Obtain a WireGuard config file for your device.

    • StartTunnel: Follow instructions here
    • Router: Follow your router’s instructions.

  2. Install WireGuard and import your config file:

  1. Install WireGuard from the App Store.

  2. Open the WireGuard app, click “Import tunnel(s) from file”, and select the config file.

  3. MacOS will inform you that WireGuard wants to set up a VPN connection. Click “Allow”.

  4. Your VPN tunnel will have been created and visible in both your Mac’s system settings and in the WireGuard app where you can click to activate it.

    Tip

    You may need to edit your newly created tunnel and enable “On-demand” for either ethernet, wifi, or both.

Connecting Clients (OpenVPN)

Note

OpenVPN is only available when using a router-based VPN server. StartTunnel uses WireGuard.

  1. Download the configuration file from your router’s OpenVPN server.

  2. Install OpenVPN and import your config file:

  1. Install the OpenVPN Connect client from the official website.

  2. If asked to do so, allow the OpenVPN client to run in the background.

  3. Import the configuration file and enter the necessary authentication settings you chose or were default on your OpenVPN server on your router.

  4. Depending on how you’ve configured your OpenVPN server, you may need to add a username and password before you hit Connect.

  5. Once set up, click on the name of the profile to connect and disconnect. You can edit the profile from the icon to its right.

Tor

Access your server over the Tor network using .onion addresses. This method provides anonymous, censorship-resistant connections and requires installing the Tor service from the StartOS marketplace.

Use Case

This connection method permits hosting services on the private Internet (aka the “Darknet”) as anonymous (.onion) domains.

There are three reasons you might want this:

  1. Unless you share/leak a Tor address, it is totally private and anonymous. Nobody knows it exists, and nobody knows it belongs to you. It is your secure, secret tunnel to the underlying website/API.

  2. If you share/leak a Tor address without associating it to your identity (not easy to do), it is anonymous but not private. People know it exists, but nobody knows it belongs to you. By this method, you can anonymously host a censorship-resistant website/API on the private web.

  3. If you share/leak a Tor address and also associate it with your identity, it is neither private nor anonymous. People know it exists, and they know it belongs to you. This is useful for hosting an identified yet still censorship-resistant website/API on the private web, or for sharing access to the websites/API with select friends and family.

Warning

It is normal for Tor connections to be slow or unreliable at times.

Tip

Tor can also be used for public access by publishing your .onion addresses.

Setting Up Tor

Tor is not included in StartOS by default. To use Tor, you must install the Tor service from the marketplace.

  1. Go to the Marketplace and install the Tor service.

  2. Start the Tor service and wait for it to become healthy.

Managing Onion Services

Once Tor is installed and running, you can create .onion addresses for specific service interfaces on your server.

  1. Open the Tor service and go to Actions > Manage Onion Services.

  2. Select a service interface to create an onion address for.

  3. To view your onion addresses, go to Actions > View Onion Addresses.

Tip

When creating an onion service, you can upload a private key to use a vanity address. For instructions on generating a vanity address, see here.

Note

Each onion domain produces two addresses: HTTP and HTTPS. Because Tor is a secure protocol, it is perfectly safe to use the HTTP address. It is also preferable, because it does not require anyone to trust your server’s Root CA. Some applications may require HTTPS, in which case the certificate is signed by your server’s Root CA.

Connecting over Tor

Using a Tor Browser

You can connect to your server and installed services from anywhere in the world, privately and anonymously, by visiting their unique http://....onion URLs from any Tor-enabled browser.

Tip

Recommended Browsers

Running Tor in the Background on your Phone/Laptop

By running Tor in the background on your phone or laptop, certain apps can connect over Tor, even if the apps themselves do not natively support Tor.

For instructions specific to your device’s operating system, use a search engine or AI. This capability is well documented.

Holesail

Access your server remotely using Holesail’s peer-to-peer tunneling. This method creates direct encrypted connections without port forwarding, static IPs, or centralized servers, and requires installing the Holesail service from the StartOS marketplace.

Use Case

Holesail creates direct, encrypted peer-to-peer tunnels between your devices and your server. No port forwarding, static IP, or centralized servers are required. Traffic flows directly between peers as if they were on the same local network.

This is a good option when:

  1. You want fast, private remote access without the complexity of setting up a VPN server.
  2. You don’t have control over your network (e.g. work, school, shared housing) and cannot configure port forwarding.
  3. You want a simple, zero-configuration alternative to Tor that offers better performance.

Setting Up Holesail

Holesail is not included in StartOS by default. To use Holesail, you must install the Holesail service from the marketplace.

  1. Go to the Marketplace and install the Holesail service.

  2. Start the Holesail service and wait for it to become healthy.

Managing Tunnels

Once Holesail is installed and running, you can create tunnels for specific service interfaces on your server.

  1. Open the Holesail service and go to Actions > Manage Tunnels.

  2. Select a service interface to create a tunnel for. Each tunnel produces a unique connection key.

  3. To view your tunnel connection keys, go to Actions > View Tunnels.

Note

Anyone with the connection key can access the tunnel. Treat connection keys like passwords — only share them with trusted devices.

Connecting over Holesail

To connect to a Holesail tunnel from a client device, install the Holesail client and use the connection key provided by your server.

For client installation and usage instructions, see the Holesail documentation.

Public Access

Public access means making your services reachable by anyone on the Internet.

  • Clearnet. Host services on the public Internet using standard (.com, .net, etc) domains or public IP addresses.

  • Tor. Host services as .onion addresses for censorship resistance and optional anonymity.

Clearnet

Make your services publicly reachable on the Internet using standard domains (.com, .net, etc.) or public IP addresses. This requires a gateway, a domain name, and DNS configuration.

Use Case

This connection method permits hosting a service interface on the public Internet.

Choosing a Gateway

When hosting services on the clearnet, anyone who connects will know the IP address of the gateway used. Knowing a gateway’s IP address reveals its approximate geographic location:

Geographic LocationDetection Accuracy
Country99%
State / Region95-99%
City (large metro)60–80%
Zip Code / Neighborhood30–50%
Exact Street AddressRequires ISP subpoena

If your gateway is your home router, you are revealing the approximate location of your home. If your gateway is a VPS running StartTunnel, you are revealing the approximate location of the VPS, not your home.

Which gateway you select will depend on your threat model and budget:

  • Router: If you have no issue revealing your approximate location, use your router as your clearnet gateway (free). Since home IP addresses can change without warning, we highly recommend setting up dynamic DNS. Many routers offer this as a built-in feature. If not, third-party services are available. Without dynamic DNS, a change to your home IP will make your domains unreachable until you update their DNS records.

    Warning

    If your Internet Service Provider (ISP) uses Carrier-grade NAT (CGNAT), such as Starlink, it means you share an IP address with other customers. It is not possible to use your router as a clearnet gateway. You must use StartTunnel instead.

  • StartTunnel: If you want to obfuscate your home IP address, or your ISP uses CGNAT, you can use a StartTunnel gateway. Refer to the StartTunnel guide.

Adding a Public Domain

With few exceptions, you should add a domain to your service interface so that you and others can access it seamlessly, just like any other website or API.

  1. On the service interface page, click “Add Domain” on the desired gateway’s table and select “Public Domain”.

    Warning

    CGNAT gateways, such as Starlink, cannot be used for clearnet hosting. You must use a StartTunnel gateway. Refer to the StartTunnel guide.

  2. Enter the fully qualified domain name. For example, if you control domain.com, you could enter domain.com or public.domain.com or nextcloud.public.domain.com, etc.

  3. Select a Certificate Authority to sign the certificate for this domain.

    • Local Root CA: Good for personal access. Only devices that have downloaded and trusted your server’s Root CA will be able to access the domain without issue.
    • Let’s Encrypt: Good for public access. All devices trust Let’s Encrypt certificates by default.

  4. Click “Save”.

  5. StartOS will automatically test your DNS record and port forwarding. If both pass, the domain is ready to use. If either test fails, a setup modal will appear showing the failing tests with instructions to remedy and the ability to re-test.

Configuring DNS

StartOS tests DNS automatically when you add or enable a public domain, and will guide you through the setup if the test fails. For reference, here is what is needed:

  1. Access your domain’s DNS settings, usually in the registrar where you originally leased the domain.

  2. Create a DNS record that points your domain to your gateway’s public IP address. If you use subdomains, consider creating a wildcard record (e.g., *.domain.com) so that future subdomains work without additional records.

    Tip

    It might take a few minutes for DNS changes to propagate. You can check propagation using https://dnschecker.org.

Port Forwarding

To expose a public domain or public IP address to the Internet, the appropriate port must be forwarded in the corresponding gateway. StartOS tests port forwarding automatically when you add or enable a public address, and will guide you through the setup if the test fails.

Tip

Most websites and APIs on the Internet are hosted on port 443. Port 443 is so common, in fact, that apps and browsers infer its presence. The absence of a port means the port is 443. With rare exceptions, domains on StartOS also use port 443, and that is why your domains usually do not display a port. The port forwarding rule needed for these standard domains is always the same, which means you only have to do it once!

How you create a port forwarding rule depends on the type of gateway.

  • Routers: Port forwarding is supported by all routers and easy to do. Refer to your router’s manual for instructions.

  • StartTunnel: Refer to the StartTunnel Port Forwarding guide.

Tor

Tor onion addresses (.onion) can be used for public hosting. Unlike clearnet domains, onion addresses do not require purchasing a domain, configuring DNS, or opening ports. Anyone with a Tor-enabled browser can reach them.

Why Use Tor for Public Hosting

  • Censorship resistance. Onion services cannot be taken down by domain registrars, DNS providers, or ISPs. As long as your server is running, the address is reachable.

  • Anonymity (if done carefully). If you publish an onion address without associating it with your identity, observers can access your service but cannot determine who operates it. Achieving true anonymity requires careful operational security — for example, never linking the address to your real identity, and not leaking metadata that could be correlated.

  • No infrastructure dependencies. You do not need a static IP, a domain name, or port forwarding. Tor handles routing entirely through its overlay network.

Setup

Tor public hosting uses the same Tor service as private access. Follow that guide to install Tor from the marketplace, create onion services, and view your onion addresses.

The difference is simply in how you use the addresses: keeping them secret (private access) vs. sharing them publicly (public access).

Note

Each onion domain produces two addresses: HTTP and HTTPS. Because Tor is a secure protocol, it is perfectly safe to use the HTTP address. It is also preferable, because it does not require visitors to trust your server’s Root CA.

System Settings

General system settings for your StartOS server. Navigate to System > General Settings in the StartOS dashboard.

Software Update

View your current StartOS version and check for updates.

  • If an update is available, click Update to begin the update process.
  • After updating, click Restart to apply to reboot your server with the new version.
  • If no update is available, click Check for updates to query the latest release.

Server Name

Your server name is displayed along with its derived .local hostname. The hostname is created by lowercasing the server name, removing non-alphanumeric characters, and replacing spaces with hyphens. For example, “My Cool Server” becomes my-cool-server.local.

Click Change to open the server name dialog. After saving a new name, your .local address will update accordingly.

Warning

If you are currently connected via your .local address, changing the hostname will require you to switch to the new .local address. You will be prompted with the new address after saving.

Language

Change the display language of the StartOS interface. Select a language from the dropdown to apply it immediately.

Kiosk Mode

Kiosk Mode enables a display output for connecting a monitor directly to your server. This is useful for setup or troubleshooting without a separate client device.

  • Enable: If no keyboard layout has been set, you will be prompted to select one first. A restart is required to apply the change.
  • Disable: Click Disable, then restart when prompted.
  • Change Keyboard Layout: When Kiosk Mode is enabled, your current keyboard layout is displayed. Click the edit icon to select a different layout.

Note

Kiosk Mode may be unavailable on certain hardware.

Installing Services

StartOS services are installed from the Marketplace, which consists of curated registries. You can also sideload packages directly from .s9pk files.

From the Marketplace

The Marketplace is made up of multiple “registries”. A registry is a curated list of services that can be downloaded and installed onto StartOS. You can think of a registry as just one “store” or “booth” inside a broader marketplace.

StartOS comes preloaded with two default registries: (1) The Start9 Registry and (2) the Community Registry.

Services in the Start9 Registry are vouched for, recommended, supported, and maintained by Start9. Services in the Community Registry are not. For a more detailed explanation of the Registry framework, check out this short blog post.

To install a service from the marketplace, simply visit the Marketplace, select a service, and click “Install”.

Switching Registries

To switch between registries or add a custom registry, simply click arrows underneath the current Registry title.

Sideloading

Sideloading is useful if you are testing a service that does not yet exist on a registry, or if you prefer to eliminate the Marketplace as a point of trust. An s9pk can be obtained from anywhere or even built from source code.

To sideload a service, go to Sideload and upload the appropriate .s9pk file.

Gateways

A gateway is what connects your server to the Internet. There are two types of gateways: outbound only and inbound/outbound.

Inbound/Outbound Gateways

An inbound/outbound gateway handles traffic in both directions — it routes outbound traffic and accepts inbound connections from the Internet. Your router is an inbound/outbound gateway. StartTunnel is also an inbound/outbound gateway.

Think of the inbound side as a defense perimeter with hundreds of locked doors, each door leading to a unique service interface. For example, one door might say “Vaultwarden UI”, another might say “Bitcoin RPC”, and yet another might say “Bitcoin P2P”.

If you want to let a specific person through a particular door, you give them a key. This is the equivalent of giving someone private VPN access to a specific service interface. If you want to let everyone through a particular door, you remove the lock altogether. This is the equivalent of forwarding a port in your gateway, thereby exposing a particular service interface or domain to the public Internet.

Note

If you are running StartOS on a VPS with a public IP address, there is no local network. Your gateway is inherently public and open to the Internet.

For guidance on choosing a gateway for clearnet hosting, see Clearnet.

Outbound Only Gateways

An outbound only gateway (or outbound VPN) routes traffic from your server to the Internet but does not accept inbound connections. A common example is a commercial VPN provider such as Mullvad or ProtonVPN. When you add a gateway to StartOS using a standard WireGuard configuration file, StartOS automatically detects it as an outbound only gateway.

You might want an outbound only gateway to hide your server’s real IP address from external services, protect against your ISP monitoring or logging your traffic, or route sensitive services through a trusted VPN provider for added privacy.

Adding a Gateway

  1. Navigate to System > Gateways and click “Add”.

  2. Upload or paste the WireGuard configuration file from your VPN provider or StartTunnel instance.

    StartOS will automatically detect the gateway type:

    • StartTunnel config files are recognized and marked as inbound-outbound gateways, capable of both receiving inbound connections and routing outbound traffic.
    • All other WireGuard configs (e.g. Mullvad, ProtonVPN, or any standard WireGuard provider) are marked as outbound-only gateways.

Outbound Traffic

By default, StartOS dynamically selects which gateway to use for outbound traffic for maximum performance. You can override this behavior using the select dropdown in the “Outbound Traffic” section underneath the “Gateways” table. This forces all outbound traffic for everything on the server through the selected gateway.

Per Service Overrides

You can further override this on a per-service basis by navigating to a service and going to Actions > Set Outbound Gateway. This is useful for routing sensitive services through a commercial VPN while leaving other services on the default.

DNS

StartOS runs its own DNS server to resolve private domains for services on your server. This page covers how DNS works on StartOS and when you might need to change it.

How It Works

By default, StartOS obtains its DNS servers from your router via DHCP. For most users, the default settings require no changes. When you add a private domain, StartOS automatically creates a DNS record on its internal DNS server.

For private domains to work, the gateway they are assigned to must use StartOS for DNS. StartOS will test this automatically and guide you through the setup if needed. The details depend on your gateway type:

  • Router: Set StartOS as your router’s primary DNS server. All routers support this feature. Refer to your router’s user manual for detailed instructions.

    Warning

    It is possible that StartOS is already using your router for DNS. In this case, you cannot instruct your router to use StartOS for DNS, as this would be circular. If StartOS detects a potential circular DNS situation, it will warn you. To resolve this, switch to static DNS servers so StartOS no longer relies on your router.

  • StartTunnel: SSH into your StartTunnel VPS and run the following command:

    start-tunnel dns defer

Tip

If your private domain is a real domain that you control, you can alternatively configure its DNS record at your registrar to resolve to your server’s LAN IP address. In this case, the StartOS DNS server is not needed.

Static DNS Servers

To view or change the DNS servers StartOS uses, navigate to System > DNS. To override the defaults, select “Static” and provide up to three DNS servers in order of preference.

Note

If you want to use a specific DNS provider (such as Cloudflare or Quad9), it is generally better to configure it in your router so that all devices on your network benefit, not just your server.

Creating Backups

Important

Creating backups is an essential responsibility of self-hosting. If you do not make backups, you will eventually lose your data.

Watch The Video

What You Need to Know

  1. You can create backups to a physical drive plugged directly into your server, or over-the-air to another device on the same LAN (a network folder).

  2. Backups are encrypted using your master password. If you change your password prior backups retain the original password.

  3. Services may choose to exclude certain files or folders from the backup. For example, Bitcoin excludes the blockchain, since it can be recovered by re-syncing.

  4. Backups can take minutes or hours to complete, depending on your hardware and quantity of data.

  5. A service cannot be used while it is backing up. You may, however, continue to use your server and other services.

  6. Upon completion, StartOS issues a backup report, indicating which services were backed up, as well as any errors.

  7. Backups taken from a specific system architecture (x86, ARM, RISC-V) are backed up for just that architecture. If restored to another architecture, they will likely need to be reinstalled to run efficiently.

Best Practices

Even with proper backups the risk of data corruption is always non-zero. Therefore it is recommended to take additional care when backing up highly valuable or irreplaceable data like a lightning node:

  • High quality SSDs should be favored over HDDs as a backup target.
  • Backup to multiple targets.
  • If backing up to multiple targets make sure all backups are up to date.

Physical Drive

EXT4 is the recommended format of your backup drive. fat32 and exFAT are not recommended and may not work.

Warning

Backing up to USB thumb drives or SD card media is not recommended unless you are using high-endurance, high-quality storage. Low-quality flash memory is prone to corruption and failure over time.

If you are using a Raspberry Pi, backup drive must be self-powered, or be connected via a powered USB hub, to prevent possible data corruption.

Network Folder

A network folder backup sends your encrypted backup over the LAN to a shared folder on another device. First, create a shared folder on the target device, then connect to it from StartOS.

Step 1. Create a Shared Folder

  1. Identify or create a folder to store your server backups.

    Tip

    This folder can be located on an external drive connected to your Mac.

  2. Go to System Settings > General > Sharing and click the “info” icon.

  3. Click the toggle to enable file sharing, then click the “plus” icon and select your backups folder.

  4. Click “Options”.

  5. Select the user who owns the folder.

Tip

You can find the hostname at the top of the sharing window. The hostname will be an address beginning with smb://. To use as hostname, disregard the smb:// and simply enter the IP address that follows it. Alternatively, you can use the computer hostname (open Terminal and type hostname). Either method will work.

Step 2. Connect from StartOS

  1. In StartOS, go to System > Create Backup.

  2. Click “Open New”.

  3. Complete the form:

  1. Hostname: The hostname or IP address of your Mac (see the tip in the section above).
  2. Path: The name of your shared folder, not the full directory path.
  3. Username: Your Mac user who owns the shared folder.
  4. Password: Your password for the above user.

Warning

If you receive Filesystem I/O Error mount error(13): Permission denied, ensure you have entered the correct values. The hostname can be particularly tricky.

Restoring Backups

Restore previously created backups to recover individual services or your entire server. This is for disaster recovery when a service is accidentally uninstalled or when your data drive is lost or corrupted.

Restoring Individual Services

This option should only be necessary if you accidentally uninstall a service.

  1. Go to System -> Restore from Backup
  2. Select your backup drive.
  3. Decrypt the backup drive by entering the password that was used to create it.
  4. Select the service(s) you want to restore and click “Restore Selected”.

Tip

If you’re restoring a backup taken from a different system architecture (x86, ARM, RISC-V) to the one you’re restoring to, you may need to reinstall services (not uninstall, since you will lose your data) from the marketplace after the restore completes to avoid running them more slowly in emulation.

Restoring an Entire Server

If your StartOS data drive is lost or corrupted and you need to restore your entire server, follow instructions here.

SMTP

Warning

This guide is not for using StartOS as an email server. It is for granting StartOS the simple ability to send emails through a 3rd party SMTP server.

Use Case

Adding SMTP credentials to StartOS makes it possible for certain services to send email notifications. Many services, such as NextCloud, Vaultwarden, Gitea, and others expect to send emails and require SMTP credentials to send them.

Getting SMTP Credentials

The guides below are for using Gmail, Amazon SES, or Proton Mail for SMTP, but you may also use another third party provider of your choice.

  1. Access your Google 2-step verification settings: https://myaccount.google.com/signinoptions/two-step-verification.

  2. Enable 2-Step verification if not already.

  3. Under “App Passwords” (bottom), add a new App Password.

  4. Choose a name for the new App Password. You may call it anything, such as “SMTP”, then click “Create”.

  5. A random 16-character password will be created and shown to you. This is your app password. Save it somewhere secure, such as your Vaultwarden password manager, then click “Done”.

  6. Now you can use this SMTP account for any service that has the capability to send an email. The table below shows all the details you may need:

    ParameterValue
    Hostsmtp.gmail.com
    Port587
    EncryptionTLS
    Usernameyour-username@gmail.com
    Passwordyour App Password (from above)

Configuring StartOS

  1. Navigate to System > SMTP

  2. Enter your SMTP credentials and hit “Save”.

  3. On the same page, send yourself a test email. Remember to check your spam folder. If the email goes to spam, mark it as not spam.

  4. For each service you want to use the credentials to send emails, go to the dashboard of that service, click “Actions”, and locate the relevant action.

SSH

Like other Linux distributions, StartOS allows you to go “under-the-hood” via Secure Shell Protocol (SSH).

Warning

Accessing your server via SSH is considered advanced. Please use caution, you can cause permanent damage to your server, potentially resulting in loss of data.

Using your StartOS Master Password

  1. Open a terminal on your client device and enter:

    ssh start9@SERVER-HOSTNAME

    Replace SERVER-HOSTNAME with your server’s your-server-name.local address.

  2. The first time you connect, you will see something like this:

    The authenticity of host 'your-server-name.local (192.168.1.175)' can't be established.
ED25519 key fingerprint is SHA256:BgYhzyIDbshm3annI1cfySd8C4/lh6Gfk2Oi3FdIVAa.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

    Type yes and hit Enter to start trusting the server’s SSH public key.

  3. Enter your StartOS master password.

Using SSH Keys

  1. In the StartOS UI, go to System > SSH

  2. Click Add Key, paste in your key and click Save

  3. Open a terminal on your client device and enter:

    ssh start9@SERVER-HOSTNAME

    Replace SERVER-HOSTNAME with your server’s your-server-name.local address.

  4. Enter your key’s passphrase (if any)

Connecting via PuTTY on Windows

For Windows, following the command above will work. But if you prefer a GUI tool, BrewsBitcoin has created a guide for connecting via SSH using PuTTY on Windows

WiFi

Warning

A wired Ethernet connection provides significantly better reliability, throughput, and latency. WiFi is prone to intermittent drops that can interrupt backups, corrupt data transfers, and degrade service performance. Only use WiFi if Ethernet is truly not an option.

Requirements

Your server must have a compatible wireless interface. If no wireless hardware is detected, the WiFi page will display “No wireless interface detected” and no controls will be available.

Note

Servers sold by Start9 do not come with wireless networking cards, but a wireless card can be added to any of the servers we sell.

Enabling WiFi

WiFi is managed from System > WiFi. Use the toggle at the top of the page to enable or disable the wireless radio. When disabled, no networks will be scanned or connected.

Connecting to a network

Once WiFi is enabled, two lists are displayed:

  • Known Networks - Networks you have previously saved. Tap one to reconnect. Use the trash icon to forget a saved network.
  • Other Networks - Available networks detected nearby. Tap one to connect. If the network is secured, you will be prompted for the password.

Signal strength is indicated by the WiFi icon color: green (strong), yellow (moderate), or red (weak). A lock icon means the network requires a password.

Adding a hidden network

To connect to a network that does not broadcast its SSID, tap the Add button. Enter the network SSID and password, then choose:

  • Save for later - Saves the credentials without connecting immediately.
  • Save and connect - Saves the credentials and connects right away.

Troubleshooting

If a connection attempt fails, you will see a “Failed to connect” warning. Double-check the password and try again. The system retries several times before reporting failure, so the process may take a moment.

Updating StartOS

Note

There are no automatic updates in StartOS. Updating the operating system and service always requires explicit action. That said, we highly recommended keeping StartOS up to date for the latest security and performance patches, as well as to take advantage of new features.

Update through the UI

  1. When a new version of StartOS is available, a rocket badge will appear on the “System” tab.

  2. Go to System -> General -> Software Update.

  3. Read the release notes and click “Begin Update”.

    Warning

    Ensure you have a stable Internet connection before beginning an OS update, and do not unplug your server while StartOS is downloading.

  4. While the new version of StartOS is downloading, you may continue to use your device as usual.

  5. Once the download is complete, you will be prompted to restart your server to complete the update.

    Warning

    Updates can take up to an hour to complete. During this time, there is no indication of progress and your StartOS UI will be unreachable. DO NOT UNPLUG YOUR SERVER DURING THIS TIME!

Update by Re-flashing

If you are updating to an unreleased version of StartOS, or something went wrong with a UI update (very rare), it may be necessary to update StartOS by re-flashing. Follow the guide for Installing StartOS.

Resetting Your Password

This guide should only be used if you have lost or forgotten your StartOS master password. If you are just wanting to change your password, that can be done through the main UI System > Change Password.

  1. Download and flash the latest version of StartOS, using the appropriate installation guide for your hardware.

  2. Visit http://start.local

  3. When selecting your data drive, be sure to select “Keep my data”.

  4. Create a new password and complete setup. All your previous addresses and data will be preserved.

CLI Reference

StartOS can be fully managed from the command line using start-cli. Connect via SSH and run:

start-cli --help

Authentication

Login, logout, and manage sessions.

start-cli auth login
start-cli auth logout
start-cli auth reset-password
start-cli auth session list
start-cli auth session kill

Server

Restart, shutdown, update, and configure the server.

start-cli server restart
start-cli server shutdown
start-cli server update
start-cli server logs
start-cli server kernel-logs
start-cli server metrics
start-cli server time
start-cli server update-firmware
start-cli server set-smtp
start-cli server test-smtp
start-cli server clear-smtp
start-cli server set-language
start-cli server set-keyboard
start-cli server set-ifconfig-url
start-cli server experimental governor
start-cli server experimental zram

Packages

Install, manage, and monitor services.

start-cli package list
start-cli package install
start-cli package start <PACKAGE>
start-cli package stop <PACKAGE>
start-cli package restart <PACKAGE>
start-cli package uninstall <PACKAGE>
start-cli package logs <PACKAGE>
start-cli package action run <PACKAGE> <ACTION>
start-cli package rebuild <PACKAGE>
start-cli package set-outbound-gateway <PACKAGE>

Backups

Create backups and manage backup targets (network shares).

start-cli backup create
start-cli backup target list
start-cli backup target cifs
start-cli backup target mount <TARGET>
start-cli backup target umount <TARGET>
start-cli package backup restore

Networking

Manage gateways, DNS, ACME certificates, and tunnels.

# Gateways
start-cli net gateway list
start-cli net gateway set-name <GATEWAY> <NAME>
start-cli net gateway set-default-outbound <GATEWAY>
start-cli net gateway check-dns <GATEWAY>
start-cli net gateway check-port <GATEWAY>
start-cli net gateway forget <GATEWAY>

# DNS
start-cli net dns set-static
start-cli net dns query <DOMAIN>

# ACME (Let's Encrypt)
start-cli net acme init
start-cli net acme remove

# Tunnels
start-cli net tunnel add
start-cli net tunnel remove

SSH

Manage authorized SSH keys.

start-cli ssh add
start-cli ssh list
start-cli ssh remove

WiFi

Connect to and manage wireless networks.

start-cli wifi add
start-cli wifi connect
start-cli wifi remove
start-cli wifi get
start-cli wifi available
start-cli wifi country
start-cli wifi set-enabled

Notifications

View and manage system notifications.

start-cli notification list
start-cli notification mark-seen
start-cli notification remove

Kiosk

Enable or disable kiosk mode for the local display.

start-cli kiosk enable
start-cli kiosk disable

Disk

List disks and repair filesystem issues.

start-cli disk list
start-cli disk repair

Diagnostics

Troubleshoot issues with logs and container rebuilds.

start-cli diagnostic logs
start-cli diagnostic kernel-logs
start-cli diagnostic error
start-cli diagnostic restart
start-cli diagnostic rebuild

Architecture

StartOS is a Linux distribution purpose-built for running a personal server. Unlike general-purpose operating systems designed for desktops and laptops, StartOS provides a graphical interface for discovering, installing, configuring, and managing self-hosted services — no command line required.

This page describes how StartOS is designed and how its components fit together. For implementation details, see the start-os repository.

Components

StartOS is composed of four major components:

  • Core — A Rust backend that manages system state, service lifecycles, networking, storage, and the API. It compiles into a single binary (startbox) that is symlinked to serve as the system daemon (startd), the CLI (start-cli), and other utilities.
  • Web UI — An Angular frontend that provides the admin interface, setup wizard, and marketplace. It communicates with the backend over JSON-RPC and WebSocket.
  • Container Runtime — A Node.js process that runs inside each service’s LXC container, loading the package’s JavaScript and managing subcontainers, health checks, and effects callbacks.
  • SDK — A TypeScript library that package developers use to define service metadata, daemons, actions, interfaces, and other behaviors. The SDK compiles into the JavaScript bundle shipped inside each package.

Service Model

Every service on StartOS runs inside its own isolated LXC container. This provides process isolation, filesystem isolation, and network namespacing without the overhead of full virtual machines.

S9PK Package Format

Services are distributed as .s9pk files — a custom archive format built on a merkle tree. An S9PK contains:

  • manifest.json — Package metadata: ID, title, version, license, descriptions, alerts, dependency declarations, and image definitions.
  • icon — The package icon displayed in the marketplace and UI.
  • LICENSE.md — The applicable license.
  • javascript.squashfs — The compiled SDK code that defines the service’s behavior on StartOS (daemons, actions, health checks, interfaces, etc.).
  • images/ — Container root filesystem images (squashfs), organized by CPU architecture (x86_64, aarch64, riscv64).
  • assets.squashfs — Optional static assets mounted read-only into the container.

The merkle archive format enables partial downloads, integrity verification of subsets, efficient updates (only changed portions need re-downloading), and size limit enforcement before completing a download.

S9PK files are cryptographically signed (Ed25519) so that users and registries can verify package authenticity.

Service Lifecycle

A service moves through several lifecycle stages, each of which can trigger package-defined code:

  1. Install — The S9PK is unpacked, container images are extracted, volumes are created, and the package’s setupOnInit function runs with kind: 'install'. This is where packages generate initial secrets, create default configuration, and prompt the user for required setup via tasks.
  2. Actions — Actions are operations defined by the package that appear as buttons in the UI. They can display information (e.g., show admin credentials), accept user input (e.g., configure SMTP), or modify the service’s state. Actions can run whether the service is started, stopped, or both.
  3. Tasks — Tasks are notifications that prompt the user to run a specific action. Packages create tasks during initialization or at runtime to guide the user through required setup steps. Tasks have a severity level: critical tasks block the service from starting until completed, while lower-severity tasks are informational.
  4. Start — The package’s setupMain function runs, which defines daemons (long-running processes), oneshots (startup tasks like migrations), and health checks. Daemons run inside subcontainers created from the package’s images.
  5. Update — When a new version is installed, the package’s version migration code runs, transforming stored data as needed. The setupOnInit function runs again with kind: 'install'.
  6. Backup — StartOS creates an encrypted backup of the service’s designated volumes. Services can exclude data that is recoverable by other means (e.g., Bitcoin excludes the blockchain).
  7. Restore — A backup is decrypted and restored. The setupOnInit function runs with kind: 'restore', allowing the package to re-register triggers or re-prompt the user.
  8. Uninstall — The container and its volumes are removed.

Container Architecture

When a service starts, the container runtime loads the package’s JavaScript and uses it to create subcontainers from the package’s images. The relationship looks like this:

LXC Container (managed by StartOS)
└── Container Runtime (Node.js)
    └── Package JavaScript (from s9pk)
        ├── SubContainer A (e.g., the main application)
        ├── SubContainer B (e.g., a database)
        └── Health Checks

The container runtime communicates with the StartOS host via JSON-RPC over a Unix socket. This is how packages invoke “effects” — host-level operations like reading configuration, resolving hostnames, accessing the network, or creating user-facing tasks.

Volumes

Each service has one or more named volumes for persistent data. Volumes survive container restarts, updates, and restores. They are id-mapped to the container’s user namespace for security. Packages declare which volumes to include in backups.

Networking

StartOS provides multiple ways to access services, all managed through the UI.

LAN Access

Services are accessible over the local network using mDNS hostnames (your-server-name.local). StartOS runs its own DNS resolver and issues TLS certificates from a local Certificate Authority (CA). Users trust this CA on their client devices to get HTTPS connections over LAN without browser warnings.

Tor

Tor is available as a marketplace service. Once installed, users can enable onion addresses for any service through the Tor service’s actions. Tor provides access from anywhere without port forwarding or exposing your IP address.

Clearnet

Services can be exposed to the public internet using a domain name. This requires a clearnet gateway — a WireGuard-based tunnel to a server with a public IP and domain. StartTunnel is one such gateway, but any WireGuard configuration can be used for outbound traffic.

Gateways

A gateway is a WireGuard tunnel that routes traffic between a StartOS server and the outside world. Gateways can be:

  • Inbound + Outbound — Routes both incoming and outgoing traffic (e.g., StartTunnel). This enables clearnet access to services.
  • Outbound only — Routes only outgoing traffic through the tunnel (e.g., a commercial VPN). This masks your server’s IP for outbound connections.

StartOS auto-detects the gateway type from the WireGuard configuration file. A system-wide default gateway can be set, and individual services can override it.

Holesail

Holesail is available as a marketplace service for peer-to-peer tunneling using the Hyperswarm DHT. It provides an alternative to Tor for remote access without port forwarding.

State Management

StartOS uses Patch-DB, a custom diff-based database, to manage system state. The key property of Patch-DB is reactive synchronization: when the backend mutates state, the frontend receives only the diff (patch) over a WebSocket connection. This means the UI always reflects the current system state without polling.

The database has two layers:

  • Public model — Synced to the frontend. Contains everything the UI needs: service status, installed packages, system settings, network configuration, notifications.
  • Private model — Backend-only. Contains internal state like cryptographic keys, session tokens, and operational data that should never leave the server.

Security

Container Isolation

Each service runs in its own LXC container with:

  • Separate filesystem (id-mapped volumes)
  • Network namespace isolation
  • Resource limits
  • No direct access to host resources except through the effects API

Encrypted Backups

All backups are encrypted using the user’s master password. Backups can be stored on physical drives or network shares (SMB/CIFS). Each service’s backup retains the password that was active when the backup was created.

Authentication

The web UI is protected by password authentication with session cookies. The API uses JSON-RPC with session-based auth. SSH access is available for advanced users but is not required for normal operation.

Package Signing

S9PK files are signed with Ed25519 keys. The registry and StartOS verify signatures before installing packages, ensuring that packages have not been tampered with.

Tech Stack

ComponentTechnology
BackendRust (async Tokio, Axum)
FrontendAngular, TypeScript, Taiga UI
Container RuntimeNode.js, TypeScript
ContainersLXC
DatabasePatch-DB (custom, diff-based)
APIJSON-RPC
Package FormatS9PK (merkle archive, Ed25519 signed)
NetworkingWireGuard, Tor (Arti), mDNS, ACME
Supported Archsx86_64, aarch64, riscv64

Source Code

StartOS is fully open source. The main repository is Start9Labs/start-os on GitHub. See the repository’s CONTRIBUTING.md for build instructions and development setup.

Flashing Firmware

These guides are for updating the BIOS/firmware on Start9-branded server hardware. They are not needed for DIY builds or for installing/updating StartOS itself.

Flashing Firmware - Server Pure

This page is for the Server Pure only. It will not work on other devices.

Generally, you do not need to manually flash your device using this guide, as the firmware is now automatically updated on supported devices. Please only use this method if directed by a Start9 Support Technician. If you were told to “flash your device”, you are looking for the StartOS flashing guides instead.

You Will Need

  • A monitor and keyboard.
  • A USB stick, formatted FAT32.

Instructions

  1. Power down your server if not already.

  2. Connect a monitor and keyboard to your server using two of the USB3 (blue) ports.

  3. Download the right firmware:

    Note

    The Jailed WiFi variation deactivates WiFi at the firmware level so it can never be turned on

  4. Copy or move the zip file to the USB stick.

  5. Eject the USB stick and insert it into your server using a USB3 (blue) slot.

  6. Turn on the server while pressing the ESC key on the keyboard repeatedly until you see the PureBoot Basic Boot Menu screen. Select “Options –>”.

    step 1

  7. Select “Flash/Update the BIOS”.

    step 2

  8. Select “Flash the firmware with a new ROM, erase settings”.

    step 3

  9. The system will ask if you want to proceed flashing the BIOS with a new ROM, select “Yes”.

    step 4

  10. Choose the file that we downloaded and copied to the USB stick.

    step 5

  11. Confirm you want to proceed with the flash by selecting “Yes”.

    step 6

  12. The BIOS will be re-flashed with the new firmware. This may take a few minutes. When complete, remove the firmware USB, then select “OK” to complete the process.

    step 7

Flashing Firmware - Server One (2023)

Start9’s 2023 Server One was the Intel NUC11ATKC4, whose BIOS was refered to as “ATJSLCPX” by Intel, and whose latest release was AT0043.cap before they officially discontinued support for the product line.

You Will Need

  • A monitor and keyboard.
  • A USB stick, formatted FAT32.

Instructions

  1. Download Intel_ATJSLCPX-AT0043.cap to the USB stick

    Tip

    If you wish to confirm the integrity of your download before you flash it, here is the sha256sum:

    e72c356cdefa90486c031b7bd3d616cfd4e34e76dffb9f3ba72928355db3185b Intel_ATJSLCPX-AT0043.cap

  2. Insert the power cable, video cable, keyboard, mouse, and USB stick with the ATJSLCPX BIOS into the Server One.

  3. Power the unit on and continually press F7 on your keyboard to launch the BIOS update screen.

  4. Press enter 3 times to update the BIOS by selecting and confirming your intention to flash Intel_ATJSLCPX-AT0043.cap from the USB stick.

  5. Power the unit off when it reboots, and remove the BIOS USB stick.

  6. Power the unit on and continually press F2 to enter the bios settings.

  7. Arrow up, then right to the Power menu (near the top right).

  8. Arrow to Secondary Power Settings at the bottom.

  9. Arrow down to After Power Failure and set the value to “Power On”.

  10. Arrow to Wake on LAN from S4/S5 and set the value to “Stay Off”.

  11. Arrow up, then over to the Boot menu (top right).

  12. Arrow down to Boot Priority.

  13. Set all 4 UEFI PXE & HTTP Network boot options to “Disabled”.

  14. Arrow down to Boot USB Devices First and enable (check) it.

  15. Hit F10 to save changes and exit, followed by “Yes”.

FAQ

Common issues encountered during setup and daily use of StartOS, including network connectivity problems, diagnostic mode, clock sync failures, and service-specific troubleshooting.

I do not have access to Ethernet

Ethernet is strongly recommended. Servers are always-on, critical devices and should use a wired connection. However, if you do not have access to a router, such as in a work or school environment, there are two options:

  • Server has a WiFi card (DIY builds only — Start9 servers do not ship with one): Connect a monitor and keyboard to your server (kiosk mode). If no Ethernet interface is detected, you will be prompted to connect to a WiFi network. See WiFi for more details.

  • Server does not have a WiFi card: Use a WiFi extender to bridge the local WiFi network to Ethernet, then connect your server to the extender. The extender below has been tested with StartOS, but others should also work.

StartOS boots into “Diagnostic Mode”

If you encounter Diagnostic Mode, your best bet is stop clicking and contact support.

During initial setup, I am unable to connect to “start.local”.

  1. Confirm that the server is plugged into power and Ethernet

  2. Confirm that your phone/computer is connected to the same network as the server.

  3. Confirm your phone/computer is not connected to a “Guest” network

  4. Confirm you are not using the Tor Browser.

  5. Confirm your phone/computer is not using a VPN, or that if you are, that it allows LAN connections, such as the examples below:

    • Mullvad - Go to Settings -> VPN Settings -> Local Network Sharing
    • ProtonVPN - Go to Preferences -> Connection -> Allow LAN Connections

  6. Very rarely, your firewall settings may block mDNS. In this case:

    • From your browser, navigate to your router configuration settings. This is usually an IP address such as 192.168.1.1. A simple web search will usually reveal how to access the router configuration settings for a particular brand.
    • Once in the router config settings, find the section that lists the devices on your network. You should see a device labeled start. Take note of the associated IP address and enter it into your browser’s URL field to enter the setup.

  7. Log into your router (the directions for which can be found with a simple web search for your router model and ‘how to log in’). Once you are in your router, find the device labeled “start”, and visit its associated IP address, which will look something like: 192.168.1.9

I am unable to connect to my server’s “custom-address.local” URL

  1. First, try :ref:these step <setup-troubleshoot>. In none resolve the issue, continue below.

  2. Hard refresh the browser:

    • Linux/Windows: ctrl+shift+R
    • macOS Firefox: cmd+shift+R
    • macOS Safari: cmd+option+E, then cmd+R

  3. Make sure you have successfully followed the :ref:connecting-lan instructions for your device.

  4. If you are using Windows, the problem is almost certainly with Bonjour. Follow the :ref:directions to reinstall <connecting-lan-windows>, even if you have already done so.

  5. If using Firefox from Mac, Windows or Android, ensure you have set security.enterprise_roots.enable to true in about:config per the :ref:instructions<ca-ff>

  6. Try connecting using your server’s IP address. If this works, it means your issue is specific to .local. Try clearing your browser cache and/or restarting your phone/laptop/router. If all fails, try restarting your server.

  7. Try connecting using a different browser on the same device. If this works, it means you need to clear cache on your current browser.

  8. Try connecting using a different device. If this works, it means you need to clear cache on your current browser and/or restart your current device.

  9. Try visiting start.local. Your server may be in diagnostic mode.

  10. Try restarting your router.

  11. Try restarting your server. Be patient and give it plenty of time to come back online.

I am unable to connect to my server’s “xxxxxxxxxxxxxxxxxx.onion” URL

  1. Tor can be slow and unreliable. Often, the solution to poor connectivity is just to wait an hour and try again.
  2. Confirm that the Tor service is installed and running on your server.
  3. Confirm that you have created an onion service for the interface you are trying to reach. See Tor.
  4. Try connecting using the official Tor Browser. If this works, it means the issue is with your current browser or the Tor daemon running on your phone/laptop. Try clearing cache and restarting things.
  5. Try connecting to your server using its .local URL or IP address. If this works, the issue is specific to Tor. Try restarting the Tor service on your server.

Request Error

This means your client device failed to connect to the server. This can happen for a variety of reasons. The best course of action is:

  1. Check your local Internet connection.
  2. Hard refresh the browser.
  3. Clear the browser cache/history.
  4. Try using a different address for your server. For example, if you are using your .local address, try your IP address instead, or vice versa.
  5. Try from another client device. If the second client works, then you know the issue is with your first client. If the seconds client does not work, then you know the issue is either with your clients’ network or with your server.
  6. If after completing the steps above, you still cannot connect using any address from any client, then you will likely need to manually power cycle the server.
  7. If power cycling the server does not resolve the issue, please contact support.

Clock Sync Failure

This means your server was unable to sync its clock with the Internet using the Network Time Protocol (NTP). This is usually due to a firewall issue with your network/router. Make sure you are not blocking NTP. If the issue persists, please contact support.

Issue with a particular service

If a service is misbehaving or crashing, check the logs for that service. Look for any errors that might explain the problem. Often, the solution is to restart the service by clicking “Restart”. If the issue persist, contact support.

Common Speaker Noises

The Server Pure (2023 and older) and and Server One (2022 and older) have an internal speaker. Below are the meanings of various noises.

  • bep: Server is starting up

  • chime: Server is ready

  • double/triple bep: Server is updating

  • flatline: Server initialization failed / no network connection

  • Beethoven’s 5th: Something has gone wrong. Visit http://start.local to view Diagnostic Mode and contact support.