Introduction

Welcome to the Start9 Docs! Here you will find everything you need to set up and use your Start9 server. For additional help, contact support.

Initial Setup - Start Fresh

Connect your server to power and Ethernet.
From a computer connected to the same Local Area Network (LAN) as your server, open a browser and visit http://start.local.
Select "Start Fresh" and follow the on-screen instructions. If you are setting up StartOS and need to recover existing data, see Initial Setup - Recover.

Initial Setup - Recover

There are three options for setting up StartOS while also keeping existing data.

Setup

Use Existing Drive

Select this option if:

You have re-flashed StartOS and want to resumt normal operation on the same drive and server.
You are physically transplanting your data drive to a new server.

Transfer

Select this option if you are transferring your data from one drive to another.

Restore from Backup (Disaster Recovery)

Select this option only if your StartOS data drive has been lost or corrupted. This is for disaster recovery only.

Trusting Your Root CA

To establish a secure (HTTPS) connection with your server, it is necessary to download and trust your server's Root Certificate Authority (Root CA).

Download your Root CA

There are multiple ways to download your Root CA.

From the HTTP login screen.

Visit your server's http://<adjective-noun>.local URL.
From your StartOS-info.html file.

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

You can securely access your server using its http://....oinion URL from any Tor-enabled browser. From there, you can download your Root CA by going to System -> Root CA.
Sending to yourself.

Once you have downloaded your Root CA on one device, you can simply send the file to yourself using email, messaging app, or other file sharing technique.

Trust your Root CA

Select your client device OS and follow instructions

Connecting Locally

To connect locally, you must be connected to the same LAN as your server. Local connections are the fastest possible, as they do not reach out to the Internet.

Using .local (preferred)

Ensure you have trusted your Root CA.
Visit your server's unique .local address from any browser.

Using IP Address


Your router may unexpectedly change your server's IP address. To prevent this, assign a static IP address to your server in your router settings. This is supported by all routers. Refer to your router's user manual for instructions.

Ensure you have trusted your Root CA.
Visit your server's unique IP address from any browser. You can find your server's IP address in StartOS under System > About, or in your router settings.

Connecting Remotely

Connecting over Router VPN

Prerequisite

Trusting Your Root CA

Most modern routers have VPN functionality built-in. Refer to your router's user manual for instructions to complete the following steps.

Assign a static IP address to your server.

Enable your router's VPN.


Rarely, your ISP may unexpectedly change your home IP address. If this happens, it will break your VPN connection until you re-complete the steps below. To prevent this, you can enable Dynamic DNS in your router, which is usually a paid service. To learn more about Dynamic DNS, click [here]().

Download your VPN config file from your router.
Install OpenVPN on your client device(s) and establish a VPN connection to your LAN using the config file from above.

Connecting over Tor


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

Using a Tor Browser

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

Recommended Browsers

Mac, Linux, Windows, Android/Graphene: Tor Browser
iOS: Onion Browser

Running Tor in the background on your Phone/Laptop

By running Tor on your phone or laptop, certain apps will be able to connect to your server over Tor, even if the apps themselves do not natively support Tor. Select the guide specific to your phone/laptop:

Installing Services

Installing 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 "Change" underneath the current Registry title.

change registry

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 System > Sideload a Service and upload the appropriate .s9pk file.

system sideload

Creating Backups

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

What You Need to Know

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).
Backups are encrypted using your master password.
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.
Backups can take minutes or hours to complete, depending on your hardware and quantity of data.
A service cannot be used while it is backing up. You may, however, continue to use your server and other services.
Upon completion, StartOS issues a backup report, indicating which services were backed up, as well as any errors.

Physical Drive

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

Backing up to USB thumb drive or SD card media is highly discouraged, as low-quality flash memory is easily corruptible.

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

Choose your target device below for instructions creating a network folder.

Restoring Backups

Restoring Individual Services

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

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

Restoring an Entire Server

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

Using SSH

Like other Linux distributions, you can go "under-the-hood" via Secure Shell Protocol (SSH) if you choose. Even though StartOS is designed to be used from the GUI, it is a good idea to set up SSH access. It can be useful for debugging purposes as well as advanced functionality.

For security reasons, StartOS _disables_ access is not available, so you will need to add an SSH key to your server via the method below.

Creating an SSH Key

Open a terminal on your client device and enter the following command.
```
ssh-keygen -t ed25519
```
You will be asked to enter a file in which to save the key. We recommend pressing Enter to use the default location
Optionally create a passphrase, or press enter for no passphrase.

The next 3 step are for Linux and Mac users only. Windows users skip to Registering Your SSH Key with StartOS
The terminal will inform you that your public key has been saved. Take note of the path.
```
Your public key has been saved in /home/user/.ssh/id_ed25519.pub
```
Start your system's ssh-agent:
```
eval "$(ssh-agent -s)"
```
Add your key to the ssh-agent:
```
ssh-add ~/.ssh/id_ed25519
```
Note: if you changed the file name/location in step 1, you will need to use that file/path in this step

Registering Your SSH Key with StartOS

Open a terminal on your client device and display your SSH public key (created above):
- Mac and Linux:
```
cat ~/.ssh/id_ed25519.pub
```
- Windows:
```
type .ssh\id_ed25519.pub
```

Copy the resulting line that looks similar to

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINH3tqX71XsPlzYhhoo9CqAP2Yx7gsGTh43bQXr1zqoq user@email.com

In StartOS, navigate to System > SSH.
Click "Add New Key".
Paste your SSH public key (copied above).
Click "Submit".

SSH over LAN

Open a terminal on your client device and enter:
```
ssh start9@SERVER-HOSTNAME
```
Replace SERVER-HOSTNAME with your server's adjective-noun.local address URL.

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

The authenticity of host 'adjective-noun.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.


If you get a scary looking warning that says something like

    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!

Fear not! This is most likely happening because you have recently re-flashed your server, which causes a change in the key for your device's hostname. The solution is to delete the existing entry from your `known_hosts` file, which is typically located at `~/.ssh/known_hosts`. This will be specified in the warning, along with a helpful line number (in case your file is lengthy).

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

SSH over Tor


Terminal SSH over Tor is only supported on Linux and MacOS. For Windows, it is only possible with PuTTY as seen <a href="https://tor.stackexchange.com/a/143" target="_blank">here</a>. Note: those instructions use port 9150, but we've configured Tor in Windows on the traditional port 9050.

Install torsocks

Mac:
```
brew install torsocks
```
Debian / Ubuntu
```
sudo apt install torsocks
```
Arch / Garuda / Manjaro
```
sudo pacman -S torsocks
```

Run the following command:
```
echo -e "\nHost *.onion\n\tProxyCommand nc -xlocalhost:9050 %h %p" >> ~/.ssh/config
```
This command adds a wildcard setting for .onion domains to your SSH config file. Any .onion domains you connect to using SSH will use the specified proxy command.

SSH into StartOS:


The changes you make here are on the overlay and won't persist after a restart of your server.

ssh start9@<custom-address>.local

Elevate yourself to root in chroot edit mode (which will make your changes persist across reboots):
```
sudo /usr/lib/startos/scripts/chroot-and-upgrade
```

Using Vim or Nano, add the following 2 lines to /etc/tor/torrc

HiddenServiceDir /var/lib/tor/ssh
HiddenServicePort 22 127.0.0.1:22


You can also add these lines by running the following command:

    echo -e "\nHiddenServiceDir /var/lib/tor/ssh\nHiddenServicePort 22 127.0.0.1:22" >> /etc/tor/torrc

Restart your Start9 server by exiting chroot edit mode:
```
exit
```

SSH in again to gather you newly-generated SSH ".onion" address:

sudo cat /var/lib/tor/ssh/hostname


This .onion address is only for SSH access and should not be confused with your server's main .onion address.

Exit SSH
```
exit
```
Now you can SSH into your server using your SSH ".onion" URL:
```
ssh start9@xxxxxxxxxxxxxxxxx.onion
```

Using WiFi

StartOS does not have WiFi capabilities.

Servers are intended to be online 24/7, and a direct, Ethernet connection is always faster and more reliable than WiFi.

However, WiFi can sometimes be necessary, such as in a school or office setting where Ethernet connections are not available. In these circumstances, we recommend using a WiFi extender.

You connect the WiFi extender to the available WiFi network, then you connect your StartOS server to the WiFi extender using Ethernet. It is that easy.

The WiFi extenders below have been tested to work with StartOS, but other extenders should also work.

Updating StartOS


StartOS does not have automatic updates and will _never_ update without your approval. 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

When a new version of StartOS is available, a rocket badge will appear on the "System" tab.
Go to System > Software Update.

Read the release notes and click "Begin Update".


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

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

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


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 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 Flashing StartOS.

Flashing Firmware

Flashing Firmware - Server Pure

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

It is generally unnecessary to flash your device in this manner. Please only use this method if directed by a Start9 team member.

The firmware source code can be viewed here.

Prerequisites

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

Instructions

Power down your server if not already.
Connect a monitor and keyboard to your server using two of the USB3 (blue) ports.
Download the latest firmware: standard release or jailed WiFi.
Copy or move the zip file to the USB stick.
Eject the USB stick and insert it into your server using a USB3 (blue) slot.
Turn on the server while pressing the ESC key on the keyboard repeatedly until you see the PureBoot Basic Boot Menu screen. Select "Options -->".
Select "Flash/Update the BIOS".
Select "Flash the firmware with a new ROM, erase settings".
The system will ask if you want to proceed flashing the BIOS with a new ROM, select "Yes".
Choose the file that we downloaded and copied to the USB stick.
Confirm you want to proceed with the flash by selecting "Yes".
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.

Flashing Firmware - Server Pure

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

It is generally unnecessary to flash your device in this manner. Please only use this method if directed by a Start9 team member.

The firmware source code can be viewed here.

Prerequisites

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

Instructions

Power down your server if not already.
Connect a monitor and keyboard to your server using two of the USB3 (blue) ports.
Download the latest firmware.
Copy or move the zip file to the USB stick.
Eject the USB stick and insert it into your server using a USB3 (blue) slot.
Turn on the server while pressing the ESC key on the keyboard repeatedly until you see the PureBoot Basic Boot Menu screen. Select "Options -->".
Select "Flash/Update the BIOS".
Select "Flash the firmware with a new ROM, erase settings".
The system will ask if you want to proceed flashing the BIOS with a new ROM, select "Yes".
Choose the file that we downloaded and copied to the USB stick.
Confirm you want to proceed with the flash by selecting "Yes".
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.

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.

Prerequisites

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

Instructions

Download Intel_ATJSLCPX-AT0043.cap to the USB stick


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

`e72c356cdefa90486c031b7bd3d616cfd4e34e76dffb9f3ba72928355db3185b  Intel_ATJSLCPX-AT0043.cap`

Insert the power cable, video cable, keyboard, mouse, and USB stick with the ATJSLCPX BIOS into the Server One.
Power the unit on and continually press F7 on your keyboard to launch the BIOS update screen.
Press enter 3 times to update the BIOS by selecting and confirming your intention to flash Intel_ATJSLCPX-AT0043.cap from the USB stick.
Power the unit off when it reboots, and remove the BIOS USB stick.
Power the unit on and continually press F2 to enter the bios settings.
Arrow up, then right to the Power menu (near the top right).
Arrow to Secondary Power Settings at the bottom.
Arrow down to After Power Failure and set the value to "Power On".
Arrow to Wake on LAN from S4/S5 and set the value to "Stay Off".
Arrow up, then over to the Boot menu (top right).
Arrow down to Boot Priority.
Set all 4 UEFI PXE & HTTP Network boot options to "Disabled".
Arrow down to Boot USB Devices First and enable (check) it.
Hit F10 to save changes and exit, followed by "Yes".

Flashing StartOS

Flashing StartOS - X86_64 / ARM

This guide is for flashing StartOS to a USB drive, then installing it onto an x86_64 device, which includes most desktops, laptops, and mini PCs. For an up-to-date list of known-good hardware, please check out this forum post.


To install StartOS on an ARM device, simply replace all x86_64 references in this guide.

Download

Visit the Github release page to find the latest version of StartOS.
At the bottom of the page, under "Assets", download the x86_64.iso file or the x86_64-nonfree.iso file. We recommend installing the x86_64.iso image first. Then, if it is not compatible with your hardware, install the x86_64-nonfree.iso image.
- x86_64.iso: This image is 100% open source, containing no proprietary firmware or drivers. It will only work on certain hardware devices, such as the Start9 Server Pure.
- x86_64-nonfree.iso: this image contains non-free (closed source) firmware and drivers, primarily for display and wireless capabilities.
Verify the SHA256 checksum against the one listed on GitHub (optional but recommended).
- Mac. Open a terminal window and run the following, replacing startos-0..._x86_64 with the path/name of the file:
```
openssl dgst -sha256 startos-0..._x86_64
```
- Linux Open a terminal window and run the following, replacing startos-0..._x86_64 with the path/name of the file:
```
sha256sum startos-0..._x86_64
```
- Windows Open a PowerShell and run the following, replacing Downloads with the directory where you downloaded the file, and startos-0..._x86_64 with the name of the file:
```
cd Downloads
Get-FileHash startos-0..._x86_64
```

