Flox and systemd

Flox environments have a built-in concept of services. Flox environment services are managed by invoking the flox services category of sub-commands such as flox services status. In some scenarios, you may want to register Flox services to be run and managed by the operating system’s systemd. For example, systemd can auto-start services when the host is booting or when a service crashes. This tutorial shows how to create and use systemd services with Flox by creating unit files manually. You will learn how to run a Flox environment service as both a systemd user unit and a systemd system unit.

Prerequisites

A Linux system with systemd support. This tutorial was tested on Ubuntu 24.04 and 26.04.
Flox installed in multi-user mode. This tutorial was tested on Flox 1.11.0.

Constraints

The systemd service that invokes Flox cannot run as root.
The service cannot listen on a port with a value less than 1024.
The UID for the user running the systemd service should be >= 1000 for logs to function properly. See flox#2e789b5 for details.
Logs may not function properly if the process forks. See flox#9b1e750 for details.

Run a Flox environment service as a systemd user unit

In this section you will set up a Redis service from a FloxHub environment and run it as a systemd user unit.

Create the Redis environment locally

Pull the flox/redis environment from FloxHub into your home directory:

flox pull flox/redis -d ~/redis

Test the environment with Flox services

Before creating the systemd unit, verify that the environment works:

$ cd ~/redis
$ flox activate -s
$ flox services status
$ redis-cli -p $REDIS_PORT ping
$ exit

Create the systemd user service

Create the systemd user unit file:

mkdir -p ~/.config/systemd/user/
cat > ~/.config/systemd/user/redis.service << 'EOF'
[Unit]
Description=Redis Server (Flox)

[Service]
ExecStart=flox activate -d %h/redis -c 'redis-server --bind $REDIS_HOST --port $REDIS_PORT --daemonize no --dir $REDIS_DATA'

[Install]
WantedBy=default.target
EOF

By default, systemd user units only run while the user is logged in. Enabling lingering allows the service to start at boot without a login session. If you only need the service to run while you are logged in, you can skip this step.

sudo loginctl enable-linger $USER

Load, enable, and start the service:

systemctl --user daemon-reload &&
systemctl --user enable redis.service &&
systemctl --user start redis.service

Verify the service is running:

systemctl --user status redis.service

Verify Redis is responding:

flox activate -d ~/redis -c 'redis-cli -p "$REDIS_PORT" ping'
# should respond PONG

User unit cleanup

To stop and fully remove the systemd user unit:

systemctl --user stop redis.service
systemctl --user disable redis.service
rm ~/.config/systemd/user/redis.service
systemctl --user daemon-reload

Run a Flox environment service as a systemd system unit

For services that should run under a dedicated system user rather than your personal account, you can create a system-level systemd unit instead.

Create a dedicated Redis user and environment

sudo useradd --system --create-home --shell /usr/sbin/nologin redis &&
sudo -u redis flox pull flox/redis -d /home/redis/redis

Create the system unit file

Since the redis user has no login session, user units will not work. Create a system unit instead:

sudo tee /etc/systemd/system/redis.service << 'EOF'
[Unit]
Description=Redis Server (Flox)

[Service]
User=redis
ExecStart=flox activate -d /home/redis/redis -c 'redis-server --bind $REDIS_HOST --port $REDIS_PORT --daemonize no --dir $REDIS_DATA'

[Install]
WantedBy=multi-user.target
EOF

NoteEnable lingering is not needed for system units. System units start at boot automatically.

Load, enable, and start

sudo systemctl daemon-reload &&
sudo systemctl enable redis.service &&
sudo systemctl start redis.service

Verify

sudo systemctl status redis.service

flox activate -d ~/redis -c 'redis-cli -p $REDIS_PORT ping'
# should respond PONG

NoteKey differences from the user unit approach: the system unit goes in /etc/systemd/system/, uses multi-user.target, requires sudo, and no lingering is needed.

System unit cleanup

To stop and fully remove the systemd system unit:

sudo systemctl stop redis.service
sudo systemctl disable redis.service
sudo rm /etc/systemd/system/redis.service
sudo systemctl daemon-reload

Introduction

Install Flox

Quickstart

Tutorials

Imageless Kubernetes

Concepts

Languages

Customer

Flox and systemd

Prerequisites

Constraints

Run a Flox environment service as a systemd user unit

Create the Redis environment locally

Test the environment with Flox services

Create the systemd user service

User unit cleanup

Run a Flox environment service as a systemd system unit

Create a dedicated Redis user and environment

Create the system unit file

Load, enable, and start

Verify

System unit cleanup

Where to next?

​Prerequisites

​Constraints

​Run a Flox environment service as a systemd user unit

​Create the Redis environment locally

​Test the environment with Flox services

​Create the systemd user service

​User unit cleanup

​Run a Flox environment service as a systemd system unit

​Create a dedicated Redis user and environment

​Create the system unit file

​Load, enable, and start

​Verify

​System unit cleanup

​Where to next?

Prerequisites

Constraints

Run a Flox environment service as a systemd user unit

Create the Redis environment locally

Test the environment with Flox services

Create the systemd user service

User unit cleanup

Run a Flox environment service as a systemd system unit

Create a dedicated Redis user and environment

Create the system unit file

Load, enable, and start

Verify

System unit cleanup

Where to next?