Getting Started

System Requirements

As of the latest release, Sylve requires FreeBSD 15.0-RELEASE or later. You will also need to have a ZFS pool available if you intend to use Sylve for managing Virtual Machines or Jails. If you are using Sylve just for things like WireGuard or the built-in firewall, you can use any filesystem, but ZFS is still recommended for its advanced features and reliability.

Note

Although we list support for FreeBSD 15.0-RELEASE, we strongly recommend using -STABLE with pkgbase, -CURRENT is also supported, but remember to disable any debug features in the config if you’re using it in production!

Since both Sylve and Bhyve are under pretty active development, using a more recent version of FreeBSD will ensure you have the latest features and bug fixes. That said, if your use case requires maximum stability and you do not need the latest features or bug fixes, 15.0-RELEASE should work perfectly fine.

Configure a hostname before signing in

Every node must have a hostname. It identifies the system throughout Sylve, and login attempts will be refused if one is not configured.

On FreeBSD, set a persistent hostname before starting Sylve:

sysrc hostname="sylve-node.lan"
hostname sylve-node.lan

TL;DR

If you want to get going right away, run pkg install sylve on a FreeBSD >= 15 machine and open https://<host>:8181 in your browser. For more details, continue reading.

Software Dependencies

Sylve is designed to run using only base FreeBSD dependencies if you prefer. However, we recommend installing the following packages:

Capability	Packages	What they enable	Requirement
Bhyve virtualization	libvirt, bhyve-firmware, swtpm, qemu-tools	Virtual-machine creation and management, firmware support, virtual TPMs, and disk-image tooling.	Required to use the virtualization subsystem.
SMB file sharing	samba4XX	SMB shares for guests and Jails, including basic share management and audit logging.	Optional; required for SMB features.
DHCP and DNS	dnsmasq	Managed DHCP ranges, leases, and DNS services from within Sylve.	Optional; required for managed DHCP and DNS.

Install all recommended dependencies at once:

pkg install -y libvirt bhyve-firmware swtpm qemu-tools samba423 dnsmasq

If you install Sylve with pkg install sylve, these dependencies are pulled in automatically; the command above is only needed when installing Sylve manually or building it from source.

Hardware Requirements

Use this estimator as a conservative starting point for a Sylve host running a mix of Jails, Bhyve virtual machines, and replicated workloads. Enter the resources assigned across your VMs rather than relying on a VM count. Jails use a modest mixed-services baseline; applications with known requirements should be sized separately.

Workload allocations

Jails−

5

+

VM vCPUs−

4

+

VM RAM−

8 GB

+

VM disks−

100 GB

+

Storage planning

Data to replicate−

100 GB

+

Replica copies−

1

+

ZFS headroom−

25%

+

CPU7 threadsWithout overcommit

Memory14.5 GBIncludes host + ARC reserve

Primary ZFS227 GBIncludes selected headroom

Replica targets134 GBData × copies, with headroom

Planning baseline, not a performance guarantee. CPU overcommit, thin provisioning, compression, deduplication, snapshot retention, and workload peaks can materially change the result.

How this estimate is calculated

The host reserve is one CPU thread plus 4 GB of memory for FreeBSD, Sylve, and a modest ARC. VM allocations are added directly. Each Jail contributes a planning allowance of 0.5 GB of memory, 10 GB of storage, and one quarter of a CPU thread. Storage totals preserve the selected percentage as free ZFS headroom.

Replica capacity is shown separately because it is consumed on the destination host or backup target. For active replication, prefer at least a 1 Gbps link and leave additional ZFS headroom for snapshots and changed blocks.

Note

If you are going to test out Sylve on providers like Hetzner, know that many of them do not support nested virtualization, so they cannot run Bhyve guests. Jails do not require nested virtualization and remain available on those hosts, along with all other features of Sylve.

Installing Sylve

From pkg

As mentioned before, the easiest way to install Sylve is via the FreeBSD package manager. Run the following command:

pkg install sylve

It will pull in all the required dependencies and install Sylve on your system. Once the installation is complete, you can enable and start the service using:

service sylve enable && service sylve start

Installing from GitHub Releases

Note

The releases are built using GitHub actions and does NOT involve any manual intervention, so you can be assured that the binaries are built from the source code in the repository.

We recommend first getting your system up and running with a pkg installation, and then replacing the binary with the latest release from GitHub if you want to stay on the bleeding edge. This is because the pkg version may lag behind the latest nightly release, and you may want to take advantage of new features or bug fixes (which we do support and recommend).

Before replacing the packaged binary, lock the Sylve package:

pkg lock -y sylve

The package database still considers /usr/local/sbin/sylve part of the installed Sylve package. Locking it prevents a later pkg upgrade from silently replacing your GitHub release with the repository version. Other system packages can continue to update normally.

You can visit the releases page and download the latest release for your architecture. Once downloaded, you can move the sylve binary to a location in your PATH, such as /usr/local/bin. The below commands will do this for you:

# Replace amd64 with arm64 if you're on an ARM64 system
fetch https://github.com/AlchemillaHQ/Sylve/releases/download/tip/sylve-amd64 -o sylve
chmod +x sylve
mv sylve /usr/local/sbin/

Should get you the absolute latest release, but if you want to get a specific version, just replace tip with the version tag you want to install for instance v0.3.0.

Keep the package locked while managing the binary from GitHub Releases. To return to the FreeBSD package version, unlock and reinstall it explicitly:

pkg unlock -y sylve
pkg install -f sylve

Building from Source

Building Sylve is actually insanely simple. You obviously need the Go toolchain and Node.js installed on your system, but other than that you can just clone the repository and run the build command. If you don’t have Go or Node.js installed, you can install them via pkg:

pkg install go node npm git-lite

Once that’s done, you can clone the repository, navigate to the project directory, and run the build command:

git clone https://github.com/AlchemillaHQ/Sylve.git
cd Sylve
make

That should build both the backend and frontend, and place the sylve binary in the bin/ directory. You can then move it to a location in your PATH:

mv bin/sylve /usr/local/sbin/

Setting up Sylve

Note

This section is primarily a configuration reference for manual installations from GitHub Releases or source. If you installed Sylve with pkg install sylve, the package provides the service integration and expected filesystem layout; you only need to review the configuration and enable the service.

Configuration file

Sylve reads its runtime configuration from /usr/local/etc/sylve/config.json. Start with the following production-oriented example and replace the administrator password before the first launch:

{
  "environment": "production",
  "proxyToVite": false,
  "profile": false,
  "ip": "0.0.0.0",
  "port": 8181,
  "httpPort": 8182,
  "logLevel": 3,
  "dataPath": "/var/db/sylve",
  "auth": {
    "enablePAM": false
  },
  "admin": {
    "email": "admin@sylve.local",
    "password": "replace-this-with-something-strong",
    "forcePasswordReset": false
  },
  "raft": {
    "reset": false
  },
  "btt": {
    "rpc": {
      "enabled": false,
      "address": "127.0.0.1",
      "port": 6890
    },
    "dht": {
      "enabled": true,
      "port": 7246
    }
  },
  "jails": {
    "disableDevFS": false
  },
  "zfs": {
    "tune": true
  },
  "uploads": {
    "maxFileBytes": 68719476736,
    "maxConcurrentTransfers": 2
  },
  "trustedProxies": []
}

Configuration reference

Object / parameter	Example	Purpose
config.jsonRoot configuration
environment	"production"	Runtime mode: production, development, or debug.
proxyToVite	false	Proxies frontend requests to Vite. Keep disabled in production.
profile	false	Enables Go block and mutex profiling for diagnostics.
ip	"0.0.0.0"	Bind address for the HTTP and HTTPS listeners.
port	8181	HTTPS API and web-interface port. Set to 0 to disable.
httpPort	8182	Plain HTTP port. Set to 0 to disable.
logLevel	3	0 debug, 1 info, 2 warning, 3 error, 4 fatal, 5 panic.
dataPath	"/var/db/sylve"	Stores databases, Raft state, downloads, uploads, and working data.
trustedProxies	[]	Trusted proxy IP addresses or CIDR ranges. Keep empty unless required.
authSystem authentication
enablePAM	false	Allows authentication with FreeBSD system accounts when explicitly enabled. Disabled by default.
adminBuilt-in administrator
email	"admin@sylve.local"	Email address assigned to the built-in administrator.
password	"…"	Sets the initial password. It may be blank after initialization without clearing the stored hash.
forcePasswordReset	false	Applies a non-empty configured password on the next startup, then clears itself.
raftCluster state
reset	false	Destructively resets this node's Raft state for deliberate cluster recovery.
btt.rpcOptional torrent RPC listener
enabled	false	Enables the BTT RPC listener.
address	"127.0.0.1"	RPC bind address. The field is named address, not host.
port	6890	RPC listener port.
btt.dhtTorrent peer discovery
enabled	true	Enables BitTorrent DHT discovery for magnet downloads.
port	7246	UDP port used for DHT peer discovery.
jailsJail integration
disableDevFS	false	Disables Sylve-managed DevFS rules. Automatically disabled when Sylve runs in a Jail.
zfsHost tuning
tune	true	Applies Sylve's recommended ZFS tuning during startup.
uploadsTransfer limits
maxFileBytes	68719476736	Maximum accepted file size in bytes; this example is 64 GiB.
maxConcurrentTransfers	2	Maximum number of simultaneous upload transfers.

Create the configuration directory and place the completed file there:

mkdir -p /usr/local/etc/sylve
mv config.json /usr/local/etc/sylve/

Sylve creates dataPath and its required subdirectories automatically. Place it on storage with enough capacity for databases, Raft state, uploads, ISO images, base archives, and other downloads.

Service integration

The pkg and ports installations provide the rc.d service automatically. For manual GitHub Release or source installations, use the maintained FreeBSD ports rc.d template as the reference implementation instead of copying a script from this guide. Ports placeholders such as %%PREFIX%% and %%ETCDIR%% are substituted during packaging and must resolve to the paths used by your manual installation.

Sylve loads its required kernel modules during operational startup. If you enable Jails while RACCT is disabled, Sylve adds kern.racct.enable=1 to /boot/loader.conf; reboot once after that automatic change so the boot-time setting can take effect.

Once the service script and configuration are in place, enable Sylve at boot:

sysrc sylve_enable=YES

Start it immediately unless you still need to reboot for loader settings:

service sylve start

Open https://<your-server-ip>:8181 and sign in with the administrator credentials from config.json.

Default Network Ports

Port	Scope	Purpose	Configuration
Public listeners
8181/tcp	Public	HTTPS API and web UIPrimary browser and API endpoint.	port
8182/tcp	Public	HTTP API and web UIInsecure on untrusted networks; intended for controlled reverse-proxy setups.	httpPort
Cluster transport
8180/tcp	Internal	RaftCluster membership and replicated control-plane state.	Not configurable
8183/tcp	Internal	Cluster SSHSecure channel for node-to-node operations.	Not configurable
8184/tcp	Internal	Cluster HTTPSNode control-plane traffic, including cluster joins.	Not configurable
Peer discovery
7246/udp	Optional	BitTorrent DHTPeer discovery for magnet downloads when DHT is enabled.	btt.dht.port