Flash

Download and install balenaEtcher onto your Linux, Mac, or Windows computer.
Insert your USB drive into your computer.
Open balenaEtcher.
Click "Select Image" and select the .iso image you just downloaded.

Click "Select Target" and select your microSD card.


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

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

Install

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).

Power on your server, booting from USB.


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 <a href="https://community.start9.com" target="_blank">Community Hub</a> for guides or to get help.

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".
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.

Flashing StartOS - Raspberry Pi

This guide is for flashing StartOS to a microSD card for use on a Raspberry Pi.

Download

Visit the Github release page to find the latest version of StartOS.
At the bottom of the page, under "Assets", download the startos-..._raspberrypi.img.gz file.
Verify the SHA256 checksum against the one listed on GitHub (optional but recommended).
- Mac. Open a terminal window and run the following, replacing startos-0..._raspberrypi.img.gz with the path/name of the file:
```
openssl dgst -sha256 startos-0..._raspberrypi.img.gz
```
- Linux Open a terminal window and run the following, replacing startos-0..._raspberrypi.img.gz with the path/name of the file:
```
sha256sum startos-0..._raspberrypi.img.gz
```
- Windows Open a PowerShell and run the following, replacing Downloads with the directory where you downloaded the file, and startos-0..._raspberrypi.img.gz with the name of the file:
```
cd Downloads
Get-FileHash startos-0..._raspberrypi.img.gz
```

Flash

Download and install balenaEtcher onto your Linux, Mac, or Windows computer.
Insert your microSD card into your computer, either directly or using an adapter.
Open balenaEtcher.
Click "Select Image" and select the .img.gz image you just downloaded.

Click "Select Target" and select your microSD card.


BE ABSOLUTELY CERTAIN you have selected the correct target microSD card. Whatever drive you select will be **COMPLETELY ERASED**!

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

Install

For the Raspberry Pi, flashing and installing are essentially the same thing. Simply remove the newly-flashed microSD card and insert it into your Raspberry Pi.

Linux Guides

Trusting Your Root CA (Linux)

Debian Systems

This should work for most Debian-based systems, such as Debian, Ubuntu, Mint, PopOS etc.

Ensure you have downloaded your Root CA.

Open a terminal and run::

sudo apt update
sudo apt install -y ca-certificates p11-kit

Move into the directory where you downloaded your Root CA (usually ~/Downloads), for example:
```
cd ~/Downloads
```

Add your Root CA to your OS trust store. Be certain to replace adjective-noun with your server's unique hostname in the 3rd and 4th commands:

sudo mkdir -p /usr/share/ca-certificates/start9
sudo cp "adjective-noun.crt" /usr/share/ca-certificates/start9/
sudo bash -c "echo 'start9/adjective-noun.crt' >> /etc/ca-certificates.conf"
sudo update-ca-certificates

If successful, you will receive 1 added.

If using Firefox or Tor Browser, complete this final step.
If using a Chromium browser, such as Chrome or Brave, complete this final step.

Arch / Garuda

Ensure you have downloaded your Root CA.
Move into the directory where you downloaded your Root CA (usually ~/Downloads), for example:
```
cd ~/Downloads
```
Add your Root CA to your OS trust store. Be certain to replace adjective-noun with your server's unique hostname in the 3rd and 4th commands:
```
sudo pacman -S ca-certificates
sudo cp "adjective-noun.crt" /etc/ca-certificates/trust-source/anchors/
sudo update-ca-trust
```
Despite no output from the last command, you can test your app right away.

CentOS / Fedora

Ensure you have downloaded your Root CA.
In /etc/systemd/resolved.conf, ensure you have MulticastDNS=Yes.

Restart systemd-resolved

sudo systemctl restart systemd-resolved

Move into the directory where you downloaded your Root CA (usually ~/Downloads), for example:
```
cd ~/Downloads
```
Add your Root CA to your OS trust store. Be certain to replace adjective-noun with your server's unique hostname in the 3rd and 4th commands:
```
sudo yum install ca-certificates
sudo cp "adjective-noun.crt" /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
```

Additional Steps for Chromium Browsers

On Linux, Chromium browsers require extra configuration to trust your Root CA. These instructions should work for Chrome, Brave, Vivaldi and other Chrome-based browsers.

In the URL bar, enter chrome://settings/certificates.
Click Authorities > Import.
Select your adjective-noun.crt file.
Check "Trust this certificate for identifying websites".
Click OK.

Using a VPN (Linux)

Running Tor (Linux)


After completing the guide below for your system, you can confirm Tor is running with:

    systemctl status tor

In the rare event that Tor is having connectivity issues, reset the connection:

    sudo systemctl restart tor

Debian/Ubuntu

This should work for most Debian-like systems, such as Debian, Ubuntu, Mint, PopOS etc.

The following instructions will install the LTS (Long Term Support) version of Tor from your distro's default repository. If you would always like the latest stable release, the Tor Project maintains their own Debian/Ubuntu repository. The instructions for connecting to this official Tor Project repository can be found here.

Open a terminal and install/start Tor:

sudo apt update && sudo apt install tor

Arch / Garuda / Manjaro

Open a terminal and install/start Tor:
```
sudo pacman -S tor
```

CentOS / Fedora / RHEL

Configure the Tor Package repository. Add the following to /etc/yum.repos.d/tor.repo:

[Tor]
name=Tor for Enterprise Linux $releasever - $basearch
baseurl=https://rpm.torproject.org/centos/$releasever/$basearch
enabled=1
gpgcheck=1
gpgkey=https://rpm.torproject.org/centos/public_gpg.key
cost=100

For Fedora, the "name" line should be Tor for Fedora $releasever - $basearch

Open a terminal and install Tor:
```
sudo dnf install tor
```
Enable tor service:
```
sudo systemctl enable --now tor
```

Creating Backups (Linux)

Create a Shared Folder

Ubuntu

Install Samba if not already:

sudo apt install samba && sudo systemctl enable smbd

Add your user to samba, replacing $USER with your Linux username.
```
sudo smbpasswd -a $USER
```
You will be prompted for your linux password. Then, you must create a new SMB password for the user with permission to write to your new backup share. Keep the password somewhere safe, such as Vaultwarden.

Identify or create a folder to store your server backups.


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

Right click the folder and click "Properties".
Click "Local Network Share".
Select "Share this folder" and give the folder a Share name. Remember the name, you will need it later. Then click "Create Share".
If your installation of Ubuntu is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
```
sudo ufw allow Samba
```

Mint

Install Samba if not already:

sudo apt install samba && sudo systemctl enable smbd

Add your user to samba, replacing $USER with your Linux username.
```
sudo usermod -a -G sambashare $USER
sudo smbpasswd -a $USER
```
You will be prompted for your linux password. Then, you must create a new SMB password for the user with permission to write to your new backup share. Keep the password somewhere safe, such as Vaultwarden.

Identify or create a folder to store your server backups.


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

Right click the folder and click "Sharing Options".
Select "Share this folder" and give the folder a Share name (maximum 12 characters). Remember the name, you will need it later. Click "Create Share".
If your installation of Mint is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
```
sudo ufw allow Samba
```

Other Linux

Install Samba if it is not already installed.

Arch:
```
 sudo pacman -S samba
```
Debian and Debian-based:
```
  sudo apt install samba
```
CentOS/Redhat
```
  sudo yum install samba
```
Fedora
```
  sudo dnf install samba
```

Identify or create a folder to store your server backups. Make a note of the directory path. For example:

mkdir -p /home/$USER/start9-backup

replacing $USER with your Linux username and "start9-backup" with whatever you want the folder to be named.


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


If you are on Fedora 38+, you need to do an extra step to allow the Samba share in SELinux:

    sudo semanage fcontext --add --type "samba_share_t" "/home/$USER/start9-backup(/.*)?"
    sudo restorecon -R /home/$USER/start9-backup

Configure Samba by adding the following to the end of your /etc/samba/smb.conf file:
```
[backup-share]
    path = "/home/$USER/start9-backup"
    create mask = 0600
    directory mask = 0700
    read only = no
    guest ok = no
```
Where:
- [backup-share] can be replaced with whatever you want (must remain inside brackets). This is your Share Name. Remember the name, you will need it later.
- path is the directory path to the share folder from above.
Open a terminal and enter the following command, replacing $USER with your Linux username:
```
sudo smbpasswd -a $USER
```
This creates a password for the Local Network Share. Keep it somewhere safe, such as Vaultwarden.
If your installation of Linux (Pop-OS users take special note!) is running a firewall by default or due to your own custom configuration, enter this command to allow connections to Samba. If it generates an error, you can safely ignore it:
```
sudo ufw allow Samba
```

Create a Backup

In StartOS, go to System > Create Backup.
Click "Open New".
Complete the form:
1. Hostname: The name of your Linux machine on the LAN.
2. Path - The "Share Name" (name of the share in your samba config), not the full directory path. (e.g. "backup-share" in the example).
3. Username - Your Linux username on the remote machine that you used to create the shared directory.
4. Password - The password you set above using smbpasswd

Click "Connect".


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

Mac Guides

Trusting Your Root CA (Mac)

Ensure you have downloaded your Root CA.
Locate your Root CA and double click it. Keychain Access will launch. You will be prompted for your Mac credentials. Select "Modify Keychain".
Press Command + Spacebar to launch a program, type in Keychain Access and select the resulting Keychain Access program to open it.
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:
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.

You will then be prompted again for your Mac credentials. Click Update Settings:
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:
If using Firefox or Tor Browser, complete this final step

Using a VPN (Mac)

Running Tor (Mac)

Install Homebrew

If you do not already have Homebrew installed, follow the installation instructions here. TLDR: Open the Terminal and paste the following line:
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
You will be prompted for your system password before installation; proceed with entering your password. You may be asked more than once.
You will be notified which directories Homebrew is going to create. Hit RETURN:

Homebrew may take a few minutes to download and install everything it needs.


Homebrew uses Google Analytics to collect anonymous usage data. You can deselect the option to share usage data by <a href="https://docs.brew.sh/Analytics#opting-out" target="_blank">opting out</a>

Install Tor

If you have the Tor Browser open, close it and quit the application.


If you are on a very old version of macOS, such as High Sierra (10.13) or below, first execute this command in a Terminal window, then close the Terminal app.

     echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile

Open the Terminal app and install Tor using the following command:
```
brew install tor
```
Then start Tor with:
```
brew services start tor
```
This will start Tor and ensure that it is always running, even after a restart. See the Tor Project docs for more details.

Enable Tor System-Wide

Content

Sonoma (MacOS 14)

Enable the proxy autoconfig file (This will download the Start9 standard proxy config file. You can use your own if you prefer):
```
sudo curl https://start9.com/assets/proxy.pac --output /Library/WebServer/Documents/proxy.pac
```

Enable Apache:

sudo launchctl enable system/org.apache.httpd
sudo launchctl kickstart system/org.apache.httpd


If these commands fail, your version of macOS may still use the older launchctl syntax:

    sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

Go to System Settings > Network and select the interface to edit. We recommend editing both Ethernet and WiFi. First do one, then the other:
Click Details > Proxies and paste the following URL into "Automatic Proxy Configuration": http://localhost/proxy.pac. Click "OK".
Repeat the previous two steps for Wifi/Ethernet, depending on which interface you haven't done yet.

Pre-Sonoma (MacOS 13 and Older)

Enable the proxy autoconfig file (This will download the Start9 standard proxy config file. You can use your own if you prefer):
```
sudo curl https://start9.com/assets/proxy.pac --output /Library/WebServer/Documents/proxy.pac
```

Enable Apache:

sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

Go to System Preferences > Network and select the interface to edit. We recommend editing both Ethernet and WiFi. First do one, then the other:
Click Advanced > Proxies and paste the following URL into "Automatic Proxy Configuration": http://localhost/proxy.pac
Repeat the previous two steps for Wifi/Ethernet, depending on which interface you haven't done yet.

Creating Backups to Mac

Create a Shared Folder

Identify or create a folder to store your server backups.


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

