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

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

Your server does not need to be in the same room as you. You do not need to access it physically. You do not need to see it or touch it for it to serve a web interface on your network. It can live with your router with a direct ethernet connection.

However, WiFi can sometimes be necessary, such as in a school or office setting where Ethernet connections are not available.

Your server may or may not come with a built-in WiFi adapter.

No WiFi adapter

If your device does not have a WiFi adapter, 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.

WiFi adapter built-in

Connecting to a WiFi network in StartOS

You should have already set up your server in a location with ethernet and be able to log in from a client machine.

Under System > WiFi select your country (this is for limiting to local civilian radio frequencies)
Choose your WiFi network
Enter your WiFi password and click Save and Connect

That's it!


You should use either wired ethernet or WiFi to connect your server, it isn't recommended that you use both at the same time.


WiFi is consistantly less easy to work with than wired ethernet and is not a recommended solution. Common issues include:

- WiFi networks set up on routers being seperate networks (i.e. "guest" networks or a different subnet)
- Dropped connections confused with the server being down
- Issues with routers when wired ethernet and WiFi are both connected

These can make it difficult to troubleshoot when contacting support.

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

Mac
Linux
Windows

Contents

Specter Desktop

Instructions

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

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.


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

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 an 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 an 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`, or of course, the IP address and port.

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 with Alby Hub

Alby Hub

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.
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 Browser Extension

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 are looking for Alby Hub, this is not it. To use [Alby Hub](../lnd/alby-hub.md) you must instead run [LND](../lnd/).
This is NOT the guide for setting up **Alby Hub** this is for a direct connection to LND. If you'd like to connect via Alby Hub instead (recommended), click [here].

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 expand Services -> Core Lightning -> Config -> Advanced -> Plugins, then confirm the CLNRest is toggled on.
Now open Services -> Core Lightning -> Properties.
Tap the QR code icon for CLNRest Quick Connect to display the QR code.
In Zeus, tap "ADVANCED SET-UP", followed by "Connect a node", and finally click the 'scan' icon in the top right to scan the qr code from the previous step.
Click SAVE NODE CONFIG


If you already have other nodes configured in Zeus, Click the 'Node' icon in the top right -> 'plus' icon -> 'scan' icon . Then scan the QR code, and tap "SAVE NODE CONFIG".

![LND Actions](../assets/connect-zeus-cln-addnode.png)

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

Alby Hub

Alby Hub is the open-source, self-custodial Lightning wallet that puts you in control. Connect to your LND or to an integrated node, it's more than just a wallet—it's your gateway to Bitcoin. Manage channels, run apps, and take charge of your funds, all through one sleek, user-friendly interface. Empower your Bitcoin journey with simplicity and sovereignty.

Usage options

LND already on your server: This option tells Alby Hub to use the LND node installed on this StartOS server. It is the more sovereign and secure option, allowing full control over your node.
Alby Hub embedded light node: This option tells Alby Hub to use its own, built-in LDK light node. This option is convenient but offers less control over your node.

Getting Started

Once you've made your decision on how to use Alby Hub, install it from the marketplace.
Click Configure
And select your prefered usage type…
Hit Save and then start the service.

LND on your server

You will be running Alby Hub on your server, and it will be connecting to LND on your server.

Launch the Alby Hub UI for the first time.
Cycle through the introduction to arrive at the setup screen.
Click on the Get Started (LND) button.
Enter a password and keep it somewhere safe, like in your personal :ref:Vaultwarden<vaultwarden-service> instance.

Select whether you will create an Alby account now or later (i.e. not at all).


An Alby Account gives your hub a lightning address, Nostr address and zaps, email notifications, fiat topups, priority support, automatic channel backups, access to podcasting apps & more. If you choose not to create an account, your setup will be complete.

Setup

Connect your Alby account by clicking to request an authorization code. This will open a new tab.
If you have a pre-existing Alby account your can log in here, otherwise you can sign up.
You will get an authorization code to add back into the previous tab hosted on your server. Paste that auth code and hit Submit.
Your self-hosted Alby Hub is ready and connected to your self-hosted LND!

Alby Hub embedded light node

You will be running Alb Hub on your server, and it will be connecting to LDK light node on your server. (The Alby Hub service will have a self-contained node, rather than connecting to an external instance of the LND servic. Keep this in mind when considering backups!)

Launch the Alby Hub UI for the first time.
Cycle through the introduction to arrive at the setup screen.
Click on the Get Started (LDK) button.
Enter a password and keep it somewhere safe, like in your personal Vaultwarden.

Select whether you will create an Alby account now or later (i.e. not at all).


An Alby Account gives your hub a lightning address, Nostr address and zaps, email notifications, fiat topups, priority support, automatic channel backups, access to podcasting apps & more. If you choose not to create an account, your setup will be complete.

Setup

Connect your Alby account by clicking to request an authorization code. This will open a new tab.
If you have a pre-existing Alby account your can log in here, otherwise you can sign up.
You will get an authorization code to add back into the previous tab hosted on your server. Paste that auth code and hit Submit.
Your self-hosted Alby Hub is ready and connected to your self-hosted LDK light node!

Connecting Apps

Two of the more important apps you may want to install are:

Alby Web (a simple wallet interface that connects to your Alby Hub and can be saved as a PWA (app-like) on your phone)
Alby Extension (companion for accessing Bitcoin and Nostr apps, payments across the globe and passwordless logins)

Alby Web

If you have connected your Alby Hub to an Alby account during setup, Alby Web will appear connected by default. (If you have not, you can go to Settings > Alby Account to add an account).

This wallet interface allows you to interact with your Alby Hub-connected LND over clearnet with a easy to use interface.

Alby Extension

Visit the App Store from your Alby Hub.
Click Connect.

Give the connection to your Alby Extenions a name and decide what access and limitations you give it.


The settings are fairly self explanatory. Typically you'll want your browser extension to be able to have full access to your lightning node and funds since you will be the only one using it and will want to both make and receive payments. Payments you make have to be confirmed and authorized through the extension, but if you are worried about overspending, the advanced **Budget** option sets monthly limits on how much can be spent. This is useful in case you get carried away zapping or if you ever misread a payment request that's higher than you expect.

Alby Extension Setup

Download the extension for your browser if you don't have it already. Install it. Open it if you do already have it installed.
If the extenstion is installed on the same browser, click the newly appeared icon in the menu bar while on the screen above. Click to connect.
You can now spend sats and generate invoices from your browser! Test it out by running your own noStrudel instance.

Resources and Guides

Alby have extensive users guides available here. Learn how to connect other apps and use the advanced features available to those who set up Alby accounts.

BTC Sessions has created an Alby Hub tutorial here. While this focuses on the cloud hosted variety of Alby Hub, the interface and features are the same, and the Start9 hosted variety gets a mention in the last segment.

Connecting to LND

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

Alby Hub

Alby Hub

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 Browser Extension


This is NOT the guide for setting up **Alby Hub** this is for a direct connection to LND. If you'd like to connect via Alby Hub instead (recommended), click [here](./alby-hub.md).

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.

LND via Lightning Node Connect (LNC) - Alby Browser Extension

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.

Navigate to Services -> LNbits, click Launch UI, and authenticate with your 'Superuser Username' and 'Superuser Default Password' found in LNbits -> Properties:

After logging into your LNbits account 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.

Navigate to Services -> LNbits, click Launch UI, and authenticate with your 'Superuser Username' and 'Superuser Default Password' found in LNbits -> Properties:

After logging into your LNbits account 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.

Navigate to Services -> LNbits, click Launch UI, and authenticate with your 'Superuser Username' and 'Superuser Default Password' found in LNbits -> Properties:

After logging into your LNbits account 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.

Navigate to Services -> LNbits, click Launch UI, and authenticate with your 'Superuser Username' and 'Superuser Default Password' found in LNbits -> Properties:

After logging into your LNbits account 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 Browser Extension 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.

Matrix

Synapse

With registrations disabled, the only way to create an account on your Server is through the Admin Portal. The Admin Portal is the preferred method for creating an account.

In your Start9 UI, under Services > Synapse, click "Launch UI"
Log in with your Admin Username and Password (located in Properties). For "Homeserver URL", do not enter your Homeserver address. Instead, enter your Admin Portal URL.
```
This is the URL currently showing in your browser URL bar, excluding the path. e.g. `https://adjective-noun.local:port` or `http://exampleaddress.onion`
```
In the "Users" tab, you will notice the admin user already created.
In the "Users" tab, click "+ Create"
Choose a User-ID, Displayname, and Password for your account. Optionally enter an email address under the 3PIDs section. It is not recommended to make this user a Server Administrator, as it is best to limit admin access.

Nextcloud

These guides will help you to setup tools to connect or interact with Nextcloud.

Nexcloud Device Setup - Set up your client device to connect to Nextcloud
Nextcloud Apps & Integrations - Setup and use Nextcloud and 3rd party apps

Nextcloud Device Setup

Connection guides by Device. This will guide you through initial setup and syncing configurations.

Nextcloud - Linux

Initial Config

For the best experience, it is recommended to set up your Nextcloud devices on LAN with a designated IP address and port. This setup allows you to sync files, calendars, and contacts while away from home using a Router VPN.

Once configured, you can also use Tor for remote syncing. However, keep in mind that transferring large files may fail or take a considerable amount of time. Therefore, it is advisable to use remote syncing primarily for low-bandwidth activities, such as syncing calendars, contacts, tasks, and notes. Streaming music is also possible.


When using remote connections, be mindful of any data caps on your cellular plan. You may need to limit bandwidth usage by disconnecting from your Router VPN server or Tor when using cellular data.

Desktop Integrations

Many Linux distributions ship with a Desktop Environment (DE) that supports Nextcloud account integration directly for use with their built-in calendars and other applications. It is recommended to try these first for the best possible experience with your particular flavor of Linux.

You will first need to trust your Root CA.

The following desktop environments support integrated account syncing, including Nextcloud:

Gnome (Ubuntu default)
Cinnamon (Linux Mint default)
KDE
Budgie

The following guide uses Ubuntu as an example.

Open settings app.
Go to Online Accounts and click on Nextcloud.
Paste in the server path from StartOS > Nextcloud > Interfaces and the username and password from StartOS > Nextcloud > Properties, and click Connect.
Choose which services you want to integrate and close Nextcloud Account window.
Open the file manager, and you should see your NextCloud account in the side panel.

To setup other Linux distributions, check out this Linuxhint guide and our Nextcloud Master Thread. Please share your feedback - it is very valuable to our community!

Standalone Clients

For those that prefer to use a desktop client or your desktop environment does not support account integrations.


The desktop version of NextCloud doesn't have much of a user interface.  Once installed, it solely lives in the your system tray or navigation bar.  You can click on this icon to access the app.

File Syncing - Nextcloud Desktop

This is Nextcloud's official client application for file syncing and account management. It is available in your favorite package manager (usually as nextcloud). You can also see this full list of available packages. or you can get the latest version as an AppImage from the Download for Desktop section of Nextcloud's website.

LAN/Router VPN Setup

Make sure you have first set up your trusted Root CA.

Open the client and click Log In to your Nextcloud.
From your server's Nextcloud service page, go to Interfaces and copy the IP address and port, or .local and port.
Enter your IP address and port, or .local and port under Server Address and click Next.
This will launch a page in your web browser, click Log In and then Grant access to link the desktop client. You can close this browser window afterwards.
Next, configure the local directory that you want to sync with Nextcloud. You may use the default or change it, and edit the sync settings to desired. When satisfied, click Connect.
Files will begin to sync immediately and you will see a green check when this is complete.
That's it! From this desktop client you will recieve notifications, control accounts and syncing, and quickly access your Apps' WebUI pages

Tor Setup

You will first need to have the Tor daemon running.

On your desktop application. Click the account avatar in the top left > Settings, then click Network. Choose Specify proxy manually as and SOCKS5 proxy. Enter 127.0.0.1 for the Host and 9050 for the port.
Close the Settings screen and click the account in the top left again, then Add Account.
On the following screen, click Log in your Nextcloud, then enter your Nextcloud Tor server address, which you can copy from the Nextcloud page on your StartOS > Interfaces > Tor. This should start with https:// and end with .onion.
This will launch your browser and prompt you to log in to your account. Log in and then grant access as we did for LAN.
That's it! You can set up some select folders for remote sync, but for large files, it is best to sync on LAN only. Check your connection by clicking the newly created account in the client app.

Nextcloud - Mac OS

Initial Config


When using remote connections, be mindful of any data caps on your cellular plan. You may need to limit bandwidth usage by disconnecting from your Router VPN server or Tor when using cellular data.

Native Desktop Integration

The smoothest experience will be using direct account integration with your Mac. First head into the top-righthand menu of your Nextcloud's WebUI and click "Apps," then search for and install the Calendar and/or Contacts Apps if you don't have them already (these are installed by default on the latest Nextcloud for StartOS).The steps below are adapted from the Official Nextcloud guide.

Open the "System Settings" and select "Internet Accounts," click "Add Account." and then select "Add Other Account".
Select CalDAV for calendar setup or CardDAV for contacts setup. If you want to do both, you will need to return to this step after finishing the setup of the first.
```
You will need to perform 2 individual setups, one for Calendar and one for Contacts.
```
Select "Advanced" from the "Account Type" dropdown menu and fill in the following fields.
- Username - The default user is "admin," but this is your user within Nextcloud, so be sure it is the correct user if you have more than one.
- Password - In your Nextcloud WebUI, visit the top-right-hand menu and select "Personal Settings" -> "Security." At the bottom, under Devices & Sessions, create a new app password with a name of your choice, such as "MacCalDAV." Then, copy the resulting password into your Mac's account configuration.
- Server Address - copy your LAN address from the "Interfaces" section of your Nextcloud service page then paste.
- Server Path - You can find the complete path in Nextcloud by navigating to Calendar settings and copying the iOS/macOS CalDav address. For setting up contacts (CardDav), use only the path without the hostname.
  
  Example:
  
  /remote.php/dav/principals/users/admin/
- Port - Set port to 443.

Standalone Clients

The desktop version of NextCloud doesn't have much of a user interface.  Once installed, it solely lives in the top right hand corner of the Mac desktop in the navbar, near the WiFi icon.  When it's synced, the icon turns into a checkmark with a circle around it.

File Syncing - Nextcloud Desktop

This is Nextcloud's official client application for file syncing and account management. The latest version of the official Nextcloud client is available on their download page.

LAN/Router VPN Setup

Make sure you have first set up LAN access. Then do the following:

Open the client and click "Log In".
From your server's Nextcloud Service page, go to "Interfaces" and copy the LAN address.
Enter your LAN address under "Server Address" and click "Next".
This will launch a page in your web browser, click "Log In" and then "Grant access" to link the desktop client. You can close this browser window afterwards.
Next, configure the local directory that you want to sync with Nextcloud. You may use the default or change it, and edit the sync settings to desired. When satisfied, click "Connect".
Files will begin to sync immediately and you will see a green check when this is complete.
That's it! From this desktop client you will recieve notifications, control accounts and syncing, and quickly access your Apps' WebUI pages.

Tor Setup

You will first need to have the Tor daemon running.

To add an account, configure the network settings first. In your desktop application, go to your account in the top left, select Settings, then Network. Choose Specify proxy manually as and select SOCKS5 proxy. Enter 127.0.0.1 for the Host and 9050 for the Port.
Close the Settings screen and click the account in the top left again, then "Add Account".
On the following screen, click "Log in," then enter your Nextcloud Tor server address, which you can copy from Nextcloud -> Interfaces - Tor. This should start with http:// and end with .onion. Click Next.
This will launch your browser and prompt you to log in to your account. Log in and then grant access as we did for LAN.
That's it! You may wish to set up some select folders for remote sync, but for large files, it is best to sync on LAN only, so you can "Skip folders configuration" on the resulting screen if you wish. Check your connection by clicking the newly created account in the client app.

Nextcloud - Windows

Initial Config


When using remote connections, be mindful of any data caps on your cellular plan. You may need to limit bandwidth usage by disconnecting from your Router VPN server or Tor when using cellular data.

Native Desktop Integration

If you prefer to use Microsoft's integrated Calendar and Contacts apps with your Windows machine, you can integrate directly. First head into the top-righthand menu of your Nextcloud's WebUI and click "Apps," then search for and install the Calendar and/or Contacts Apps. The steps below are adapted from the Official Nextcloud guide.

Make sure you have first set up LAN access. Then do the following:

Launch the Windows Calendar app and click the gear icon (Settings), then select "Manage Accounts."
Select "Add Account" and choose "iCloud" (don't worry, it won't really be iCloud).
Enter an email, username and password. None of this information has to be valid and it will all be changed in the upcoming steps. Click "Sign In" (or "Done" in Win10).
In the "Manage Accounts" menu, click on the account just created and select "Change Settings," and then "Change mailbox sync settings" (at the bottom of the page).
Scroll to the bottom again and fill in the following fields (as desired):
- Calendar Server (CalDAV) - This link can be copy-pasted by clicking your Nextcloud Calendar app's "Calendar Settings" in the bottom-left, then "Copy primary CalDAV address" at the bottom of the expanded menu.
- Contacts Server (CardDAV) - This link can be copy-pasted by clicking your Nextcloud Contacts app's "Contacts Settings" in the bottom-left, then the kebab (3 dots) menu next to "Contacts," and finally "Copy Link" at the top of the resulting menu.
Click "Done."

You should now be able to sync your native Windows Contacts and/or Calendar apps with the associated Nextcloud apps.

Standalone Clients

File Syncing - Nextcloud Desktop

This is Nextcloud's official client application for file syncing and account management. The latest version of the official Nextcloud client is available on their download page.

LAN/Router VPN Setup

Make sure you have first set up LAN access. Then do the following:

Download the appropriate desktop client from https://nextcloud.com/install/#install-clients
Open the client and click "Log In"
From your server's Nextcloud Service page, go to "Interfaces" and copy the IP address and port, or .local and port.
Enter your LAN address under "Server Address" and click "Next"
You will be asked to Trust your server's certificate, which is safe to do as you generate and sign this during LAN Setup
Tick the box for "Trust this certificate anyway" and click "Next"
This will launch a page in your web browser, click "Log In" and then "Grant access" to link the desktop client. You can close this browser window afterwards
Next, configure the local directory that you want to sync with Nextcloud. You may use the default or change it, and edit the sync settings to desired. When satisfied, click "Connect"
Files will begin to sync immediately and you will see a green check when this is complete.
That's it! From this desktop client you will recieve notifications, control accounts and syncing, and quickly access your Apps' WebUI pages

Tor Setup

You will first need to have the Tor daemon running.

On your desktop application, click the account in the top left -> Settings, then in Settings, click Network, then "Specify proxy manually as" and "SOCKS5 proxy." Enter "127.0.0.1" for the Host and "9050" for the port.
Close the Settings screen and click the account in the top left again, then "Add Account."
On the following screen, click "Log in," then enter your Nextcloud Tor server address, which you can copy from Nextcloud -> Interfaces - Tor. This should start with http:// and end with .onion. Click Next.
This will launch your browser and prompt you to log in to your account. Log in and then grant access as we did for LAN.
That's it! You may wish to set up some select folders for remote sync, but for large files, it is best to sync on LAN only, so you can "Skip folders configuration" on the resulting screen if you wish. Check your connection by clicking the newly created account in the client app.

Nextcloud - Android

Initial Config


When using remote connections, be mindful of any data caps on your cellular plan. You may need to limit bandwidth usage by disconnecting from your Router VPN server or Tor when using cellular data.

Nextcloud App

The latest version of the official Nextcloud client is available on their download page. This is for file syncing and account management.

LAN/Router VPN Setup

Make sure you have first set up LAN access.

Open Nextcloud via your server's Services -> Nextcloud -> Launch UI
Log in and select the top right icon -> Personal Settings:
Select the hamburger (3 lines) menu:
Select Security:
Under Devices & sessions, give this Nextcloud mobile app a session name, such as "Mobile" and tap Create new app password:
Tap Show QR code for mobile apps:
The new session's QR code will be displayed:
Download and install the appropriate desktop client for your Android device from https://nextcloud.com/install/#install-clients
Open the Nextcloud client on your Android device and tap "Log in"
Tap the QR code icon:
Scan the QR code presented in Step 7.


Here you may see an error about the Nextcloud app being unable to find the host that was decoded from the QR code:

![Nextcloud mobile app error Could not find host](../assets/pitfall1-could_not_connect_to_host-wifi-mdns-orbot.png)

If you see this message, you may be on an Android version that does not support mDNS .local name resolution (it is available on Android 13+ and some builds of Android 12, but not all.  The other possibility is that your WiFi network is not properly "bridged" with the ethernet network that your Start9 server is on, or you lack WiFi connectivity to your network in general.


Alternatively, you may see a warning about an untrusted certificate:

![Nextcloud mobile app QR Code button](../assets/pitfall2-untrusted_cert.png)

In this case, make sure you have [added your server's CA certificate to the Android trust store](/device-guides/android/ca.md) as noted at the top of the `LAN Setup` section of this guide, close the Nextcloud mobile app and try again.  Otherwise, proceed to the next step.

Android may ask you about Storage permissions. Grant "Full access":
Next, configure the local directory that you want to sync with Nextcloud. You may use the default or change it, and edit the sync settings to desired. When satisfied, tap "Connect"
Files will begin to sync immediately and you will see a green check when this is complete.
That's it! From this desktop client you will recieve notifications, control accounts and syncing, and quickly access your Apps' WebUI pages

Tor Setup

You will first need to have Orbot running.

First, add Nextcloud to your Orbot apps list.
Tap the account in the top-right, then "Add Account."
On the following screen, tap "Log in," then enter your Nextcloud Tor server address, which you can copy from Nextcloud -> Interfaces - Tor. This should start with https:// and end with .onion. tap Next.
This will launch your browser and prompt you to log in to your account. Log in and then grant access as we did for LAN.
That's it! You may wish to set up some select folders for remote sync, but for large files, it is best to sync on LAN only, so you can "Skip folders configuration" on the resulting screen if you wish. Check your connection by tapping into the newly created account in the app.

Device Integration

In order to sync calendars and contacts with your Android device, follow the steps below, which are adapted from the Official Nextcloud guide. First head into the top-righthand menu of your Nextcloud's WebUI and click "Apps," then search for and install the Calendar and/or Contacts Apps.

Download the WebDAV sync management client DAVx5 from your app store of choice, such as F-Droid or the Play Store.
Add account:
- If you are on Android 12+ and already have the Nextcloud file-syncing app (recommended - guide above), then open it and enter the "Settings" menu from the top-lefthand hamburger (3 lines) menu. Then under the section titled, "More," tap "Sync Calendar & Contacts."
  - This will open Nextcloud's WebFlow login in a browser, where you will need to log in and "Grant Access" - you will then be returned to DAVx5
  - Set an account name when asked, then set "Contact Group Method" to "Groups are per-contact categories" - DAVx5 will close and Nextcloud will reappear.
  - Manually launch DAVx5 again and top on the account that was just created. Grant access to Calendars and Contacts when requested, and optionally tasks, if you added that feature in setup. Choose the address books and calendars you wish to sync and you're done!
- If you are NOT using the Nextcloud app already, then open DAVx5 and after going through the introduction (optionally selecting additional features), tap the "+" icon to add a new account, then select "Login with URL and user name," and fill in the following fields:
  - Base URL - Enter your Nextcloud WebDAV Base LAN URL (found in "Properties" in the Nextcloud service page).
  - User name - Your Nextcloud user (defaults are found in "Properties" on your Nextcloud service page)
  - Password - Your Nextcloud user's password (defaults are found in "Properties" on your Nextcloud service page)
  - If given the option, select "Groups are per-contact categories," then tap "Login." Select the data you want to sync, grant access for contacts, calendars, and optionally tasks if you added that feature in setup. That's it, you're done!
```
You may also wish to add the [ICSx5](https://icsx5.bitfire.at/) app, which allows subscription to remote WebCal or local iCal files (such as public event schedules, iCloud/Google calendars, etc).  It can be found in your favorite app store.
```

Nextcloud - iOS

Initial Config


When using remote connections, be mindful of any data caps on your cellular plan. You may need to limit bandwidth usage by disconnecting from your Router VPN server or Tor when using cellular data.

Standalone Client

The latest version of the official Nextcloud client is available on their download page.

LAN/ Setup

Make sure you have first set up LAN access.

Download the iOS Nextcloud client from App Store.
Open the client and tap "Log In".
From your server's Nextcloud Service page, go to "Interfaces" and copy the IP address and port, or .local and port.
Enter your LAN address under "Server Address" and tap "Next".
You will be shown the "Connect to your account" screen, and then click "Log In" and "Grant Access".
Next, you will be asked to enter the username and password, which can be found on the startOS Nextcloud Service page under the "Properties" tab.
The account access page will be displayed, tap "Grant access".
Files will begin syncing immediately, and you will see your username and account icon in the top left corner.
That's it! From this mobile client you can receive notifications, control accounts and syncing, and quickly access your apps' WebUI pages.

Tor Setup

You will first need to have the Tor daemon running.

Click the account in the top left again, then "Add Account."
On the following screen, click "Log in," then enter your Nextcloud Tor server address, which you can copy from Nextcloud -> Interfaces - Tor. This should start with https:// and end with .onion. Click Next.
This will launch your browser and prompt you to log in to your account. Log in and then grant access as we did for LAN.
That's it! You may wish to set up some select folders for remote sync, but for large files, it is best to sync on LAN only, so you can "Skip folders configuration" on the resulting screen if you wish. Check your connection by clicking the newly created account in the client app.

Device Integration

In order to sync calendars and contacts with your iOS device, follow the steps below, which are adapted from the Official Nextcloud guide.

First head into the top-righthand menu of your Nextcloud's WebUI and click "Apps," then search for and install the Calendar and/or Contacts Apps. Next folow guide for iOS.

nextcloud account settings

Open the "Settings" app on iOS device.


You will need to perform 2 individual setups, one for Calendar and one for Contacts.

Select "Calendar" (or "Contacts") -> "Accounts" -> "Add Account" -> "Other" -> "either CalDAV (for Calendar setup) or CardDAV (for Contacts setup)". Return to this step after completing one in order to add the other.

nextcloud account settings

Enter the following fields and tap "Next":

Server - Copy your URL from Nextcloud -> Calendar settings -> Copy iOS/macOS CalDav address. For setting up contacts/CardDav use the same path.
User name - The default user is "embassy" but this is your user within Nextcloud, so be sure it is the correct user if you have more than one.
Password - In your Nextcloud WebUI, visit the top-right-hand menu and select “Personal Settings” -> “Security.” At the bottom, under Devices & Sessions, create a new app password with a name of your choice, such as “iOSCalDAV.” Then, copy the resulting password into your iOS CalDAV account configuration.
Description - Anything to describe this account, such as "Nextcloud CalDAV".

nextcloud account settings

If you get a warning about verifying the server identity, it is safe to "Continue." Add the apps you want to use, such as Calendars, Contacts, and/or Reminders, then tap "Next".

That's it! Go back to step 2 above to set up your other account (CalDAV / CardDAV).

Nextcloud Apps & Integrations

Nextcloud Bookmarks

Nextcloud Bookmarks is software for sorting, tagging, searching, sharing, and (most importantly) syncing your browser's bookmarks via your server. First set up your client devices, so that Nextcloud will automatically keep your bookmarks synced.

Available for:

Web Interface
Mobile
- Android
Desktop Browsers
- Chrome
- Edge
- Firefox

NC App Setup

Begin by downloading Bookmarks from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Bookmarks." Click it to get started.
- At this point you can begin adding bookmarks directly into the app, or import them from a browser. These are always available by accessing your Nextcloud from your client devices.
- The real power here is in the ability to import or sync across devices. There are several clients that can accomplish this, which can be found on the NC Bookmarks Github Page. For our example, and the recommended option if you click "Sync with your browser" from the Bookmarks welcome page, is Floccus.
(Optional) In the "Settings" menu in the bottom-left, you may change the Nextcloud location in which to store your bookmarks. If you change this or create a new folder, be sure to reflect this change in Floccus below.

Browser & Mobile Setups

Floccus (Browser & Android)

Download the appropriate Floccus extension for your browser or app from the App Store, F-Droid, or Play Store.
Open the Floccus browser extension and click "+NEW ACCOUNT", select "Nextcloud Bookmarks", and then add your server address and login via Nextcloud.
(Optional) Edit the folder paths if changed above and select a local folder to save bookmarks to.
On the final setup page, use the defaults unless you are absolutely sure what you are doing. Click "Continue" and you're ready to sync!
```
Repeat this process for any additional devices or browsers that you'd like to keep in sync.
```

Nextcloud Calendar

Nextcloud Calendar is software for managing and syncing calendars, events, and tasks between your devices. First set up your client devices, so that Nextcloud will automatically keep your calendars synced.

Available for:

Web Interface
Mobile
- Android
- iOS
Desktop
- Linux
- Mac
- Windows

NC App Setup

On the latest Start9 Nextcloud service, Calendar is included by default. If coming from an older install, begin by downloading Calendar from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Calendar." Click it to get started.
- At this point you can begin using the Calendar right away in the web UI. All changes will be reflected in any currently synced client devices, or on any added in future.

Client Integrations

Client integrations can all be found in the initial setup guides for your device.

Nextcloud Contacts

Nextcloud Contacts is software for managing and syncing your contacts between your devices. First set up your client devices, so that Nextcloud will automatically keep your contacts synced.

Available for:

Web Interface
Mobile
- Android
- iOS
Desktop
- Linux
- Mac
- Windows

NC App Setup

On the latest Start9 Nextcloud service, Contacts is included by default. If coming from an older install, begin by downloading Contacts from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Contacts." There is also a quick access icon in the top-right. Click either to get started.
- At this point you can begin using your Contacts app right away in the WebUI. All changes will be reflected in any currently synced client devices, or on any added in future.

Client Integrations

Client integrations can all be found in the initial setup guides for your device.

Nextcloud Cookbook

Nextcloud Cookbook is software for viewing, syncing, and organizing recipes. First set up your client devices, so that Nextcloud will automatically keep your recipes synced.

Available for:

Web Interface
Mobile
- Android
- iOS

NC App Setup

Begin by downloading Cookbook from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Cookbook." Click it to get started.
You can now start adding recipes. Simply find a recipe online and copy the URL into the box on the left. In most cases, this will be translated into an easy-to-read recipe with ingredients and steps, and without all the distractions and junk included with most recipe pages.
```
Tag and categorize your recipes!  Basic settings are available in the bottom-left menu.
```

Mobile Setups

### Nextcloud Cookbook (Android / iOS)

There are 2 versions of this app available on Android, and one on iOS. Check this repository for details.

Go to your app store of choice and install the Nextcloud Cookbook app.
(Android connection) You can select a previously connected Nextcloud account, or scan an app-specific QR, created under Nextcloud's main menu -> Personal Settings -> Security
(iOS connection) You will be prompted to enter the following:
- Server URL - get this from your server's Services -> Nextcloud -> Interfaces (LAN is recommended)
- Username - get this from your server's Services -> Nextcloud -> Properties (admin is default)
- Password - get this from your server's Services -> Nextcloud -> Properties
```
You may need to enable "self-signed certificates" for LAN.  This is safe to do as you are the signer of the cert and owner of all involved hardware.
```
As soon as you connect and sync, you will see your Cookbook!

Nextcloud Files

Nextcloud Files is software for managing and syncing your data between your devices. In practice it functions similarly to the file explorer on your computer. Files also serves as the base storage on your server for all the other apps that may need to access your data, such as documents, multimedia, and syncing apps. This even includes data storage for other Start9 services on your server, such as Jellyfin and Start9 Pages.

Available for:

Web Interface
Mobile
- Android
- iOS
Desktop
- Linux
- Mac
- Windows

NC App Setup

You will find an icon in your top menu for "Files." Click here to get started.
- You can begin using your Files app right away in the web UI. All changes will be reflected in any currently synced client devices, or on any added in future.
```
Keep in mind that if you delete a file in one location, it may be deleted across all locations!!  Start with some test folders/files in order to understand how the syncing system works with your devices.
```

Client Integrations

Client integrations can all be found in the initial setup guides for your device.

Nextcloud Maps

Nextcloud Maps is software for viewing and managing your places. First set up your client devices, so that Nextcloud will automatically keep your maps synced.

Available for:

Web Interface

NC App Setup

Begin by downloading Maps from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Maps." Click it to get started.
You can now browse OpenStreetMap, get directions, create favorite locations, add photos, and share custom maps.
```
You can find the settings for Maps in the bottom-left
```


This is basic software at this time, havnig just reached 1.0, but features are planned by the developers for linking mobile devices for finding a lost or stolen device as well as fitness tracking and other modern location services.

Nextcloud Memories

Nextcloud Memories is software for viewing, managing, and organizing your photos. First set up your client devices, so that Nextcloud will automatically keep your photos synced.

Available for:

Web Interface
Mobile
- Android

NC App Setup

Begin by downloading Memories from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Memories." Click it to get started.

You will see an image that says "Click Here To Start" - click it and select your media directory.


You can find the settings for Memories under the top-right menu -> Administrative Settings -> Memories

Desktop & Mobile Setups

This is currently a webUI only application (though the Android app of the same name is in active development), but you can use the same clients as those supported by Nextcloud Photos.

Nextcloud Music

Nextcloud Music is software for organizing and playing your music as well as managing and streaming podcasts and internet radio. First set up your client devices, so that Nextcloud will automatically keep your music synced.

Available for:

Web Interface
Mobile
- Android
- iOS
- Garmin Watch
Desktop:
- Linux
- Mac
- Windows

NC App Setup

Begin by downloading Music from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Music." Click it to get started.
You can now play existing music from your Nextcloud Files, or add an internet radio station or podcast feed!
```
You can set the media directory path in the 'Settings' menu on the bottom-left
```

Desktop & Mobile Setups

Nextcloud Music can be used by clients that support Ampache or Subsonic. See all the options in the 'Settings' menu on the bottom-left, or see the Ampache client list or the Subsonic client list.

Nextcloud News

Nextcloud News is software for managing and viewing RSS feeds. First set up your client devices, so that Nextcloud will automatically keep your feeds synced.

Available for:

Web Interface
Mobile
- Android
- iOS
- SailfishOS
Desktop:
- Linux
- Mac
- Windows
- Unix Terminal

NC App Setup

Begin by downloading News from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "News." Click it to get started.
- You can now add your favorite RSS feeds from the left-hand panel.

Desktop & Mobile Setups

Nextcloud News can be synced with a wide range of clients across almost any platform you can imagine. See all the options on the official client list.

Nextcloud Notes

Nextcloud Notes is software for managing and syncing your notes across devices. First set up your client devices, so that Nextcloud will automatically keep your notes synced.

Available for:

Web Interface
Mobile
- Android
- iOS
Desktop:
- Unix Terminal

NC App Setup

Begin by downloading Notes from your Nextcloud service's App Store (Top-right menu -> Apps).
```
Use the "Search" function to quickly find the App you are looking for
```
Once installed/enabled, you will get a new icon in your top menu for "Notes." Click it to get started.
- You can now use the web UI to record your notes.
```
Markdown is supported
```

Desktop & Mobile Setups

The real beauty of Notes is being able to sync to your mobile devices for use on the go.

Nextcloud Notes (Android)

Download the Nextcloud Notes app from your favorite app store (Aurora, F-Droid, or Play Store).
On the opening screen, select your existing Nextcloud account. If one does not exist, make sure to start with your client setup or you can hit "Add Account," then create an app passcode QR under Nextcloud's main top-right menu -> Personal Settings -> Hamburger (3 lines) Menu > Security > Devices & Sessions > "Create new app password" and scan it to grant access.
You existing notes will now sync, or you can create your first note to test!

Nextcloud Notes (iOS)

Download the Nextcloud Notes app from the App Store.
Enter your Nextcloud server URL from your server: Nextcloud -> Interfaces (LAN recommended).
You will be redirected and asked for your username and password, both can be found on your server: Nextcloud -> Properties. Then Grant Access.
You'll be returned to the setup screen, just tap "Done," your existing notes will now sync, or you can create your first note to test!

Nextcloud Photos

Nextcloud Photos is a basic gallery for viewing and managing your photos. First set up your client devices, so that Nextcloud will automatically keep your photos synced.

Available for:

Web Interface
Mobile
- Android

NC App Setup

Photos is included by default and there will be an icon in your top menu for "Photos." Click it and you will be in the web UI viewing your gallery.

Desktop & Mobile Setups

nc-photos (Android)

nc-photos is a modern mobile photo gallery with a grid-based interface reminiscent of Google Photos.

First, install Photos (for Nextcloud) from the Google Play Store or from the GitLab repository. There is a ad-supported version and a paid version on the Play Store, but the GitLab APK is ad-free by default.
At the welcome screen, you will be reminded not to delete a special folder that will be created in your Nextcloud file directory and asked to enter your server URL.
Select your prefered interface for Nextcloud (.local:PORT, IP:PORT or .onion from StartOS's UI) and paste it into the field without http or https.
Proceed to connect and authenticate automatically.
- That's it! Photos will take some time to initially sync.

Memories (Android)

Memories the Android app is based on the Nextcloud Memories app and is a modern free and open source replacement for Google Photos.

First, install Memories from the Google Play Store, F-Droid or from the GitHub repository.
At the welcome screen, you will be reminded not to delete a special folder that will be created in your Nextcloud file directory and asked to enter your server URL.
Copy the interface for Nextcloud (.local:PORT, IP:PORT from StartOS's UI) and paste it into the field. Tor is not supported.
Check disable certificate verification which did not work on testing.
Proceed to connect and authenticate automatically.
- That's it! Photos will take some time to initially sync.

Les Pas (Android)

Les Pas is a great mobile gallery for viewing and organizing your photos, gifs, and videos.

First, install Les Pas from your favorite app store (Aurora, F-Droid, or Play Store), or from the github repository.
At the welcome screen, you will be asked to either enter your server URL or scan a QR code. In your Nextcloud instance, click the top-right menu -> Personal Settings -> Hamburger (3 lines) Menu > Security > Devices & Sessions > "Create new app password." Hit "Show QR Code" and then scan it with Les Pas.
You'll be sent to your Nextcloud instance to log in and grant access to the app.
- That's it! You're ready to view your photos with no third party involved!

Joplin

Joplin is an open source note-taking app. Capture your thoughts and securely access them from any device. First set up your client devices, so that Nextcloud will automatically keep your notes synced.

Clients available for:

Desktop
- Linux
- Mac
- Windows
Mobile
- Android
- iOS

Connecting Joplin to Nextcloud (Mac Desktop Example)

This guide will go over how to connect Joplin running on a desktop machine to your Start9 server's Nextcloud over LAN.


This guide assumes your Nextcloud username is "embassy," replace with your username if different.

You will need your device set up to connect via LAN first.

First go into Nextcloud on your server and click on the "Files" app icon.
Click on the + icon, then "New folder".
Create a new folder called "joplin" and click the arrow to the right.
Click on "Files settings" in the bottom left and copy the WebDAV link.
Open up Joplin, click on "Joplin" in the top left and click "Preferences" (on Mac).
Click on "Synchronisation".
Under "Synchronisation target" select "Nextcloud", paste the WebDAV and append onto the end of it "joplin" so the entire URL should look like this (replace xxxx with your unique Nextcloud LAN address): https://xxxx.local/remote.php/dav/files/embassy/joplin.
Under "Nextcloud username" enter "embassy" (or your username).
Under "Nextcloud password" enter your password.
The username and password for your Nextcloud can be found in your server's UI by clicking on the Nextcloud service then clicking on "Properties".
Now click "Show advanced settings".
Scroll down then check the box that says "Ignore TLS certificate errors".
Now scroll back up and select "Check sychronisation configuration" and you should see the following success message:
You have now connected your Joplin client to your Start9 server's Nextcloud and your notes will sync automatically!

Thunderbird

Content

Calendar Syncing

You can set up your devices using their integrations, but if you wish to use a standalone client for your Calendar and Contacts syncing, we recommend Mozilla's Thunderbird.

Install the Calendar and Contacts apps in Nextcloud if they are not currently installed.
Add your RootCA to your system and then configure Thunderbird.
In Thunderbird, click on the calendar icon, then "New Address Book" in the bottom-left.
Choose "On the network," then click "Next".
Fill in the Username and Location fields with the credentials from Nextcloud > Properties on your Start9 server. Click "Find calendars".
Create a unique app password - In your Nextcloud WebUI, visit the top-right-hand menu and select "Personal Settings" -> "Security." At the bottom, under "Devices & Sessions," create a new app password with a name of your choice, such as "CalDAV." Copy the resulting password and paste it into Thunderbird.
Check which calendars you want to integrate and click "Subscribe".

Your Nextcloud calendar will now sync with Thunderbird. Click on the "Contacts" tab above to add your contacts.

Contact Syncing

Install the Calendar and Contacts apps in Nextcloud if they are not currently installed.
Add your RootCA to your system and then configure Thunderbird.
Click on the Address Book icon, open the drop-down menu for "New Address Book" and click "Add CarDav Address Book".
Fill in the Username and Location fields with the credentials from Nextcloud > Properties on your Start9 server. Click "Continue".
Create a unique app password - In your Nextcloud WebUI, visit the top-right-hand menu and select "Personal Settings" -> "Security." At the bottom, under "Devices & Sessions," create a new app password with a name of your choice, such as "CalDAV." Copy the resulting password and paste it into Thunderbird.

Your Nextcloud contacts will now sync with Thunderbird.

Nostr

These guides will help you to setup tools to run a nostr relay and a nostr client.

Nostr RS Relay

Nostr is a simple, open protocol that enables global, decentralized, and censorship-resistant social media.


It is highly recommended that you run a private relay, not a public one. Private will be the default option when you open the config for the first time. You will not be able to save the config until you follow the instructions below.

Initial Config

Install Nostr RS relay service from Start9 Registry on your server.
In the service, page click CONFIGURE and add the pubkey in hex format to whitelist your client. Click save.
Now you will have a Nostr relay websocket URL available in Nostr RS Relay -> Properties.

Running a private relay

Private relays serve as a personal backup for your posts, follows, messages, settings, and more. Without a private relay, there is no assurance that this data will be preserved, and there is a risk of it disappearing unexpectedly. By utilizing a private relay, only the pubkeys on the whitelist are authorized to post and save content to your relay. To ensure functionality, it is essential to whitelist your own pubkey in hex format. The configuration settings will not permit saving until at least one pubkey is added to the whitelist. Some Nostr clients may offer the option to copy your hex pubkey, but if not, you can visit https://damus.io/key to convert your npub to hex.

Running a public relay

In contrast to a private relay, a public relay lacks a whitelist, permitting any pubkey to post. Running a public relay is not recommended unless you comprehend the associated risks and configure it with appropriate safeguards. The primary risk to be mindful of is the potential for malicious clients to spam your relay, leading to the saturation of your storage drive. While we have implemented fairly restrictive defaults in your configuration to mitigate this risk, it is crucial to acknowledge that you assume responsibility for managing this aspect on your own.

Testing your relay

If you want to test your private relay and verify whether it's storing all your notes, you can SSH into your server and execute the following command.

sudo podman exec nostr.embassy sqlite3 /data/nostr.db "SELECT content FROM event;" | grep -o 'content":"[^"]*' | awk -F: '{print $1":"$2}'

noStrudel

noStrudel is a web app for exploring the nostr protocol.

Using noStrudel on StartOS

Install the noStrudel service from the Start9 registry on your server.
Click "Start".
When the service is ready click "Launch UI" to access noStrudel.
Choose how to setup your relays and create a new account or access an existing account by using a nip-07 browser extension. If creating a new account, be sure to securely back up the private key, preferably using Vaultwarden on StartOS.

To connect to your own private relay, go to Relays -> App Relays, paste in your Nostr Relay Websocket URL (e.g. ws://address.onion) and click add. You can find this value in the Properties section of your Nostr RS Relay service.


If you plan to connect to your own private relay, you must use either be running your own [LAN/Router VPN](/user-manual/connecting-remotely.md) or you must use [Tor browser](https://www.torproject.org/) on your system.  We recommend using Firefox which must be [configured to use Tor](/misc-guides/firefox-guides/tor.md).

add relay

To connect to your LND instance using NWC (Nostr Wallet Connect) for LN payments, go to Settings -> Lightning -> Connect wallet. Choose NWC and paste your pairing secret.

Vaultwarden

Vaultwarden is a self-hosted password manager, which means your passwords physically live on your Start9 Server. Be sure to create backups and keep them safe! If you lose your Server or uninstall Vaultwarden, and you have not made a backup, all your passwords will be lost forever.

If you currently have a hosted account with Bitwarden, you can export your data from that account and import it to your Vaultwarden service on your Start9 Server using the built-in import/export features in any Bitwarden application!

Follow the guides below to get the most out of your Vaultwarden server:

Initial Setup

Web Vault

Ensure Vaultwarden is running - click START on your Start9 Server if not:
Once the health check turns green, click Launch UI:

Time to create an account! Click Create account:

vaultwarden-create-account


You are creating an account with yourself on your own Vaultwarden website served from your own Vaultwarden server - there are no third parties involved here.

Enter an email address for login:

vaultwarden-create-account-email


This email address can be anything you like. It doesn't have to be real. It is simply a way for you to log into Vaultwarden from Bitwarden apps on your devices. Your Vaultwarden server won't ever email you.


You cannot use this email address to reset your master password - it is simply used to create an account on your server.


Do not lose it - you will not be able to log in without it!

Enter a name for the account, a strong password and (optionally) a password hint - then click Create account:

vaultwarden-account-creation


It is important to realize that this is the **Master password** for all your other passwords. Make it very strong, memorize it, write it down, and back it up to a safe place. If you lose it, you may lose access to all your passwords and your entire digital life.

Now you can log in to your new password manager! Enter your email to login:
Then your master password:
We are greeted with our newly setup Vaultwarden password vault!
On the left, you can access Tools for reports and the password generator. You can also import data from other programs, such as LastPass, 1Password, or KeePass!
Account settings gives you all your options, including the ability to set up 2 factor authorization.
Now you're ready to start storing some passwords!

Storing your first password

Back at the main page for your vault, let's do a quick example login. We'll start by creating a folder for it:
Name the folder and click Save:
Click New item:
Now add the credentials and click Save:

An entry can have multiple URLs - for example you may wish to enter both an onion address and a .local address for one of the services you have running on your server. We are increasing the numbers of ways in which you can connect to your services, soon they may even have simple .com addresses!
And there we have it - our first set of login credentials.

Congratulations! You have setup your own self-hosted password manager and have added a set of login credentials to it!

Accessing the Admin Console

You will find the Admin URL by heading to "Properties" on the Vaultwarden Service page.
Copy either of the addresses here and paste in the browser.
You will be prompted for your "Admin Token," which can be found on the same page.
Paste it on Admin page:

You're now logged in to the admin panel.

vaultwarden-admin-console


This **cannot** be used to reset passwords for accounts created on your Vaultwarden server.

Now you'll want to setup some client devices! Head here for instructions on how to do so.

Bitwarden Client Setup

Here you can learn how to setup your various devices and browsers to be able to access your Vaultwarden service.

We suggest you connect to Vaultwarden over VPN or Tor for the best experience… an experience where you can access synced passwords away from home as well as create and save new passwords. Over LAN your app and all your passwords will be cached and available after an initial sync when not connected to your Start9 Server but you would later need to connect via LAN to add or update passwords in your vault. Bitwarden requires an encrypted connection, so make sure you trust your root CA on all devices.

Contents

Browser Extension


If you intend on connecting via **Tor** (i.e using the .onion address) rather than VPN the Bitwarden browser extension will only work with a Tor enabled browser.

If you choose **Firefox with Tor**, you will need to [follow this guide](/misc-guides/firefox-guides/tor.md) to run Tor on your device and configure Firefox to use it. If using **Brave** you will just need to [setup Tor on your device](/user-manual/connecting-remotely.md#connecting-over-tor). With Tor Browser, everything will just work right out of the box.

We recommend using Firefox as it is the most compatible browser with Start9 Servers.

In this example we will use Firefox, though these instructions will work just the same for Brave. First, install the Bitwarden browser extension.
Head to the Interfaces tab in the Vaultwarden service on your Start9 Server.
Copy the preferred interface address for VPN/LAN or Tor:
Open Bitwarden extension and click the self-hosted dropdown menu and choose self-hosted. Paste your interface address to Server URL field and click save.
Enter your credentials and the Bitwarden extension will be logged into your self-hosted Vaultwarden server!

Android

Visit google play store and download the Bitwarden app.

Head to the Interfaces tab in the Vaultwarden service on your Start9 Server:

vaultwarden-interfaces


If connecting via **Tor** rather than VPN (i.e using the .onion address) the Bitwarden app will only work if [Tor is enabled](/device-guides/android/tor.md) on your device and Bitwarden is added to Orbot's VPN apps list. You may need to hit the refresh button in the top left to get it to populate.

Copy the preferred interface address for VPN/LAN or Tor:
Send that address to your phone.

Open the Bitwarden app. Tap the self-hosted dropdown menu and choose self-hosted. Paste your interface address to Server URL field and tap save.


For **Tor**, before you hit save:  If the Tor address you have copied begin with **http** - Please change this to **https** instead of **http**

Tap 'Log In,' enter your credentials, and you can access your Bitwarden app / Vaultwarden server.

iOS

Visit the App Store and download the Bitwarden app

Head to the Interfaces tab in the Vaultwarden service on your Start9 Server.

vaultwarden-interfaces


If connecting via **Tor** rather than VPN (i.e using the .onion address) the Bitwarden app will only work if [Tor is enabled](/src/device-guides/android/tor.md) on your device and Bitwarden is added to Orbot's VPN apps list. You may need to hit the refresh button in the top left to get it to populate.

Copy the preferred interface address for VPN/LAN or Tor:
Send that address to your phone.

Open the Bitwarden app. Tap the self-hosted dropdown menu and choose self-hosted. Paste your interface address to Server URL field and tap save.


For **Tor**, before you hit save:  If the Tor address you have copied begin with **http** - Please change this to **https** instead of **http**

vaultwarden-iOS-log-in-screen

Tap Log In, enter your credentials, and you'll be able to access your Bitwarden app / Vaultwarden server!

Desktop Clients

Linux

Install Bitwarden either by using a package manager like apt (we recommend against using snap) or download it from here.
If you intend to use Tor, run the program with the flag --proxy-server=socks5://127.0.0.1:9050 behind it. You can run this from a terminal, and if you'd like to use a shortcut, edit that shortcut file to include the flag.
Copy the preferred interface address for VPN/LAN or Tor:
Choose the Self-hosted option, paste the preferred interface address for VPN, LAN or Tor:
Click save and log in.

MacOS

Download the Bitwarden Desktop app.
If you intend to use Tor, make sure Tor is running on your Mac. If you intend to use a VPN, make sure you have it running on your Mac.
Copy the preferred interface address for VPN, LAN or Tor:
Click the Self-hosted option, paste the preferred interface address for VPN, LAN or Tor:
Click save and log in.

Windows

Download the Bitwarden Desktop app.
If you intend to use Tor, make sure Tor is running on Windows. If you intend to use a VPN, make sure you have it running on your Mac.
Copy the preferred interface address for VPN/LAN or Tor:
Click the Self-hosted option, paste the preferred interface address for VPN, LAN or Tor:
Click save and log in.

Organizations in Vaultwarden

Creating an Organization

If you want to share passwords amongst friends or family, you can do so using the Organizations feature of Vaultwarden.

Inside your Web Vault, click New Organization

Give your organization a name and enter your email.

You can enter whatever you want for email, even **fake@email.com**. Because you are self-hosting, the email is not used for anything at all.

Adding Others to Your Organization

   After you have completed signed up new members to your Vaultwarden server, it is highly recommended that you disable new user signups inside your `Vaultwarden Admin Dashboard` --> General Settings --> Allow new signups --> uncheck the box.

Tell the user to create an account on your Vaultwarden server. This must be done before you invite them.
Inside the Organization page, click Members --> Invite member
Decide what permissions you want the member to have and click "Save". In the below example, the member will be a manager.
The new member should automatically show as Needs confirmation. If the user shows as Invited, Remove their account by clicking the settings icon to the right of their email address, and make sure they create account before you invite them, as mentioned in Step 1. Once they show as Needs confirmation, select user checkbox and click the settings icon on the right and click "Confirm selected".
You will be presented with a fingerprint phrase. The new member can verify this phrase inside their own dashboard, but because you are self-hosting and adding users manually, you can just click "Confirm".

The new member should now be able to see the organization in their own dashboard or client apps.

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:
```
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:
```
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.

Migrating LND to StartOS


After migrating an LND wallet to StartOS, NEVER restart your old node. Turning on your old node can result in the broadcast of old channel states and potentially loss of funds!

This guide is for users seeking to migrate LND on-chain and lightning funds from a different node to StartOS easily and without closing channels. This migration will require two sets of hardware, your existing hardware you wish to migrate from, and the hardware running StartOS you are migrating to. Both devices must be running on the same LAN. The LND service on StartOS provides easy to use actions for users migrating from the below Node implementations:

Umbrel (Both 1.x and 0.5)
RaspiBlitz
myNode

Instructions

First, you will need a fresh installation of LND on StartOS which has never been started. Starting the LND service will create a wallet; if there is an existing LND wallet on StartOS, LND will not allow any of the import actions to be run.
Select the action corresponding to the node you are migrating from and fill out the corresponding IP and password(s). If you are unsure of the IP address of your node, you may need to check your router.
The migration action may take several minutes to complete. Once the action has completed and your old node has been unplugged, you may safely start LND on StartOS. Remember - NEVER restart your old node after the migration has completed!

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.

Docker

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

Make

Make is used streamline builds and produce an s9pk.

NodeJS

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

start-cli

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

Clone the start-os repo

https://github.com/Start9Labs/start-os.git

Build start-cli
```
make cli
```
Initialize start-cli
```
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.

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/
├── file-models/
├── versions/
├── backup.ts
├── dependencies.ts
├── index.ts
├── init.ts
├── interfaces.ts
├── main.ts
├── manifest.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.

dependencies.ts

setupDependencies() is where you define any dependencies of this package, including their versions, whether or not they need to be running or simply installed, and which health checks, if any, need to be passing for this package to be satisfied.

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.

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.
Data that cannot be retrieved or derived from the service itself.

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 that display as buttons to the user. They accept arbitrary input and return structured data that can be optionally displayed masked or as QR codes. For example, a config.ts action might present a validated form that represents an underlying config file of the service, allowing them to configure the service without needing SSH or the command line. A resetPassword action could generate a new password, save it to the appropriate place in the file system or package store, and display it to the user.

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

file-models/ (optional)

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.

versions/

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

In the versions/ directory, you will create a new file for each new package version. Here you will provide the version number, release notes, and define any migrations that should run. Note: migrations are only for migrating data that is not migrated by the upstream service itself. All versions must then be provided as arguments to VersionGraph.of() in index.ts with the MOST RECENT VERSION LISTED FIRST.

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.