Launch a Safe Byobu tmux Session with byobu-tmux

You will launch Byobu using tmux as its backend, verify that the expected programs are installed, and detach and reattach a session without losing the shells inside it. The examples use Byobu 6.11 and tmux 3.4, installed here from the byobu package. Allow about fifteen minutes for a first run. You need a terminal and an ordinary user account; nothing in this guide needs sudo.

1. Confirm the wrapper and versions

The installed byobu-tmux is a symbolic link to Byobu's wrapper script. The name matters: the wrapper uses it to select tmux, even if another backend is configured as the general Byobu default.

$ command -v byobu-tmux
/usr/bin/byobu-tmux
$ readlink -f "$(command -v byobu-tmux)"
/usr/bin/byobu
$ byobu-tmux --version
byobu version 6.11
tmux 3.4

Byobu's manual describes byobu-tmux as launching Byobu with tmux as the backend window manager. Its -v and --version forms print the Byobu version and then ask the selected backend for its version. This is a useful checkpoint before troubleshooting keys or configuration.

2. Start a tmux-backed Byobu session

Run this as your normal user:

$ byobu-tmux

If this is the first session, you should see a full-screen terminal with Byobu's status information along the bottom. Underneath, tmux has created a session with one window. The command normally remains attached to that session, so your shell prompt is inside Byobu rather than back at the original terminal.

Do not use sudo to start it. The installed wrapper checks that the current user owns $HOME and warns that running Byobu under sudo can create root-owned files there. If you need a root shell inside a session, start Byobu as yourself and use the smallest necessary privileged command from a pane.

3. Detach without stopping the session

Inside Byobu, press Ctrl-a followed by d. Byobu commonly uses Ctrl-a as its outer prefix, while tmux itself uses Ctrl-b by default. The exact Byobu keymap can be changed, so use the on-screen help or press F9 if your installation presents a different prefix.

After detaching, the original terminal should show a message similar to this:

[detached (from session 0)]
$

The session continues in the background. This is the useful distinction between closing a terminal window and closing the program running inside it: an SSH disconnect normally detaches your client, but the tmux server and its pseudo-terminals can remain alive.

4. Reattach and check the session

From the same account, run:

$ byobu-tmux attach
[reattached to session 0]

The wording varies with tmux and the terminal, and an already attached session may produce an error instead. The important result is that your previous shell and window return. To see sessions without attaching, pass the tmux command through Byobu:

$ byobu-tmux list-sessions
0: 1 windows (created Tue Sep 22 10:00:00 2026) [80x24]

The date, dimensions and session name are host-specific. If there is no session, the command reports that the tmux server is not running or that no sessions exist. Start a new one with byobu-tmux rather than trying to repair an empty server.

5. Pass tmux options deliberately

The byobu-tmux synopsis accepts tmux options. This makes a separate socket useful when you need an isolated temporary server:

$ byobu-tmux -L training-session

Here -L is a tmux option, not a Byobu configuration setting. Tmux creates the socket below its per-user temporary directory, normally under /tmp. A different socket name keeps this server separate from the default one. Reattach to it explicitly:

$ byobu-tmux -L training-session attach

Keep socket names simple and private. Do not put secrets in a command line, because arguments can be exposed through process inspection. If you need a completely explicit socket location, tmux also supports -S with a full path, but the directory and its permissions then become your responsibility.

6. Understand where configuration is read

Byobu uses $XDG_CONFIG_HOME/byobu when $XDG_CONFIG_HOME is set, and otherwise $HOME/.byobu. The tmux backend reads Byobu's tmux configuration there, including its display and status settings. Tmux itself normally reads /etc/tmux.conf first, then a user file at ~/.tmux.conf, $XDG_CONFIG_HOME/tmux/tmux.conf or ~/.tmux.conf, depending on what exists.

This split explains a common distraction: changing ~/.tmux.conf may not change a Byobu status line, while changing Byobu's files may not affect a standalone tmux command. Check the active backend and configuration path before editing anything:

$ printf 'XDG_CONFIG_HOME=%s\n' "${XDG_CONFIG_HOME:-unset}"
$ printf 'BYOBU_CONFIG_DIR=%s\n' "${BYOBU_CONFIG_DIR:-unset}"
$ ls -ld "${XDG_CONFIG_HOME:-$HOME/.config}/byobu" "$HOME/.byobu" 2>/dev/null

The last command may list only one directory or neither. That is not a failure: it reflects which configuration location exists on this account. Back up a file before changing it. To undo a local Byobu colour change, remove the relevant user file and start a new session; the system defaults then apply. Removing a file is destructive, so inspect its contents first and keep a copy until the new display is verified.

7. Recover from the common failures

If byobu-tmux says that tmux is missing, verify the backend directly:

$ command -v tmux
$ tmux -V

If the command returns no path, ask your system administrator to install the package that provides tmux. Do not edit the wrapper to point at an arbitrary binary.

If reattachment fails, check whether you are using the same user and socket name. A session started with -L training-session is not visible through plain byobu-tmux list-sessions. If the session has already been killed, its shells cannot be recovered from tmux. Restart the command and restore work from your normal files or service procedures.

If a configuration error appears as the first session starts, tmux continues processing the rest of its configuration after reporting the error. Move the suspect user configuration aside only after making a backup, then start a fresh session to isolate the problem. Do not delete system configuration while diagnosing an interactive tool.