Go to System Settings > General > Sharing and click the "info" icon:
Click the toggle to enable file sharing, then click the "plus" icon and select your backups folder.
Click "Options".
Select the user who owns the folder.

You can now move in to Create a Backup


 You can find the hostname at the top of 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. You will need this in the next step. Alternatively you can use the computer hostname. (See directions below) Either method will work.

Create a Backup

In StartOS, go to System > Create Backup.
Click "Open New".
Complete the form:
1. Hostname: The name of your Mac. Check the tip in Step 5 of the section above to find it. On some versions of Mac, you may need to open up Terminal and type hostname.
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.

Click "Connect".


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

- **MacOS Catalina (version 10.15.7)** If the backup fails, please see this <a href="https://discussions.apple.com/thread/253970425" target="_blank">Apple support thread</a>. If the provided solution does not work, you will either need to update your Mac or use a physical drive for backups.

- **MacOS Ventura (version 13.2)** If you recently updated to Ventura, and you cannot get the folder to connect, do the following: in `System Settings > General > Sharing`, turn off file sharing, restart your mac, then turn file sharing back on.

Windows Guides

Trusting Your Root CA (Windows)

Ensure you have downloaded your Root CA.
Click the "Start" menu, type mmc, and select "Run as administrator" to access the Windows Management Console. When prompted with the "User Account Control" window, select "Yes" to allow this program to run.
When the Management Console opens, navigate to File > Add/Remove Snap-in.
Select "Certificates" in the left side menu, then "Add". This will open another window.
Select "Computer account" and click "Next". Leave defaulted options on the next screen and click "Finish".
When you return to the "Add or Remove Snap-ins" page, ensure "Certificates (Local Computer)" exists under "Console Root" in the "Selected snap-ins" section, then click "OK".
In the left hand menu of the Management Console, navigate to Certificates (Local Computer) > Trusted Root Certification Authorities > Certificates.
Right click on the "Certificates" directory, then navigate to All Tasks > Import.
Click "Next" on the first page of the Certificate Import Wizard, then browse to the location where you saved the downloaded certificate and open it. Then click "Next".
On the "Certificate Store" window, ensure that it says "Trusted Root Certificate Authorities" and click "Next". Then click "Finish" on the final screen.
Select "OK" when the import is successful.
Verify your server's unique <adjective-noun> Local Root CA certificate is in the "Certificates" folder:
You can save the console settings (where we added a snap-in), if desired. Your Root CA will remain imported to the CA certificate store either way, and you will likely use this guide if you need to import a new certificate.
If using Firefox or Tor Browser, complete this final step

Using a VPN (Windows)

Running Tor (Windows)

Unfortunately, Tor Project no longer publishes a standalone Tor binary for Windows, so the recommended way to get it is with the Tor Browser Bundle. You can download it here.
Once it is downloaded, run the installer by right clicking on it and selecting "Run as Administrator".

Once you have selected a language, you should see a menu like this:

install tor


