systemd can manage user-level services, allowing you to run tmux sessions automatically when you log in.
Here’s how to set up a systemd user service to start a tmux session on boot:
First, let’s see a tmux session in action. Imagine you’re logging into a remote server and want your development environment to be ready immediately.
# SSH into your server
ssh user@your_server.com
# Once logged in, a tmux session named 'dev' is already running
tmux attach -t dev
If the session doesn’t exist, it’s created automatically. Inside, you might have several panes and windows already set up for your workflow.
The core idea is to create a .service file in your user’s systemd configuration directory. This file tells systemd how to start and manage your tmux session.
The systemd user service needs to know which command to run. For tmux, this is typically tmux new-session -d -s session_name. The -d flag detaches the session immediately, so it runs in the background, and -s session_name gives it a recognizable name.
You’ll also want to define the environment in which the service runs. This includes things like PATH and any other environment variables your applications might need.
Here’s a typical .service file. Save this as ~/.config/systemd/user/tmux.service:
[Unit]
Description=My tmux session
After=network.target
[Service]
Type=forking
User=%i
ExecStart=/usr/bin/tmux new-session -d -s dev
ExecStop=/usr/bin/tmux kill-session -t dev
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target
Let’s break this down. [Unit] describes the service. Description is human-readable. After=network.target ensures the network is up before your tmux session starts, which is often necessary for development tasks.
The [Service] section is where the magic happens. Type=forking is used because tmux new-session forks a background process. User=%i is a special systemd specifier that means "run this service as the user whose home directory is the instance name of the service." In this case, it’s your user. ExecStart is the command to run to start the service. ExecStop is the command to run to stop it. Restart=on-failure and RestartSec=5 mean systemd will try to restart the service if it crashes, waiting 5 seconds between attempts.
The [Install] section tells systemd how to enable the service. WantedBy=default.target means this service should be started when the user’s default target is reached, which usually happens shortly after you log in.
After creating the tmux.service file, you need to tell systemd about it and enable it.
First, reload the systemd user daemon to pick up the new service file:
systemctl --user daemon-reload
Then, enable the service so it starts on future logins:
systemctl --user enable tmux.service
Finally, start the service immediately:
systemctl --user start tmux.service
You can check the status of your tmux service with:
systemctl --user status tmux.service
This should show it as active and running. If you want to attach to the session, use tmux attach -t dev from your terminal.
If you want to stop the tmux session managed by systemd, run:
systemctl --user stop tmux.service
And to disable it from starting on boot:
systemctl --user disable tmux.service
A common gotcha is ensuring the tmux executable is in the PATH for systemd. While your interactive shell might have /usr/bin in its PATH, systemd’s environment can be more minimal. Explicitly using the full path /usr/bin/tmux in ExecStart and ExecStop is a robust practice.
Another subtle point is that Type=forking expects the ExecStart command to exit after the daemon process is forked. tmux new-session -d does exactly this, so it’s appropriate here. If you were running a command that stayed in the foreground, you’d use Type=simple.
The User=%i directive is powerful. If you wanted to manage a tmux session for a different user (e.g., a dedicated service user), you could create a directory like ~/.config/systemd/user/tmux@myotheruser.service.d/ and override the User directive, or even create separate service files for different users if they have their own systemd user instances.
The After=network.target is crucial if your tmux session needs to access network resources immediately upon startup. Without it, the tmux session might start before the network interfaces are fully configured, leading to connection errors for any tools you run within it.
The next step is to explore how to configure the contents of your tmux sessions, such as automatically creating windows and panes with specific commands running in them, using tmux.conf or scripts executed by ExecStart.