Basalt Host with no screen

This version of Basalt Host has no window. It runs in the background, starts with the computer, and you set it up and manage it from the Basalt app on your phone or computer, with Manage host. It suits a home server, a Raspberry Pi, an old computer under the TV, or a NAS that runs Debian or Ubuntu.

For a NAS that runs Docker, see Basalt Host in Docker.

Before you start

• A Linux computer: Debian 11 or later, Ubuntu 20.04 or later, Raspberry Pi OS (64-bit), Fedora, Rocky Linux or similar
• A terminal on it, directly or over SSH, and a user that can use sudo
• A phone or computer with Basalt, on the same network

Choose a package

On the download page, under No screen, choose the package for the system, and the processor:

Processor	Choose	Typical computers
64-bit Intel or AMD	PC (amd64 / x86_64)	Home servers, mini PCs, most NAS boxes, old laptops
64-bit ARM	ARM (arm64 / aarch64)	Raspberry Pi 3, 4 and 5 with a 64-bit system, other ARM boards

Not sure which you have? uname -m says x86_64 for a PC and aarch64 for ARM.

You can download straight onto the computer, for example:

wget https://basalt.reforatech.com/download/server-deb-amd64 -O Basalt-Host-Server-Linux-amd64.deb

The address for each package is the download button’s link on the download page.

Install it

Debian, Ubuntu, Raspberry Pi OS

sudo apt install ./Basalt-Host-Server-Linux-amd64.deb

Use -arm64.deb on ARM.

Fedora, Rocky Linux and similar

sudo dnf install ./Basalt-Host-Server-Linux-x86_64.rpm

Use -aarch64.rpm on ARM.

The package installs:

• the basalt-host command
• a basalt-host service, which starts now and every time the computer starts
• its updater, so the host keeps itself up to date
• a firewall profile for ufw or firewalld
• ffmpeg, where the system offers it, to convert video for devices that cannot play it

When it finishes, it shows the host’s status: its name and address, a setup code, and anything left to do.

Anything else, with the .tar.gz

On a system without apt or dnf, unpack the archive and copy the files into place:

tar xzf Basalt-Host-Server-Linux-x86_64.tar.gz
cd basalt-host-server-*/
sudo install -m 0755 basalt-host /usr/bin/basalt-host
sudo install -D -m 0755 basalt-host-update /usr/lib/basalt-host/basalt-host-update
sudo cp basalt-host.service basalt-host-update.service basalt-host-update.path /etc/systemd/system/
sudo useradd --system --user-group --home-dir /var/lib/basalt-host --shell /usr/sbin/nologin basalt
sudo systemctl daemon-reload
sudo systemctl enable --now basalt-host basalt-host-update.path

This needs a system that uses systemd.

Open the firewall

If the computer’s firewall is on, let your devices through. Installing says so when it is needed:

# Debian, Ubuntu, Raspberry Pi OS (ufw)
sudo ufw allow "Basalt Host"

# Fedora, Rocky Linux (firewalld)
sudo firewall-cmd --permanent --add-service=basalt-host
sudo firewall-cmd --reload

Find the setup code

A new host waits for its first device to set it up, with a one-time setup code of eight letters and numbers, such as K7QF-M2XR. To see it again at any time:

sudo basalt-host status

  ● Basalt Host 1.5.0 is running

    Name        home-server
    Address     192.168.1.20:7742
    Identity    3fa91c07
    Version     1.5.0
    Sharing     nothing yet
    Devices     none yet

  ┌─ Set it up ──────────────────────────────────────────┐
  │                                                      │
  │   Setup code   K7QF-M2XR                             │
  │                                                      │
  │   Open Basalt on your phone or computer, on this     │
  │   network, choose "home-server" and type the code.   │
  │   That device will manage the host.                  │
  │                                                      │
  └──────────────────────────────────────────────────────┘

The code is in the host’s log too: journalctl -u basalt-host.

Set it up from your phone

1. Open Basalt on a phone or computer on the same network. The host is in the list, marked new. Choose it.
2. Type the setup code.
3. That device now manages the host. Basalt says the host isn’t sharing anything yet: choose Choose what it shares. Pick a drive from the list, or choose Choose a folder… and tap through the host’s folders to the one you want.

From then on, Manage host on that device does everything a host’s window would: name the host, let new devices in, add profiles, and change any setting. See Manage host.

When another device asks to join, its PIN shows in Manage host on the device that manages the host.

Let it read your files

The service runs as its own user, called basalt, which can only read its own settings at first. Give it access to the folder it shares, for example /srv/media:

sudo setfacl -R -m u:basalt:rwX -m d:u:basalt:rwX /srv/media

• Use r-X instead of rwX for a host that should never change anything on the drive.
• Each folder above it must let the basalt user through too: sudo setfacl -m u:basalt:x /srv, for each one, or for the drive’s mount folder.
• setfacl comes in the acl package, if your system does not have it yet.

If the folder does not appear in Choose a folder…, or opening it says the host isn’t allowed, this is the reason.

Or run it as your own user

If your files belong to you and you would rather the host ran as you:

sudo systemctl edit basalt-host

and add:

[Service]
User=yourname
Group=yourname

then sudo basalt-host restart.

Everyday commands

Command	What it does
sudo basalt-host status	Whether it is running, its address, what it shares, its devices, and the setup code while it waits for one
sudo basalt-host start	Starts it, and says when it is running
sudo basalt-host stop	Stops it until you start it again or the computer restarts
sudo basalt-host restart	Restarts it, and says when it is back
sudo basalt-host update	Installs the newest version now
journalctl -u basalt-host -f	Follows its log

The full list is in Commands.

Updates

The host updates itself twice a day when there is a new version and nothing is playing. A device that manages it can update it now, or turn this off, under Updates in Manage host. See Updates.

If the device that manages it is lost

sudo basalt-host setup-code --reset

makes a new setup code even though the host is set up. The next device to use it manages the host too. Afterwards, remove the lost device in Manage host.

Uninstall

sudo apt remove basalt-host-server     # or: sudo dnf remove basalt-host-server

Removing keeps the host’s settings in /var/lib/basalt-host, so installing it again brings back the same host, with its devices still paired. To delete them too, use sudo apt purge basalt-host-server; every device would then pair again.