We will install it to `C:\Program Files\Tor Browser`. 
If you choose a different folder, it needs to _not_ be anywhere under `C:\Users\`. Note the path you use here for the step after next.

Open your Command Prompt as an administrator. In Windows 10, you can simply type cmd in the Windows search bar. Right click on the first result, and select "Run as Administrator".

Configure Tor to run perpetually in the background. Insert your destination folder (from above) between binPath=" and the Browser subfolder

sc create tor start= auto binPath="C:\Program Files\Tor Browser\Browser\TorBrowser\Tor\tor.exe -nt-service"


If you receive `Access denied`

1. ensure you are running the command prompt in Administrator Mode. You can tell because the prompt will show C:\\Users\\YOUR-USERNAME> if you are _not_ in admin mode, and it will show C:\\WINDOWS\\system32 if you ARE in admin mode.

Start Tor.

sc start tor

tor running


If you receive `The specified service already exists`:

1. Run the command:

        sc delete tor

1. Uninstall the Tor Browser, following <a href="https://tb-manual.torproject.org/uninstalling/" target="_blank">these steps</a>.

1. Begin this guide again from the beginning.

If using Firefox or Tor Browser, complete this final step

Creating Backups (Windows)

Create a Shared Folder

Identify or create a folder to store your server backups.


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

Right click the folder and click "Properties".
Click "Sharing".
Click "Share".

Select a user you want to use for login and click "Share".

Select a user


If you get the following dialog box, you have designated your network "Public". You may wish to change to "Private" if this is your home network. Otherwise you may turn on network sharing for public networks.

   ![public network](./assets/backups-windows-4.png)

Note the Windows directory path in grey text, highlighted in blue, beginning at the first single slash (\). We will use that path later.

Create a Backup

In StartOS, go to System > Create Backup.
Click "Open New".
Complete the form:
1. Hostname: Enter your Windows computer name (this is shown after a \\).
2. Path - Enter the folder path followed by the share name displayed in the Windows sharing dialog shown copied from above. In our example this would be /Users/win/Desktop/SharedFolder. When entering the path, make sure replace the back slashes \ shown in Windows with forward slashes /.
3. Username - Your Windows user who owns the shared folder.
4. Password - Your password for the above user.

Click "Connect".


- If you receive `Filesystem I/O Error mount error(13): Permission denied`:

1. Ensure you are entering the correct username and password. You _cannot_ use a pin.

1. Ensure your windows password meets any length and complexity requirements set by your local Windows policy.

1. Office365 accounts also may not work at all, try a regular user in this case.

- If you receive `Filesystem I/O Error mount error(115): Operation now in progress`,

1. Navigate to `Start > Settings > Network & Internet > Ethernet (or WiFi)` and select the "Private" profile to treat your LAN as a trusted network that allows file sharing.

Android/Graphene Guides

Trusting Your Root CA (Android/Graphene)

This guide applies to Android 13+, GrapheneOS, CalyxOS, and LineageOS

Ensure you have downloaded your Root CA.
Go to Settings > Security > More security settings > Encryption & credentials > Install a certificate > CA Certificate > Install Anyway, then select your custom-named adjective-noun.crt certificate.
If using Firefox, you must use Firefox Beta, then complete this final step.

Using a VPN (Android/Graphene)

Running Tor (Android/Graphene)

Some apps have Tor built-in; they do not require additional software or configurations. Most apps, however, do not have Tor built-in. They require an app called Orbot.

Running Orbot

#. Install Orbot from the Play Store or F-Droid.


For F-Droid, enable the Guardian Project repository by going to `F-Droid > Settings > Repositories > Guardian Project Official Releases`

Open Orbot and click "Start VPN":
Open the kebab menu in the bottom right and click "Settings":
Make sure the options for Start Orbot on Boot and Allow Background Starts are both checked:

Orbot VPN Apps

Apps that support using a Socks5 Proxy can use Orbot as-is; no need to add them as VPN apps. Other apps, however, must to be added. If this applies to you, continue below.

In Android, go to Settings > Network & Internet > Advanced > Private DNS and toggle Private DNS to "off".
In Orbot, click "Choose Apps" and select the apps you want to utilize Tor.

iOS Guides

Trusting Your Root CA (iOS)

Ensure you have downloaded your Root CA.
Open your iCloud Downloads folder and click on the certificate. It will display a dialog box that says Profile Downloaded. Click "Close".
Head to Settings > General > VPN & Device Management:
Under "DOWNLOADED PROFILE", click your Root CA:
Click "Install":
Click "Install" again:
Click "Install" for a 3rd time:
You should see green text with a check-mark saying "Verified" under the Profile Installed dialog:
Tap "Done".
Go to General > About > Certificate Trust Settings and enable your Root Ca:
Click "Continue".

Using a VPN (iOS)

Running Tor (iOS)

Install Orbot.
In Orbot, click "Settings" and configure the following:
1. "Disable Orbot for non-onion traffic" -> On
2. "Disable GeoIP lookup for nodes" -> On
3. "Always clear cache before start" -> On
Go back to the main screen and click "Start":

Synology Guides

Creating Backups

Creating Backups to Synology

Create a Shared Folder

In the Synology UI, go to Control Panel > Shared Folder and choose the folder you want to use as the destination for the backup.


Do not select an encrypted folder. Encrypted folders on Synology enforce a character limit of 143 characters. At this time, StartOS backups use folder/file names that are longer than 143 characters. The backup process will fail if you try to backup to an encrypted folder.

Still in the Synology UI, go to Control Panel > File Services > SMB and click the SMB tab if it isn't already selected. Ensure that "Enable SMB service" is checked.
Under Advanced Settings on the same tab, set "Min SMB protocol" to SMB2 and "Max SMB protocol" to SMB3.
Also on the SMB tab, take note of your device name. Just under "Note" in a pale blue box, you will see "PC (Windows Explorer): " and "Mac (Finder):". These both provide network addresses that contain your device's name. This device name is the "Hostname" you will need to provide within the StartOS "New Network Folder" dialog in step 3 of the "Connect StartOS" section below.
Still in File Services, click on the rsync tab. Click the checkbox to enable the rsync service.
Back in the Synology UI, click "File Station" and locate the the desired destination folder. Right click the folder, then Properties > General. Next to "Location" will be a folder location. The portion of the location without the volume label is the value you will use for the "Path" within the StartOS New Network Folder dialog. For example, if the Location is /volume1/Backups, the value you care about is Backups.

Create a Backup

In StartOS, go to System > Create Backup.
Click "Open New".
Complete the form:
1. Hostname: The name of your Synology device on the LAN.
2. Path - The name of your shared folder, not the full directory path (e.g. Backups from the example above).
3. Username - Your Synology user who owns the shared folder.
4. Password - Your password for the above user.

Click "Connect".


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

TrueNAS Guides

Creating Backups

Creating Backups to TrueNAS

Create a Shared Folder

Ensure you have already created a ZFS disk pool in Storage > Pool as a place to store your backups. If you need help with this step, see the TrueNAS documentation.
In the TrueNAS UI, create a user for writing backups. Go to Accounts > Users > ADD.
Enter a Full Name, Username, and Password for the new user. Near the bottom, click "Shell: nologin", and enable "Samba Authentication". Click "SUBMIT". In this example, we will use "Start9 Server Backup" for the full name and "s9backup" for the username. You may choose a different values.
Go to Services > SMB. enable SMB and check the box "Start Automatically".
Open a shell and create your backups directory. In this example, we will create a directory called start9backupshare in the root of our storage pool. You may choose a different name or path.
```
mkdir /mnt/zpooldisk1/start9backupshare
```
Under Sharing > Windows Shares (SMB), drill down into the path until you find the directory to be shared. Give the share a name and click "SUBMIT". In this example we will name the share the nasshare. You may choose a different name.
A Configure ACL dialog will emerge. Click "CONFIGURE NOW".
You will be brought to an Edit ACL screen. Under "User", click "Apply User" and select the username we created in step 3. On the right-hand side, Permissions Type should be set to "Basic" and Permissions should be set to "Full Control". Click SAVE

Create a Backup

In StartOS, go to System > Create Backup.
Click "Open New".
Complete the form:
1. Hostname: The name of your TrueNAS device on the LAN. (e.g truenas.local)
2. Path - The name of your shared folder, not the full directory path (e.g. "nasshare" from the example).
3. Username - Your TrueNAS user who owns the shared folder. (e.g. "s9backup" from the example)
4. Password - Your password for the above user.

Click "Connect".


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

Bitcoin Core

Contents

BitBoxApp

This guide is adapted from Shiftcrypto.

Available For

Android
Linux
macOS
Windows

Instructions


You will need to be [running Tor in the background](../../../user-manual/connecting-remotely.md#running-tor-in-the-background-on-your-phonelaptop) on your device.

Ensure you are running Tor in the background on your device
In the BitBoxApp sidebar, select Settings > Enable tor proxy.
Enable the proxy and confirm the proxy address (127.0.0.1:9050).
Restart BitBoxApp in order for the new settings to take effect.
In the BitBoxApp sidebar, select Settings > Advanced settings > Connect your own full node.
In the field Enter the endpoint, paste your electrs Tor URL and Port (found in Electrs > Properties). For example: gwdllz5g7vky2q4gr45zGuvopjzf33czreca3a3exosftx72ekppkuqd.onion:50001
Click "Check", and you will be prompted with the message "Successfully established a connection".
Click "Add" to add your node to the node list at the top of the page.
Remove the other servers if you want to exclusively connect to your own node.

Blockstream Green

Available For

Android
iOS
Linux
macOS
Windows

Contents

Instructions

Desktop Wallet

Open Blockstream Green and click the gear icon on the bottom left to open the App Settings
Click the Network button
Toggle the Connect with Tor to On (Note: you don't need to connect through a proxy, but optionally can connect to your own if you have set one up.)
Click < Back, then click Custom servers and validation
Now toggle Choose the Electrum servers you trust to On to display a Bitcoin Electrum Server field.
Back in your StartOS web interface, go to Services > Electrs > Properties and copy the Quick Connect URL
Switch back to Blockstream Green and paste it into the Bitcoin Electrum Server field, and remove :t
Click < Back, then click X to close.


The current version of Blockstream Green no longer displays the status of your in-app Tor connection, unlike previous versions. This leaves you uncertain about whether you've completed the steps correctly or if any Tor connectivity issues are due to your server or the in-app Tor connection. In some situations, it may be worth connecting to your local proxy from Step 3, as you can verify that with commands.

Mobile Wallet

Open Blockstream Green and tap App Settings on the bottom or bottom right
Toggle Connect with Tor to On
Toggle Personal Electrum Server to On to display a Bitcoin Electrum server field.
Back in your StartOS web interface, go to Services > Electrs > Properties and copy the Quick Connect URL
Switch back to Blockstream Green and paste it into the Bitcoin Electrum Server field, and remove :t
Tap Save

Blue Wallet

Available For

iOS
Android

Blue Wallet on Mac cannot use Tor and is therefore not supported by StartOS.

Instructions


You will need to be [running Tor in the background](../../../user-manual/connecting-remotely.md#running-tor-in-the-background-on-your-phonelaptop) on your device.

In Blue Wallet, go to the settings menu and click "Network".
Click "Electrum Server".
Enter your electrs host (hostname) and port (found in Services -> electrs -> Properties). For example: gwdllz5g7vky2q4gr45zGuvopjzf33czreca3a3exosftx72ekppkuqd.onion:50001
Click 'Save'

Electrum


Completing this guide will _add_ your StartOS Electrum Server (electrs) to the list of servers used by Electrum. If, instead, you _only_ want to connect to your own server, ignoring all others, you will need to run Electrum in <a href="https://electrum.readthedocs.io/en/latest/tor.html" target="_blank">Single Server Mode</a> from the CLI.

Available For

Mac
Linux
Windows
Android/Graphene

Instructions


You will need to be [running Tor in the background](../../../user-manual/connecting-remotely.md#running-tor-in-the-background-on-your-phonelaptop) on your device.

Open Electrum and go to Tools > Network or, if you are running for the first time, choose "Select server manually," and click "Next".
Uncheck "Select server automatically", and enter your electrs Quick Connect URL (found in Services > electrs > Properties). Then click "Next".
Select "Use Tor" and "Use Proxy" and enter "127.0.0.1" for the address and "9050" for the port. Click "Next"
That's it! You will be prompted to create a wallet if this is your first time. You can check your connection by clicking the orb in the bottom right, which should be blue in color. If your server settings persist, you are connected.

Fully Noded

Available For

Blue Wallet on Mac cannot use Tor and is therefore not supported by StartOS.

Instructions

In Fully Noded, go to Settings > Node Manager > +
Enter your Bitcoin Core credentials. You can do this in one of two ways:

a. Use Fully Noded to scan your Quick Connect URL (found in Services > Bitcoin Core > Properties); OR

b. Enter your Bitcoin Core Tor URL (found in Services > Bitcoin Core > Interfaces) with :8332 appended, as well as you RPC Username and Password (found in Services > Bitcoin Core > Properties).

Nunchuck

Available For

Mac
Linux
Windows
Android/Graphene
iOS

Contents

Instructions

Nunchuck Mobile


You will need to be [running Tor in the background](../../../user-manual/connecting-remotely.md#running-tor-in-the-background-on-your-phonelaptop) on your device.

If using Android/Graphene, add Nunchuck to the list of VPN apps in Orbot.
Open Nunchuck and select Profile > Network Settings.
In the "Mainnet server" field, enter your electrs hostname and port (found in Services > electrs > Properties).
Click "Save network settings" and restart Nunchuck.

Nunchuck Desktop


You will need to be [running Tor in the background](../../../user-manual/connecting-remotely.md#running-tor-in-the-background-on-your-phonelaptop) on your device.

Open Nunchuck and go to Profile (bottom left) > Settings > Network Settings.
In the "MAINNET SERVER" field Enter your electrs hostname and port (found in Services > electrs > Properties).
Select "Enable TOR Proxy" and enter "127.0.0.1" for the address and "9050" for the port.
Click "Save network settings" and restart Nunchuck.

Sparrow

Available For

StartOS
Mac
Linux
Windows

Contents

Instructions

Sparrow on StartOS


To choose between a connection to Bitcoin Core or to Electrs, instead of using the Sparrow's own UI you will instead set your choice in the StartOS UI at `Services > Sparrow > Configuration`

Ensure Sparrow is installed and running if not already.
Click "Launch UI".

Sparrow Desktop


To connect to Bitcoin Core over your LAN you do not need to be running Tor, but connecting to your .local will mean you can't use Sparrow away from home.

To connect to Electrs (or Bitcoin Core over Tor), you must be running Tor. You can do this in two ways…
   
   1. You could be running a proxy on your computer by [running Tor in the background](../../../user-manual/connecting-remotely.md#running-tor-in-the-background-on-your-phonelaptop). In this case you would toggle-on `Use Proxy`. 
   
   1. You can use the Tor daemon built into Sparrow itself, which will start automatically when you enter a .onion. You can even do this if you are already running Tor locally.


You can use Sparrow's built-in Tor even if you are already running [Tor in background](../../../user-manual/connecting-remotely.md#running-tor-in-the-background-on-your-phonelaptop)… except on Windows, where you **must** use the proxy **if** you have already set it up and have it running.

If this is your first time using Sparrow, you will be guided to a screen to configure your Bitcoin server. Otherwise, you can find the server setup in File > Preferences > Server > Configure Server.
- Connecting to Bitcoin Core (recommended):
  1. In the URL field, enter your Bitcoin Core RPC URL (found in Services > Bitcoin Core > Interfaces).
    - If connecting locally, copy the LAN Address. Remove the https:// prefix and enter "443" for the port.
    - If connecting over Tor, copy the Tor Address. Remove the http:// prefix and enter 8332 for the port.
  2. In the User / Pass field, enter you Bitcoin Core RPC Username and Password (found in Services > Bitcoin Core > Properties)
  3. If you are connecting over Tor set up as a local Proxy …
    - Enable Use Proxy.
    - For URL, enter "localhost".
    - For Port, enter "9050".
    Otherwise, if you are using your .local or will use Sparrow's own Tor daemon, keep Use Proxy diabled.
  4. Test your connection
- Connecting to electrs:
  1. In the URL field, enter your electrs Tor hostname and port (found in Services > electrs > Properties). Currently, electrs can only be used over Tor.
  2. If you are connecting over Tor set up as a local Proxy …
    - Enable Use Proxy.
    - For URL, enter "localhost".
    - For Port, enter "9050".
    Otherwise, if you are using Sparrow's own Tor daemon, keep Use Proxy diabled.
  3. Test your connection

Specter

Available For

StartOS
Mac
Linux
Windows

Contents

Instructions

Specter on StartOS

Ensure Specter is installed and running if not already.
Click "Launch UI".

Specter Desktop

If this is your first time using Specter, you will be shown a screen to pick a connection method. But we'll skip this for now and set up Tor.
Click Settings and select the Tor tab.
- If you have Tor running as local Proxy scroll down and select Custom
  - Enter or leave the URL as socks5h://localhost:9050
  - Click Test connection - if it fails, please review your Tor proxy
- If you don't have Tor running in the background of your system, select Built-in
  - Click Set Up, then Setup Tor
- then click the Save button

Connecting to Bitcoin Core (Recommended)

Click the ... menu and click + Add Connection
In the Username and Password fields, enter your Bitcoin Core RPC credentials (found in Services > Bitcoin Core > Properties)
In Host, enter your Bitcoin Core RPC Interface Tor Address (found in Services > Bitcoin Core > Interfaces).
In Port, enter 8332 and click Connect

Connecting to Electrs


If you already have a Bitcoin Core connection set up, Specter will make you delete it before you can add your connection to Electrs. If you don't already have a connection, you can skip the first step.

Delete any connections you already have by clicking ..., hovering over the connection to reveal the cog icon, clicking the cog icon and then clicking Delete. Do this for all the connections you have.
Click Add plugin then click Spectrum
Select Enter my own
In the Host field, enter your electrs Tor hostname (found in Services > electrs > Properties) and enter your port as 50001.
Click Connect, then Let's Go!

Trezor Suite

Available For

Mac
Linux
Windows

Instructions

Click the gear icon to enter the settings menu.
Inside the Application tab, enable Tor.
Inside the Coins tab, hover over over Bitcoin to show the gear icon. Click it.
Under Backends, click the dropdown menu and select "Custom Electrum Server".
Enter your electrs Quick Connect URL (found in Services > electrs > Properties) and click "Confirm".

Description

If you already have a synced Bitcoin blockchain on one StartOS server, and would like to skip IBD on another StartOS server, follow this guide.


This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause through SSH access.

Instructions

In this guide, we will refer to your synced node as synced.local and your unsynced node as unsynced.local. Simply replace these URLs with your own.
In unsynced.local UI, install Bitcoin. Do not configure or start it.
In synced.local UI:
1. Ensure you have already have an SSH key.
2. Stop Bitcoin.
SSH into synced.local:
```
ssh start9@synced.local
```

Once inside the shell, run the following commands:

sudo -i

mkdir -m 0700 -p .ssh

ssh-keygen -t ed25519 -N '' -f .ssh/temp.key

chmod 600 .ssh/temp.key*

cat .ssh/temp.key.pub

Copy the output of the final cat command to your clipboard.
In unsynced.local UI, go to System > SSH > Add New Key, and paste the value from above. Click "Submit"

In synced.local shell, run the following commands, replacing unsynced.local in the second command with the correct URL:

cd /embassy-data/package-data/volumes/bitcoind/data/main/

rsync -e "ssh -i ~/.ssh/temp.key" -povgr --append-verify --rsync-path="sudo mkdir -p /embassy-data/package-data/volumes/bitcoind/data/main ; sudo rsync" ./{blocks,chainstate} start9@unsynced.local:/embassy-data/package-data/volumes/bitcoind/data/main/

Wait some hours until the copy is complete. On a gigabit network, the limiting factor will be the write speed of your SSD on the unsynced server.
When the copy is complete, in synced.local shell, run the following commands:
```
rm .ssh/unsynced.key*
```
```
exit
```
In synced.local UI, restart Bitcoin.
In unsynced.local UI:
- configure and start Bitcoin for the first time. You should see it begin at 99%+ pre-synced!
- Delete the temp.key SSH key we added above.

Jellyfin

Web Application


While the Jellyfin server is accessable over tor for many clients, connecting over LAN is recommended for the best streaming experience.

Access through a web browser is the simplest way to view media on a desktop or laptop. When logged in with an administrator account, it also allows you access to an administrator dashboard to add & remove user accounts and set age registrictions, and change other settings.

LAN/Router VPN

In a standard web browser, launch Jellyfin from the StartOS UI or access Jellyfin by typing the LAN interface into the address bar.

TOR

In Tor Browser, or another browser configured for Tor, launch Jellyfin from the StartOS UI or access Jellyfin by typing the .onion interface into the address bar.

Mobile Apps

Contents

Android
iOS

Instructions

Android

Before proceeding, make sure your Android device has been setup to connect over LAN. If you are connecting remotely, you will need to connect over a router VPN or setup Tor.

Visit the app store of your choice and download the Jellyfin Android app.
Open the app, you will be prompted for a host; paste the URL (.local recommended) from your Jellyfin service Services -> Jellyfin -> Interfaces in this field.
Next enter your username and password and tap "Sign In".


If you are getting connection errors, make sure you are connected to the same LAN and a external VPN is not blocking use on your device.

iOS

Before proceeding, make sure your Apple device has been setup to connect over LAN. If you are connecting remotely, you will need to connect over a router VPN or setup Tor.

Open the Apple App Store and download the Jellyfin iOS app.
Open the app, you will be prompted for a server address; paste the URL (.local recommended) from your Jellyfin service Services -> Jellyfin -> Interfaces in this field.
Next enter your username and password and tap "Sign In".


If you are getting connection errors, make sure you are connected to the same LAN and a external VPN is not blocking use on your device.

Desktop Apps

Contents


You can access Jellyfin and play your media through a [web browser](./web-application.md) if you prefer, rather than install an app.

Instructions

MacOS or Windows

Before proceeding, make sure your device has been setup to connect over LAN. If you are connecting remotely, you will need to connect over a router VPN or setup Tor.

Download the .dmg file (MacOS) or the .exe file (Windows) for Jellyfin Media Player.
Upon opening the client, you will be prompted to add server. Click "Add Server".
Next you will be prompted for a server address; paste the URL (.local recommended) from Jellyfin service interfaces (Services -> Jellyfin -> Interfaces) and click "Connect".
Next enter your username and password and click "Sign In".

Jellyfin

Jellyfin has numerous other clients, not all of which have been tested at the time of writing. If you are able to test (successfully or unsucessfully) an app not documented in this guide, your feedback would be much appreciated.


Some clients such as 'Jellyfin for Roku', 'Swiftfin' (tvOS) and other Samsung/LG Smart TV apps previously would not run as they were unable to resolve private urls like ``.local``. These should now work using your unique adjective-noun.local and port number found under `Services -> Jellyfin -> Interfaces`.

Lightning Network

Contents

Getting Started

Opening Your First Channel - We use Ride The Lightning (RTL) as the tool to interact with and to fund our CLN or LND wallet, then open a private channel to Start9.
Getting Inbound Liquidity - We look at the common ways to receive payments having only just opened a channel with all the liquidity on your side.

Connecting to CLN

Connect Directly to Core Lightning - Core Lightning is one of the two lightning implementations found on StartOS. It was created and is maintained by Blockstream.

Connecting to LND

Connect Directly to LND - LND is the second of the two lightning implementations found on StartOS. It was created and is maintained by Lightning Labs.
- Alby
- BitBanana
- Fully Noded
- RTL
- Zeus
Connecting to LND via Lightning Node Connect (LNC) - Lightning Node Connect (LNC) provides a very simple way to connect to an LND node that does not require the Tor network.

Using LNbits

Connect to LNbits wallets – Create and connect to a walled-off wallet in a layer above your lightning network implementation of CLN or LND.

Opening Channels

Here we'll show you how to install a lightning node and how to open a channel with Start9! We recommend first taking a moment to understand the important concept of liquidity.

Running a Node and Making a Channel with Start9

First, ensure that you have Bitcoin Core installed, running, and fully synced.
Install a lightning node. There are two options we offer on the Start9 marketplace - LND and Core Lightning. In this guide we're going to use Core Lightning (CLN). Though you can use LND and the process will be almost exactly the same.
Install one of the above lightning implementations - as mentioned in this guide we'll use CLN.
You'll see CLN say Needs Config. Click Configure:
You can leave the settings as their default values and hit SAVE.
Now hit Start and wait for CLN to sync up to the network. This may take a couple of hours.
Once the Synced health check turns green (as below) you can proceed to the next step.
To interact with your node we will use Ride The Lightning (RTL) - this is a service that provides a graphical user interface for our lightning node.

This will work with either (or both!) lightning implementations.
Install it and click on Configure just like with CLN.
It will default to LND. In this case we are using a CLN node instead, so we will change the default setting as shown:

Change to Core Lightning (CLN) and hit OK:

Hit Save:
Now hit Start:
With RTL started, click Properties:
Copy the automatically generated password:
Head back to the RTL service and click Launch UI:

Enter the copied password and log in:
```
You can add the password to your password manager for convenience.
```
Once in RTL, click On-chain then click Generate Address:

Send bitcoin to the generated address to add funds to your lightning wallet:

Configure RTL


 Please do not send money to the address pictured above as we will not receive it. If you are intent on sending us money please [head here](https://donate.start9.com).

Once your sats confirm on-chain you'll see this:
Now we must add a peer with which to make channels. In this example we will be opening a channel with Start9 so we will add Start9's node as a peer. Click Peers/Channels:
Click Peers then Add Peer:
Enter the details of the lightning node you'd like to open a channel with. Start9's node can be found here and is what we'll use in this example. You can use another node if you like - ideally one that is well connected. Once chosen and added as below, click Add Peer:
```
 The syntax is as follows **NodePublicKey@ipaddress:port** - If it's a Tor node it will be **PublicKey.onion:port** instead.
```

Then you can enter an amount (the size of the channel), select Private Channel (unless you want a public channel - see below), and a Fee Rate (check a block explorer for an idea of current necessary fees):

Configure RTL


 Here we are creating a very small channel with a capacity for payments of only a few dollars. You will likely want your channel to be larger than this so that it's actually usable for reasonably sized payments. Channels this small may well get closed by the remote peer.


 Using a private channel is what we advise as a default. You may wish for the channel to be public if you intend on becoming a routing node or for other reasons.

You will now see your channel in Channels -> Pending/Inactive:
Once the transaction opening the channel gets added to a block your channel will soon appear here under Open:
To make a payment head to the Transactions tab and press Send Payment:

That's it! You now have a lightning node running with a channel open ready to send payments on the lightning network!


 You will not be able to receive payments until you have inbound liquidity in your channel. After completing the above process you will only have outbound liquidity. Inbound liquidity can be created by making payments, having someone open a channel to you or via more sophisticated channel creation.

 [This guide](getting-inbound-liquidity.md) will explain more about attaining inbound liquidity.

If you want to connect other applications or wallets to your node, please see the guides here.

Getting Inbound Liquidity

Before you read this, it's important to understand the important concept of liquidity. This guide summarizes some of the ways you can get some inbound liquidity after opening a new or first channel.

Spending Sats

The simplest way to gain inbound liquidity is to spend some of your outbound liquidity. Whether you send this to yourself or spend it on a purchase, the end result will be inbound liquidity equal to the amount you have spent.

Let's say you have opened a channel of 1 million sats and you'd like this "balanced" so that you have 500k outbound and 500k inbound. To do this, you'll have to send 500k sats from your node to somewhere else.

Common options

Buy something you'd ordinarily buy using a service like Bitrefill or The Bitcoin Company, then buy back the sats with fiat.
Send 500k sats to another wallet you control, or pay your friend the 500k sats you owe!
Donate to Start9

"Loop Out", or perform a swap

Oftentimes when people open a channel, again, let's use 1 million sats as an example, they'd like to be both better connected to the Lightning Network with more than one channel and have inbound and outbound liquidity on both channels. But if you've just opened a channel with the majority of your on-chain funds, you now have just one channel with all your funds as outbound liquidity.

To get some of these sats back as on-chain funds, and so free up the channel so that it has some inbound liquidity, we need to send sats via lightning and have them come back to us at an on-chain Bitcoin address (optionally back to your CLN or LND node to open another channel).

This is typically done using third-party services such as Loop, Boltz, Deezy, and probably a few others. They'll provide you with a lightning invoice to pay and ask you in turn for a Bitcoin address to send to. In return for this service, you'll pay a percentage fee.


In using a swap service, you'll not only pay the third-party a fee for their service, but you'll also be charged for the resulting on-chain fee. This means when swapping or "looping" out 500k, you'll receive the majority but not all of it back. This means any second channel you open will be smaller than the first unless you add more on-chain funds.


Start9 doesn't recommend, vouch for or have any relationship with the third-parties listed as examples.

You can acheive the same effect as using an official swap tool with many lightning wallets that have their own swapping functionality built in. Though this is generally intended for you to be able to pay an on-chain invoice/address through the app rather than for channel management, it can be useful in a pinch. Send to the wallet over lightning, send back to yourself onchain, paying the wallet's own swap fees in the process.

Get peers to open channels to you

When you open a channel to someone else, by default, you'd have all the liquidity on your side of that channel. You'd have only outbound liquidity. On your channel partner's side of the channel, they would see that all the liquidity is on your side and that they only have inbound liquidity.

In the same way that you're giving someone else inbound liquidity by opening your channel to them, you can get inbound liquidity by having someone open a channel to you.

You can convince someone to do this, pay someone to do this, or make friends with others and open reciprocal channels as a group.

Buying Lquidity

There are those who make a business out of selling liquidity. These businesses will charge a fee to open a channel to you from their well-connected nodes, giving you inbound liquidity to use immediately. They will typically agree to keep the channel open for a specific period of time. Examples of these businesses include LNBig and Deezy.

There are also marketplaces where ordinary users sell their liquidity. These could probably be considered a better option. Most sellers are well connected but not heavily centralized, and you have a channel partner you can reach out to and talk with. They'd often be willing to keep the channel open longer if you ask them or if you use it. One popular market for this is Magma.

Swapping Liquity

The easiest, cheapest, and best way to get and offer liquidity is to make agreements with fellow Lightning Network users and open reciprocal channels as a group. You'll often have a chance to learn from more experienced peers (i.e., how to do a circular rebalance) and get two channels by just opening one yourself. For example, in a triangular swap, you open with A, A opens with B, B opens with you. Each user gets 2 channels and 50% inbound. The best example of this is lightning network+

Connecting to CLN

Core Lightning is one of the two lightning implementations found on StartOS. It was created and is maintained by Blockstream.

Core Lightning - Alby

Alby is a browser extension that can be connected to your lightning node a number of ways. This guide will go over direct connections between Alby and your Core Lightning node.

If you'd like to connect via LNbits which allows allocation of funds, please see this guide.


We are going to connect using Tor so that Alby will be able to connect from anywhere.

Make sure you are already running Tor on your system and we suggest using Firefox which must be configured to use Tor
Download the Alby extension by visiting the Alby Github, selecting your browser, and installing.
On the Alby welcome screen, select Get Started.
Create a strong password and store it somewhere safe, like your Vaultwarden password manager.
On the next screen, select Bring Your Own Wallet and click Connect.
Click Start9 first...
... and only then Core Lightning.
You will see the following fields to fill out:
For "Host" this is your Peer Interface - find this under Interfaces -> Machine Interfaces within the CLN service on your Start9 server. Copy the address shown here but remove the http:// at the start and paste it into Host within Alby:
For Public key enter your Node Id found at the top of Properties within the CLN service on your server.
To generate a rune on StartOS you will need to navigate to Core Lightning > Actions > Generate Rune. Then copy the value and paste it into Alby.
Leave the Port as 9735.
Click Continue. Once the connection is completed you will see a success page that displays the balance of your CLN node in Sats.

Alby is now connected to your CLN node over Tor!

Core Lightning - RTL

This can simply be installed by going to the StartOS marketplace, clicking on Ride The Lightning and then installing the latest version.

Once installed you can configure it to work with either - or both - Core Lightning and LND!

Config RTL

Core Lightning - Zeus

Zeus is a powerful mobile wallet that can be connected directly to both LND and Core Lightning. If you'd like to connect via LNbits, which allows allocation of funds, please see this guide.

Available For:

Android
iOS


This guide will go over how to connect Zeus to **CLN**. If you'd like to connect Zeus to LND instead - please use [this guide](../lnd/zeus.md).

Download Zeus for your device.
Log into StartOS and select Services -> CLN -> Properties. Then expand REST Properties.
Tap the QR code icon for REST Quick Connect to display the QR code.
In Zeus, tap "Scan node config". Allow camera access, scan the QR code, and then tap 'Save node config'. Zeus will fill in your node details based on the information in the QR code.
Click SAVE NODE CONFIG


If you already have other nodes configured in Zeus, go to Settings.-> Connect a node -> + . Then scan the QR code, and tap "Save node config".

That's it. You can now use your CLN Node via Zeus.

Connecting to LND

LND is the second of the two lightning implementations found on StartOS. It was created and is maintained by Lightning Labs.

Lightning Node Connect (LNC)

Connecting to LND via Lightning Node Connect (LNC) - Lightning Node Connect (LNC) provides a very simple way to connect to an LND node that does not require the Tor network.

LND - Alby

Alby is a browser extension that can be connected to your lightning node a number of ways. This guide will go over direct connections between Alby and your LND node.

If you'd like to connect via LNbits which allows allocation of funds, please see this guide.


We are going to connect using Tor so that Alby will be able to connect from anywhere.

Make sure you are already running Tor on your system and we suggest using Firefox which must be configured to use Tor
Download the Alby extension by visiting the Alby Github, selecting your browser, and installing.
On the Alby welcome screen, select Get Started.
Create a strong password and store it somewhere safe, like your Vaultwarden password manager.
On the next screen, select Bring Your Own Wallet and click Connect.
Click Start9 first...
... and only then LND.
Copy the LND Connect REST URL from your LND service page’s Properties section and paste it into Alby:
Alby will pick up that you are connecting over Tor and suggest using their Companion App (only needed if your browser isn’t setup to use Tor) or using Tor natively which you will be able to do. Select TOR (native) and click Continue:


If this does not work, please ensure that Tor is running on your system and that Firefox is configured to use it. If you can’t get this to work it’s OK to use the Companion App - but you will have a better experience with your Start9 server elsewhere if you take the time to get Tor running on your devices.

Once connection is completed you will see a success page that displays the balance of your LND node in Sats..

Alby is now connected to your LND node over Tor!

LND - BitBanana


Compatible with LND only

Install BitBanana on your phone.
In BitBanana go to Connect Node.
Locate the LND Connect gRPC URL from your LND service page's Properties section.
Display the QR code by clicking on the QR code icon.
Scan the QR code with your phone.

BitBanana is now connected to your LND node!

LND - Fully Noded

Sovereign, secure, powerful, and easy-to-use wallet that utilizes your own LND node as a backend.

Available For:

iOS
macOS

Download Fully Noded from the Apple App Store.
Log into your Start9 server UI and select Services -> LND -> Properties.
Click the QR code icon next to “LND Connect REST URL” to display the QR code and scan/copy this with your iPhone/mac.

[Scanning QR] From the App, you have to go > Node manager > Add a node + > hit Scan QR (not LND)

[Pasting credentials] From the App, you have to go > Node manager > Add a node (+) > select LND (not Scan QR).

If pasting, there are 4 fields where we'll paste the LND Connect URL we copied earlier:
- Label (pick a name for your LND node)
- Address (paste the address without the word "lndconnect")
- Macaroon (paste the macaroon without the word "macaroon")
- SSL Cert (optional field - leave it blank)
Press "SAVE"

You can now use Fully Noded with your LND node to send/receive bitcoin over the lightning network, open/close channels, connect to peers, etc!

LND - RTL

This can simply be installed by going to the StartOS marketplace, clicking on Ride The Lightning and then installing the latest version.

Once installed you can configure it to work with either - or both - Core Lightning and LND!

Config RTL

LND - Zeus

Zeus is a powerful mobile wallet that can be connected directly to both LND and Core Lightning. If you'd like to connect via LNbits, which allows allocation of funds, please see this guide.

Available For:

Android
iOS


This guide will go over how to connect Zeus to **LND**. If you'd like to connect Zeus to CLN instead - please use [this guide](../cln/zeus.md).

Download Zeus for your device.
Log into StartOS and select Services -> LND -> Properties.
Tap the QR code icon for LND Connect REST URL to display the QR code.
In Zeus, tap "Scan node config". Allow camera access, scan the QR code, and then tap 'Save node config'. Zeus will fill in your node details based on the information in the QR code.
Click SAVE NODE CONFIG


If you already have other nodes configured in Zeus, go to Settings.-> Connect a node -> + . Then scan the QR code, and tap "Save node config".

That's it. You can now use your LND Node via Zeus.

Connect to LND via Lightning Node Connect (LNC)

Lightning Node Connect (LNC) provides a very simple way to connect to an LND node that does not require the Tor network.

This is not the same as connecting directly to LND for which guides can be found here.


This requires installing the [Lightning Terminal](https://marketplace.start9.com/marketplace/lightning-terminal) service from the marketplace.

The following two guides go over how to connect wallets to LND via LNC.

Alby
Zeus

LND via Lightning Node Connect (LNC) - Alby

Alby is a browser extension that can be connected to your lightning node a number of ways. This guide will go over connecting Alby and LND using LNC.

If you'd like to connect directly using LND's REST API see here. If you'd like to connect via LNbits which allows allocation of funds, please see this guide.


This requires installing the [Lightning Terminal](https://marketplace.start9.com/marketplace/lightning-terminal) service from the marketplace.

Download the Alby extension by visiting the Alby Github, selecting your browser, and installing.
Install Lightning Terminal from the marketplace.
On the Alby welcome screen, select Get Started.
Create a strong password and store it somewhere safe, like your Vaultwarden password manager.
On the next screen, select Bring Your Own Wallet and click Connect.
Click Start9 first...
... and only then Lightning Terminal (LNC).
You will see the following screen. Launch the Lightning Terminal service UI from your Start9 server and do as instructed below:
Click Continue and you will see this once you successfully connect:

Alby is now connected to your LND node via LNC!

LND via Lightning Node Connect (LNC) - Zeus

Zeus is a powerful mobile wallet that can be connected directly to LND and or avoiding Tor via LNC. This guide will go over connecting Alby and LND using LNC.

Available For:

Android
iOS

If you'd like to connect directly using LND's REST API see here. If you'd like to connect via LNbits which allows allocation of funds, please see this guide.


This requires installing the [Lightning Terminal](https://marketplace.start9.com/marketplace/lightning-terminal) service from the marketplace.

Download Zeus for your device.
Install Lightning Terminal from the marketplace.
Log into StartOS and select Services -> Lightning Terminal and click Launch UI. The password can be found in Services -> Lightning Terminal -> Properties.
From the Lightning Terminal interface, click Lightning Node Connect.
Click to Create a new session.
Name the wallet and click Submit.
Click on the QR code:
Open up Zeus and click SCAN NODE CONFIG then scan the QR code.
Tap SAVE NODE CONFIG.


If you already have other nodes configured in Zeus, go to Settings.-> Connect a node -> + . Then scan the QR code, and tap "Save node config".

That's it. You can now use your LND Node via LNC with Zeus.

Using LNbits

The Concept

LNbits allows you to create a wallet that makes use of your node with only an alloted amount of sats. This restriction can be very helpful for if you only want to have a small amount for spending on your phone without making your entire lightning balance available. You can even allow other people to have wallets you create for them - think giving your children an allowance. They can start with a set amount (can be zero) and simply spend what you initially make available. They can also earn more for themselves as they will have the freedom to issue their own invoices - all while making use of your node.


All wallets created this way are ultimately bound by the capacity of your node. If one wallet is allocated 10,000 sats but your underlying node only has 9000 sats of outbound capacity, payments will simply fail.

What lightning node should I use?

LNbits will work for both Core Lightning (CLN) and LND but if you want to connect Zeus or BlueWallet to LNbits then this will only work with LND as the underlying node. This is because the LNDhub plugin will be required.

If you are looking to connect the Alby browser extension to your LNbits wallet, that will work with both CLN and LND.

Setting up LNbits

Start by ensuring that you have LNbits installed already as well as LND or Core Lightning (CLN). You also need your lightning node to have at least one channel set up otherwise payments will not work. If you have not set up a channel yet, please follow this guide.


 Remember - if you intend to connect BlueWallet or Zeus, that will only be possible with LND. Alby can work with both.

Head to LNbits on your server, click on Properties and copy the address under (Tor) Superuser Account:

Paste this address into your browser and you'll see the following screen - click I understand:

LNbits superuser


This isn't a concern on StartOS as all wallets created will have the address they generated stored within **Properties** within the LNbits serivce.

Now a default wallet will have already been generated - highlighted on the top left. We'll rename it to something we can remember by clicking Rename wallet entering somthing-you-can-remember then clicking UPDATE NAME:

Now you can proceed to connect one of the following wallets to LNbits using the guides below:

Funding LNbits

After any of the above wallets has been setup with the corresponding instructions, you can allocate sats to this wallet within LNbits by clicking the "+" icon here:

LNbits fund +

LNbits fund amount

LNbits fund complete


Remember: All wallets are ultimately bound by the capacity of your node. If one wallet is allocated 1,000 sats but your underlying node only has 900 sats of outbound capacity, payments will simply fail.

Your newly created LNbits wallet has now been funded and is ready to send sats over the Lightning Network!

Using LNbits

The Concept


All wallets created this way are ultimately bound by the capacity of your node. If one wallet is allocated 10,000 sats but your underlying node only has 9000 sats of outbound capacity, payments will simply fail.

What lightning node should I use?

If you are looking to connect the Alby browser extension to your LNbits wallet, that will work with both CLN and LND.

Setting up LNbits

Start by ensuring that you have LNbits installed already as well as LND or Core Lightning (CLN). You also need your lightning node to have at least one channel set up otherwise payments will not work. If you have not set up a channel yet, please follow this guide.


 Remember - if you intend to connect BlueWallet or Zeus, that will only be possible with LND. Alby can work with both.

Head to LNbits on your server, click on Properties and copy the address under (Tor) Superuser Account:

Paste this address into your browser and you'll see the following screen - click I understand:

LNbits superuser


This isn't a concern on StartOS as all wallets created will have the address they generated stored within **Properties** within the LNbits serivce.

Now a default wallet will have already been generated - highlighted on the top left. We'll rename it to something we can remember by clicking Rename wallet entering somthing-you-can-remember then clicking UPDATE NAME:

Now you can proceed to connect one of the following wallets to LNbits using the guides below:

Funding LNbits

After any of the above wallets has been setup with the corresponding instructions, you can allocate sats to this wallet within LNbits by clicking the "+" icon here:

LNbits fund +

LNbits fund amount

LNbits fund complete


Remember: All wallets are ultimately bound by the capacity of your node. If one wallet is allocated 1,000 sats but your underlying node only has 900 sats of outbound capacity, payments will simply fail.

Your newly created LNbits wallet has now been funded and is ready to send sats over the Lightning Network!

Using LNbits

The Concept


All wallets created this way are ultimately bound by the capacity of your node. If one wallet is allocated 10,000 sats but your underlying node only has 9000 sats of outbound capacity, payments will simply fail.

What lightning node should I use?

If you are looking to connect the Alby browser extension to your LNbits wallet, that will work with both CLN and LND.

Setting up LNbits

Start by ensuring that you have LNbits installed already as well as LND or Core Lightning (CLN). You also need your lightning node to have at least one channel set up otherwise payments will not work. If you have not set up a channel yet, please follow this guide.


 Remember - if you intend to connect BlueWallet or Zeus, that will only be possible with LND. Alby can work with both.

Head to LNbits on your server, click on Properties and copy the address under (Tor) Superuser Account:

Paste this address into your browser and you'll see the following screen - click I understand:

LNbits superuser


This isn't a concern on StartOS as all wallets created will have the address they generated stored within **Properties** within the LNbits serivce.

Now a default wallet will have already been generated - highlighted on the top left. We'll rename it to something we can remember by clicking Rename wallet entering somthing-you-can-remember then clicking UPDATE NAME:

Now you can proceed to connect one of the following wallets to LNbits using the guides below:

Funding LNbits

After any of the above wallets has been setup with the corresponding instructions, you can allocate sats to this wallet within LNbits by clicking the "+" icon here:

LNbits fund +

LNbits fund amount

LNbits fund complete


Remember: All wallets are ultimately bound by the capacity of your node. If one wallet is allocated 1,000 sats but your underlying node only has 900 sats of outbound capacity, payments will simply fail.

Your newly created LNbits wallet has now been funded and is ready to send sats over the Lightning Network!

Using LNbits

The Concept


All wallets created this way are ultimately bound by the capacity of your node. If one wallet is allocated 10,000 sats but your underlying node only has 9000 sats of outbound capacity, payments will simply fail.

What lightning node should I use?

If you are looking to connect the Alby browser extension to your LNbits wallet, that will work with both CLN and LND.

Setting up LNbits

Start by ensuring that you have LNbits installed already as well as LND or Core Lightning (CLN). You also need your lightning node to have at least one channel set up otherwise payments will not work. If you have not set up a channel yet, please follow this guide.


 Remember - if you intend to connect BlueWallet or Zeus, that will only be possible with LND. Alby can work with both.

Head to LNbits on your server, click on Properties and copy the address under (Tor) Superuser Account:

Paste this address into your browser and you'll see the following screen - click I understand:

LNbits superuser


This isn't a concern on StartOS as all wallets created will have the address they generated stored within **Properties** within the LNbits serivce.

Now a default wallet will have already been generated - highlighted on the top left. We'll rename it to something we can remember by clicking Rename wallet entering somthing-you-can-remember then clicking UPDATE NAME:

Now you can proceed to connect one of the following wallets to LNbits using the guides below:

Funding LNbits

After any of the above wallets has been setup with the corresponding instructions, you can allocate sats to this wallet within LNbits by clicking the "+" icon here:

LNbits fund +

LNbits fund amount

LNbits fund complete


Remember: All wallets are ultimately bound by the capacity of your node. If one wallet is allocated 1,000 sats but your underlying node only has 900 sats of outbound capacity, payments will simply fail.

Your newly created LNbits wallet has now been funded and is ready to send sats over the Lightning Network!

Alby with LNbits

Alby is a browser extension that can be connected to your lightning node a number of ways. This guide will go over connecting Alby to your LNbits wallet which allows allocation of funds.

If you'd like to connect to LND or CLN directly with Alby, start here.


This guide assumes you have already setup LNbits as per [this guide](../lnbits.md).

Make sure you are already running Tor on your system and we suggest using Firefox which must be configured to use Tor
Download the Alby extension by visiting the Alby Github, selecting your browser, and installing.
On the Alby welcome screen, select Get Started.
Create a strong password and store it somewhere safe, like your Vaultwarden password manager.
On the next screen, select Bring Your Own Wallet and click Connect.
Click Start9 first...
... and only then LNbits.
You will see the following fields to fill out:
Head back to LNbits and select the wallet you created then click on the arrow to the right of API Info:
Copy the Admin key and paste it into Alby
Head back to your Start9 server’s LNbits service page and select Interfaces:
Copy the Tor Address:
Head back to Alby and paste what you just copied into LNbits URL, select Tor (native) then hit Continue:
Click Continue. Once the connection is completed you will see a success page that displays the balance of your CLN node in Sats.


Make sure to include the http:// at the start of the address. If it is not working make sure that you are properly [configured Tor](../../../user-manual/connecting-remotely.md) on your system.

Once connected you should see the following success page:

Alby is now connected to your lightning node via LNbits!
In addition to allocating sats to this wallet via the LNbits Superuser Account (see “Funding LNbits section” here), you can also receive funds the normal way by hitting Receive within Alby.


Funds received this way must be sent from another lightning node, not the node underneath LNbits. A lightning payment that originates and terminates at the same node is technically a rebalance, not a normal payment.

You’re now setup with Alby and LNbits!

BlueWallet with LNbits


This guide assumes you have already setup LNbits as per :ref:`this guide <connecting-lnbits>` with **LND** as your underlying node.


**This will not work with CLN as your underlying node!**

BlueWallet requires that we use the LnbHub extension in order to connect to LNbits.
To do this, click Manage Extensions:
Click MANAGE under the LndHub extension:
Click the two arrows on the right, then click install:
Now ensure that it says Activated underneath LndHub and then click Extensions on the left:
Click ENABLE:
Click OPEN or LndHub under Extensions:
Make sure the wallet you just created is selected below the two QR codes:
Open up BlueWallet and click on the three dots in the top right:
Click "Network" then "Tor settings":
Click "Start" and it should say "Done" after a short time:
Head back to the main screen and click the "+" sign:
Click "Import wallet":
Click "Scan or import a file"
If you only want this wallet to be able to RECEIVE PAYMENTS, scan this QR code:

If you are happy for this wallet to be able to both receive and MAKE payments scan this QR code:
You'll see this once the wallet is added:
In addition to allocating sats to this wallet via the LNbits Superuser Account (see "Funding LNbits section" here), you can also receive funds the normal way by hitting "Receive" within BlueWallet.


Funds received this way must be sent from another lightning node, not the LND node underneath LNbits. A lightning payment that originates and terminates at the same node is technically a rebalance, not a normal payment.

Congratulations! BlueWallet is set up and ready to use lightning via your own lightning node - furthermore it will only be able to use your node in the way you allow it, via LNbits.

Zeus with LNbits


This is not the same as connecting Zeus directly to your lightning node - using LNbits allows us to allocate a specific amount of funds to Zeus instead of giving it full access to your lightning node. We can also use LNbits to permit Zeus to **just receive** satoshis, or the ability to both **receive and spend** satoshis.


This guide assumes you have already setup LNbits as per [this guide](../lnbits.md).


**This will not work with CLN as your underlying node!**

Zeus requires that we use the LnbHub extension in order to connect to LNbits.
To do this, click Manage Extensions:
Click MANAGE under the LndHub extension:
Click the two arrows on the right, then click install:
Now ensure that it says Activated underneath LndHub and then click Extensions on the left:
Click ENABLE:
Click OPEN or LndHub under Extensions:
Make sure the wallet you just created is selected below the two QR codes:
Install Zeus.
Open it up and click SCAN NODE CONFIG.
If you only want this wallet to be able to RECEIVE PAYMENTS, scan this QR code:

If you are happy for this wallet to be able to both receive and MAKE payments scan this QR code:
Once scanned, name the wallet if you wish, then hit SAVE NODE CONFIG.

Zeus will now connect to your node and you'll see this screen:

Connect Zeus


If it doesn't work, please manually restart the Zeus app.

In addition to allocating sats to this wallet via the LNbits Superuser Account (see "Funding LNbits section" here), you can also receive funds the normal way by hitting Request within Zeus.

Connect Zeus


This will only work if your node has inbound liquidity. And you cannot send sats from the LND node LNbits is using as that is not a regular lightning payment - that is a reblanace.

Once you have added sats, you can click on this button within Zeus and see your new balance

Congratulations! Zeus is set up and ready to use lightning via your own lightning node - furthermore it will only be able to use your node in the way you allow it, via LNbits.

Firefox Guides

Trusting your Root CA (Firefox)

These guides apply to Firefox, Firefox ESR, Librewolf, and Thunderbird. Mozilla apps need to be configured to use the certificate store of your device. Please refer to their blog post for an explanation (TLDR: for security purposes).

Mac / Windows

Open Firefox and enter about:config in the URL bar. Accept any warnings that appear.
Search for security.enterprise_roots.enabled and set the value to "true".
Restart Firefox

Debian / Ubuntu

In the hamburger menu, click "Settings". Search for security devices and select "Security Devices..."
When the Device Manager dialog window opens, click "Load".
Give the Module Name a title, such as "System CA Trust Module". For the Module filename, paste in /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-trust.so and hit "OK".
```
The path to p11-kit-trust.so will be slightly different if your processor's architecture is not x86_64.
```
Verify that the new module shows up on the left hand side and click "OK" in the bottom right:
Restart Firefox

Android / Graphene


The regular Firefox app will not work. You must use `Firefox Beta <a href="https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta" target="_blank">Firefox Beta</a>.

Go to Menu > Settings > About Firefox and tap the Firefox icon 5 times to enable "developer mode".
Go back to Menu > Settings > Secret Settings (at the bottom), and tap "Use third party CA certificates".

Arch / Garuda / CentOS / Fedora

No special steps required.

Enabling Tor (Firefox)

All Platforms

Ensure you have already followed instruction for running Tor on your platform.
- Mac
- Linux
- Windows
- Android/Graphene
Open Firefox and enter about:config in the URL bar. Accept any warnings that appear.
Search for dom.securecontext.allowlist_onions and set the value to "true".

Mac

Ensure you have completed the steps under All Platforms.
In the main hamburger menu, click "Settings".
Using the search bar, enter proxy, then select Settings....
Select both boxes: Use System Proxy Settings and Proxy DNS when using SOCKS v5.
Click "OK".
Restart Firefox.
Test that Firefox can resolve .onion URLs by visiting Start9's Tor website: http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion.

Linux


If you cannot connect after following this guide, your Firefox may be installed in a jailed environment, such as an AppImage, Flatpak, or SNAP. Ubuntu uses a SNAP for Firefox, so you may experience issues on Ubuntu-based systems. Please install Firefox via an alternate method that does not isolate Firefox from the wider filesystem.

Ensure you have completed the steps under All Platforms.
You need a Proxy Auto Config file to inform Firefox how to resolve .onion URLs. You can get Start9's standard file from a terminal, by using the following command:
```
sudo wget -P ~/ https://start9.com/assets/proxy.pac
```
Determine the full path of proxy.pac, which we will use later, by executing the following command in the terminal, and copying its output to your clipboard:
```
echo file://$HOME/proxy.pac
```
In the main hamburger menu, click "Settings".
Using the search bar, enter proxy, then select Settings....
Select Automatic proxy configuration URL, then paste the path copied from above. Be aware, the triple /// is intentional, and your path will be different from the one below - namely, YOUR_LINUX_USERNAME will be your actual linux username:
```
file:///home/YOUR_LINUX_USERNAME/proxy.pac
```
Select the box Proxy DNS when using SOCKS v5.
Click OK.
Restart Firefox.
Test that Firefox can resolve .onion URLs by visiting Start9's Tor website: http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion.

Windows

Ensure you have completed the steps under All Platforms.
You need a Proxy Auto Config file to inform Firefox how to resolve .onion URLs. Click here to get the one offered by Start9. Save it somewhere you will not delete it, and remember where you save it. For example:
```
C:\Program Files\Tor Browser\proxy.pac
```
In the main hamburger menu, click "Settings".
Using the search bar, enter proxy, then select Settings....
Select the box Automatic proxy configuration URL, then paste in the path to your PAC file from earlier, prefixed with file:// and with all backslashes (\) replaced by forward slashes (/). For example:
```
file://C:/Program Files/Tor Browser/proxy.pac
```
Select the box Proxy DNS when using SOCKS v5.
Click OK.
Restart Firefox.
Test that Firefox can resolve .onion URLs by visiting Start9's Tor website: http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion.

Android/Graphene

Ensure you have completed the steps under All Platforms.
You need a Proxy Auto Config file to inform Firefox how to resolve .onion URLs. Click here to get the one offered by Start9.
Search for network.proxy.autoconfig_url, and set the value to file:///storage/emulated/0/Download/proxy.pac. This is the default location of a the proxy.pac file downloaded above, although your path may vary.
Search for network.proxy.type into the search bar, and set the value to 2:
Search for network.proxy.socks_remote_dns, and set the value to true.
Search for network.http.referer.hideOnionSource and set the value to true
(GrapheneOS users only): Head to Settings -> Apps -> Firefox Beta -> Permissions -> Photos and videos -> Configure Storage Scopes -> ADD FILE, then navigate to where you placed the proxy.pac file.
Test that Firefox can resolve .onion URLs by visiting Start9's Tor website: http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion.

Thunderbird Guides

Trusting Your Root CA

Ensure you have already trusted your Root CA.
In the Thunderbird hamburger menu, click Settings.
Using the search bar, enter config, then select Config Editor....
Using the new search bar, search for security.enterprise_roots.enabled, and set the value to true.

Enabling Tor

Mac

Once you have configured Mac for Tor, no additional steps are required.

Linux

Ensure you have already configured Linux for Tor.
You need a Proxy Auto Config file to inform Firefox how to resolve .onion URLs. You can get Start9's standard file from a terminal, by using the following command:
```
sudo wget -P ~/ https://start9.com/assets/proxy.pac
```
Determine the full path of proxy.pac, which we will use later, by executing the following command in the terminal, and copying its output to your clipboard:
```
echo file://$HOME/proxy.pac
```
In the Thunderbird hamburger menu, click Settings.
Using the search bar, enter proxy, then select Settings....
Select Automatic proxy configuration URL, then paste the path copied from above. Be aware, the triple /// is intentional, and your path will be different from the one below - namely, YOUR_LINUX_USERNAME will be your actual linux username:
```
file:///home/YOUR_LINUX_USERNAME/proxy.pac
```

Windows

Ensure you have already configured Windows for Tor.
You need a Proxy Auto Config file to inform Firefox how to resolve .onion URLs. Click here to get the one offered by Start9. Save it somewhere you will not delete it, and remember where you save it. For example:
```
C:\Program Files\Tor Browser\proxy.pac
```
In the Thunderbird hamburger menu, click Settings.
Using the search bar, enter proxy, then select Settings....
Select the box Automatic proxy configuration URL, then paste in the path to your PAC file from earlier, prefixed with file:// and with all backslashes (\) replaced by forward slashes (/). For example:
```
file://C:/Program Files/Tor Browser/proxy.pac
```

Getting SMTP Credentials

There are several StartOS services that are capable of sending emails, such as BTCPay Server, Ghost, Gitea, Nextcloud, Synapse, and Vaultwarden, using third party email (SMTP) servers. The guides below are for using Gmail or Amazon SES for SMTP, but you may also use another third party provider of your choice.

Gmail

Access your Google 2-step verification settings: https://myaccount.google.com/signinoptions/two-step-verification.
Enable 2-Step verification if not already.
Under "App Passwords" (bottom), add a new App Password.
Choose a name for the new App Password. You may call it anything, such as "SMTP", then click "Create".
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".
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:

Parameter Value

Host smtp.gmail.com

Port 587

Encryption TLS

Username your-username@gmail.com

Password your App Password (form above)

Parameter	Value
Host	smtp.gmail.com
Port	587
Encryption	TLS
Username	your-username@gmail.com
Password	your App Password (form above)

Amazon SES

Refer to the Amazon SES docs.

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.

Raspberry Pi

Simply re-flash the microSD card.


When performing initial setup, be certain to select `Recover > Use Existing Drive`.

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

All Other Devices

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


- When installing StartOS, be sure to select "Re-install OS, preserving data".

- When performing initial setup (after installing StartOS), be certain to select `Recover > Use Existing Drive`.

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

Upgrading Your Raspberry Pi

Follow this guide to upgrade from a Raspberry Pi StartOS server to a Server One, Server Pure, or similar device.

From a Pi with External Drive

Use this section if your current StartOS Raspberry Pi uses an external drive over USB.

Stop every service on your Raspberry Pi server.
Shutdown your Raspberry Pi server and disconnect from power.
Connect your new server to power and ethernet.
Visit http://start.local on any computer on the same LAN.
Connect your previous storage drive to any USB-3 or USB-C port on your new server.
Select "Recover".
Select "Transfer".
On the "Transfer" screen, select the previous external storage drive.
On the "Select Storage Drive" screen, select your new storage drive. This is the internal drive of the new server.
Create a password for the new server. It can be the same as before.
Your data will now transfer. This can take minutes to hours, depending on how much data you have.
If you intend to re-purpose the Raspberry Pi as another StartOS server, be sure to first re-flash the microSD, then perform a fresh setup, which will wipe the SSD in the process. It is a good idea to wipe the SSD separately beforehand, just in case.
```
_Do not_ power on the Raspberry Pi until you have successfully re-flashed the microSD. If you power it on as-is, it can cause serious problems, including loss of funds if you are running a lightning node.
```

From 2022 Embassy One (NASPi case)

Naspi

Get a high quality USB-A to USB-A cable.
Power down the old server, then pull out the micro SD card.
Disconnect the USB adapter.
Connect one side of the USB-A cable to the lowest blue USB port on the old server, then the other side to a blue USB port on your new server.
Power on the old server
The two servers are now tethered together, and the NASPi is now powered on.
Connect your new server to power and ethernet if not already and also power on.
Visit http://start.local on any computer on the same LAN.
Select "Recover".
Select "Transfer".
On the "Transfer" screen, Select the NASPi storage drive.
On the "Select Storage Drive" screen, select your new storage drive. This is the internal drive of the new server.
Create a password for the new server. It can be the same as before.
Your data will now transfer. This can take minutes to hours, depending on how much data you have.

If you intend to re-purpose the NASPi as another StartOS server, be sure to first reflash the microSD, then perform a fresh setup, which will wipe the SSD in the process.


_Do not_ re-insert and power on the Raspberry Pi until you have successfully [re-flashed](../flashing-guides/startos/) the microSD. If you power it on with an unflashed microSD inserted, it can cause serious problems, including loss of funds if you are running a lightning node.

Introduction

StartOS is a Server OS. It is a Linux distro that is optimized for administering servers. Mac, Windows, iOS, Android, and other Linux distros, such as Debian and Ubuntu, are optimized for administering clients, such as phones or laptops. Using these operating systems to administer a server requires "popping the hood" and using the command line. Server administration involves compiling software, permissioning file systems, editing configuration files, managing dependencies, configuring network interfaces, generating certificates, monitoring health, creating backups, etc etc. It is a serious undertaking that requires significant time and expertise. For developers and system administrators, StartOS provides huge time savings over traditional Linux workflows. For everyone else, it makes administering a server possible.

The StartOS graphical interface is a private website, accessible from a local monitor or remote web browser. Through it, users can discover, download, install, configure, monitor, back up, and generally manage any variety of self-hosted, open-source software.

What makes this experience possible is a unique package format that permits services/apps/nodes to take advantage of StartOS APIs. In its most basic form, a package is just a thin metadata wrapper around a service that allows it to be discovered, installed, and run on StartOS. Beyond that, StartOS APIs grant developers an incredible degree of creative capacity to define the end-user experience for their service. Developers can:

display instructions and tool tips
present alerts and warnings under certain conditions
run arbitrary code on install, update, and uninstall
represent configuration files as validated forms with all varieties of form inputs
define command line scripts and commands that present as buttons with optional inputs
write health checks that run on an interval and are optionally displayed
automatically install and configure dependencies
maintain state and optionally expose particular values to users or dependent services
grant users flexible networking options such as LAN (.local + IP/port), Tor (.onion), and clearnet
offer one-click, encrypted backups of targeted data
and more...

In the next section, we will explore the StartOS APIs and how to access them using type safe Start-SDK.

Environment Setup

StartOS server

You will need a StartOS server to test your package. Follow the flashing guide to install StartOS on a physical device or VM.

start-cli

start-cli is needed to interact with StartOS from the command line.

Once installed, run

start-cli init

This will generate a .startos directory inside your home directory. This directory will contain a newly-generated developer.key.pem, used to sign packages, as well as a default config.yaml, which can be edited to customize and streamline your developer experience.

NodeJS

NodeJS is needed to compile the Typescript in your StartOS package.

Make

Make is used streamline builds and produce an s9pk.

Docker

Docker is needed to convert the docker image to a StartOS image.

Project Structure

/
├── assets/ (optional)
├── startos/
├── .gitignore
├── Dockerfile (optional)
├── icon.svg
├── instructions.md
├── LICENSE
├── Makefile
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json

.gitignore, Makefile, package-lock.json, package.json, and tsconfig.json

These are boilerplate files that need not be edited, except in special circumstances.

Dockerfile (optional)

It is recommended to pull an existing Docker image as shown in Hello World. If necessary, you can define a custom image using this Dockerfile.

icon.svg

This is the icon for your package. In most cases, it will be the upstream service icon. Maximum file size is 40 KiB. Supported extensions are .svg, .png, .jpg, and .webp.

instructions.md

This is your package instructions.

LICENSE

This is the software license for your package. In most cases, it will be the upstream license. If your package contains multiple upstream services with different licenses, you should select the more restrictive license.

README.md

This is largely boilerplate. Update as needed for your service, including replacing references to Hello World/Moon.

assets/ (optional)

Use the assets/ directory to package arbitrary files into your package. For example, an AI service may want to include a default LLM.

startos/

startos/
├── actions/
├── config/
├── dependencies/
├── migrations/
├── backup.ts
├── index.ts
├── init.ts
├── interfaces.ts
├── main.ts
├── manifest.ts
├── properties.ts
├── sdk.ts
├── store.ts
└── utils.ts

The startos/ directory is where you take advantage of the StartOS SDK and APIs.

backups.ts

setupBackups() is where you define what volumes to back up as well as what directories or files to exclude from backups.

index.ts

This file is just plumbing, used for exporting package functions to StartOS.

init.ts

setupInstall(): arbitrary code to run when the package is freshly installed. In this function, it is common to assign directory permissions or enter default values to the Store.
setupUninstall(): arbitrary code to run on package uninstall. It is most commonly used to undo changes made to dependency configs.

interfaces.ts

setupInterfaces() is where you define the service interfaces and determine how they are exposed. This function will execute on service install, update, and config save. It takes the user's config input as an argument, which will be null for install and update.

main.ts

setupMain() is where you define the daemons that define your service's runtime. Each daemon comes with a built-in health check that can optionally be displayed to the user. You can also use setupMain() to define arbitrary health checks in addition to those accompanying a daemon. A common use case for additional health checks is tracking and displaying a sync percentage.

manifest.ts

setupManifest() is where you define static metadata about the service, such as ID, name, description, release notes, helpful links, volumes, (software) images, hardware requirements, alerts, and dependencies.

properties.ts

setupProperties() is where you determine which values from the Store and underlying service to expose in the UI in Properties. Properties can imbued with metadata, such as whether or not to mask the value, or to display buttons for copying to clipboard or showing a QR code.

sdk.ts

This file is plumbing, used to imbue the generic Start SDK with package-specific type information defined in manifest.ts and store.ts. The exported SDK is what should be used through the startos/ directory. It is a custom SDK just for this package.

store.ts

The Store is for persisting arbitrary data that are not persisted by the service itself. The three most common use cases of the Store are:

Credentials for end user.
Credentials for dependent services.
Temporary state to be inspected at runtime, such as startup flags.
Metadata that cannot be retrieved or derived from the service itself, to be displayed in Properties.

setupExposeStore() is where you determine which values from the Store to expose to other services running on StartOS. Values not explicitly exposed here will be kept private.

utils.ts

This file is for defining constants and functions specific to your package that are used throughout the code base. Many packages will not make use of this file.

actions/

actions/
├── index.ts
├── action1.ts
└── action2.ts

Actions are predefined scripts or commands that present as buttons with optional inputs to end users. For example, a resetPassword action might use a service's command line interface to make changes to the file system, generate a new password, and save it to the package vault. The user experiences this as a button, perhaps with an input to optionally accept a user-provided password.

Each action receives its own file and is also passed into setupActions() in actions/index.ts

config/

config/
├── index.ts
├── read.ts.ts
├── save.ts
└── spec.ts

The config/ directory is where you define config options to expose, how to save and retrieve config values from the filesystem, and any side effects of configuration. Config presents in the UI as a simple, validated form.

read.ts

setupConfigRead() is where you describe how config values are retrieved from the file system. For example, you will read and parse one or more config files used by the service in order to present these options to the user.

save.ts

setupConfigSave() is where you describe how config values are saved to the file system and any associated side effects. For example, you will save form values to one or more underlying config files used by the service, or to the Store.

spec.ts

setupConfigSpec() is where you define the form that will display to the user. Forms may contain text inputs, number inputs, drop-downs, toggles, datetime selectors, and many other helpful UI elements and validations.

dependencies/

dependencies/
├── dependencyConfig/
└── dependencies.ts

The dependencies/ directory is used if your service depends on another StartOS service. If your service has no dependencies, you can ignore this directory.

dependencies.ts

setupDependencies() is where you define the services that your service requires, if any, and which states and versions they must be. This function will execute on service install, update, and config save. It takes the user's config input as an argument, which will be null for install and update.

dependencyConfig/

dependencyConfig/
├── index.ts
├── dependency1.ts
└── dependency2.ts

The dependencyConfig/ directory is used to create a unique file for each dependency whose config you intend to edit. Each dependency config is then passed into setupDependencyConfig() in index.ts.

file-models/

file-models/
├── config1.yaml.ts
└── config2.json.ts

In file-models/, create separate .ts files for each config file (.json, .toml, .yaml, .config) used by the upstream service. These .ts files add type safety to the upstream config files and provide a simple means of reading and writing them throughout the package codebase.

migrations/

migrations/
├── index.ts
├── v1_0_3_2.ts
└── v1_0_2_0.ts

In the migrations/ directory, you will create a new file for each package version that requires package data to be migrated. Note: service data if often be migrated by the service itself; migrations are for migrating data that is not migrated by the upstream service. Each migration is then passed into setupMigrations() in migrations/index.ts.

Quick Start

Environment Setup

Ensure you have completed every step of environment setup.

Generate your Package Repository

Select a template:
- Use Hello World if your service does not depend on another service.
- Use Hello Moon if your service depends on at least one other service.
Click Use this template > Create new repository. You must be signed into Github to see this button.
Name your repository. The name should be [service-name]-startos. For example, NextCloud is nextcloud-startos and Lightning Terminal is lightning-terminal-startos.
For the repository description, enter "StartOS package for [Service Name]".
Make sure the repository is Public.
Click "Create Repository".

Clone your Package Repository

From the command line of your local work machine, run the following commands:

git clone [your-repository-url]

cd [repository-name]

npm i

Build the s9pk

make

Install the s9pk

From the CLI

start-cli install -h <host> -s <path-to-s9pk>

You can eliminate the -h argument by hard-coding the host in ~/.startos/config.yaml.

From the GUI

From the GUI of your StartOS server, go to System > Sideload, upload the .s9pk file, and click "Install".

Common Issues

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".

Confirm that the server is plugged into power and Ethernet
Confirm your phone/computer is not connected to a "Guest" network
Confirm you are not using the Tor Browser.
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
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.
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

First, try :ref:these step <setup-troubleshoot>. In none resolve the issue, continue below.
Hard refresh the browser:
- Linux/Windows: ctrl+shift+R
- macOS Firefox: cmd+shift+R
- macOS Safari: cmd+option+E, then cmd+R
Make sure you have successfully followed the :ref:connecting-lan instructions for your device.
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.
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>
Try connecting using your server's IP address or Tor 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.
Try connecting using a different browser on the same device. If this works, it means you need to clear cache on your current browser.
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.
Try visiting start.local. Your server may be in diagnostic mode.
Try restarting your router.
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

Tor can be slow and unreliable. Often, the solution to poor connectivity is just to wait an hour and try again.
Try connecting using the official Tor Browser. If this works, it means the issue is with (1) your current browser or native app, (2) the Tor daemon running on your phone/laptop. Try clearing cache and restarting things.
Try connecting to your server using its "custom-address.local" URL or its IP address. If this works, it means the issue is specific to Tor on your server. Check out your Tor logs (System -> Tor Logs). If you see errors, such as Tor stuck bootstrapping, navigate to System -> Experimental Features -> Reset Tor.

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:

Check your local Internet connection.
Hard refresh the browser.
Clear the browser cache/history.
Try using a different address for your server. For example, if you are using your .onion address, try using your .local or IP address instead. If you are using your .local address, try using your .onion or IP address.
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.
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.
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.

Contact

Please visit https://start9.com/contact for contact information.