Start or Reconnect Byobu Safely with byobu-launcher

You will finish with a reliable way to invoke Byobu from a login shell, recognise when the launcher deliberately does nothing, and disable automatic launching without losing your Byobu sessions. The installed package here is byobu 6.11-0ubuntu1.1, with Byobu reporting version 6.11. The launcher is a small wrapper around byobu, not a separate multiplexer.

Allow about ten minutes. You need an interactive terminal, an ordinary user account, and the byobu package. No command in the normal workflow needs sudo. This guide uses the package's default backend on this machine, which is tmux; the launcher can still use whatever backend your Byobu configuration selects.

1. Confirm the installed command

Check which launcher will run and record the package version. These are read-only commands:

$ command -v byobu-launcher
/usr/bin/byobu-launcher
$ dpkg-query -W -f='${Package} ${Version}\n' byobu
byobu 6.11-0ubuntu1.1
$ byobu --version
byobu version 6.11

The aliases byobu-launch and byobu-launcher refer to the same launcher manpage on this installation. Prefer the longer name in scripts and documentation so its purpose is obvious.

2. Launch or reconnect from an interactive terminal

Run the launcher as your normal user:

$ byobu-launcher

The installed launcher hands control to byobu. Byobu then starts a new session or reconnects to an existing detached session when one is available. The session belongs to your user, so do not prefix this command with sudo. A root-owned home directory or root-owned Byobu files can make later starts fail or expose another user's session data.

To leave the session running while returning to the shell, use Byobu's detach key sequence for the selected backend. On the default tmux backend, that is normally Ctrl-a d unless you have changed the escape key. Detaching is not the same as stopping the session. Run byobu-launcher again to reconnect.

$ byobu list-sessions
# The exact session listing is host-specific.

If there is no session to list, the first launch may have exited rather than detached, or your configuration may select a different backend. Use the backend's own status command only after checking which backend Byobu is configured to use.

3. Understand the launcher's safety checks

byobu-launcher is designed for login environments, where blindly starting a multiplexer can create confusing nesting. It checks several conditions before it launches:

• If the current user does not own $HOME, it exits instead of risking configuration and runtime files owned by somebody else.
• If the Byobu configuration contains disable-autolaunch, it exits without starting Byobu.
• With TERM=dumb, it exits because the terminal cannot provide the interactive display Byobu needs.
• When TERM already indicates a screen-like terminal, it avoids launching another session in an ordinary SSH connection, because that can produce an unwanted nested or looping login.

An exit status of 1 therefore does not always mean that Byobu is broken. It can mean that the launcher correctly declined to start. The wrapper has no separate diagnostic option, so inspect the environment and configuration rather than repeatedly retrying it.

For example, this deliberately non-interactive test should not start Byobu:

$ TERM=dumb byobu-launcher
$ printf 'launcher status: %s\n' "$?"
launcher status: 1

Do not use TERM=dumb as a workaround for a failed interactive launch. It requests the branch that refuses to start.

4. Disable automatic launching temporarily

If your shell or login profile invokes the launcher and you need a plain shell for one session, create the marker file in Byobu's configuration directory. This changes only whether the wrapper auto-launches Byobu; it does not kill or delete any existing session.

First identify the directory that the installed scripts use. If ~/.byobu exists, it is used; otherwise the normal XDG location is ~/.config/byobu. The explicit environment variable BYOBU_CONFIG_DIR takes precedence:

$ if [ -n "$BYOBU_CONFIG_DIR" ]; then
    config_dir=$BYOBU_CONFIG_DIR
elif [ -d "$HOME/.byobu" ]; then
    config_dir=$HOME/.byobu
else
    config_dir=${XDG_CONFIG_HOME:-$HOME/.config}/byobu
fi
$ printf 'Byobu configuration: %s\n' "$config_dir"

$ mkdir -p "$config_dir"
$ touch "$config_dir/disable-autolaunch"
$ TERM=xterm byobu-launcher
$ printf 'launcher status: %s\n' "$?"
launcher status: 1

The mkdir and touch commands operate in your home directory and do not require elevated privileges. If BYOBU_CONFIG_DIR points somewhere you cannot write, fix that user configuration rather than using sudo.

5. Re-enable the launcher and recover from a false start

Removing the marker is the undo operation. Confirm the exact path first, then remove that one file:

$ test -f "$config_dir/disable-autolaunch" && printf '%s\n' 'auto-launch is disabled'
$ rm -- "$config_dir/disable-autolaunch"
$ test ! -e "$config_dir/disable-autolaunch" && printf '%s\n' 'auto-launch is enabled'

If the launcher still returns 1, check the two conditions most often mistaken for a Byobu failure:

$ id -un
$ stat -c '%U %n' "$HOME"
$ printf 'TERM=%s\n' "$TERM"
$ printf 'BYOBU_CONFIG_DIR=%s\n' "${BYOBU_CONFIG_DIR:-not set}"
$ test -e "$config_dir/disable-autolaunch"; printf 'marker status: %s\n' "$?"

The home-directory owner should be your login account, the terminal should be interactive rather than dumb, and the marker test should return 1 when the marker is absent. If the launcher is being called from inside another multiplexer or through SSH, start byobu manually only after deciding whether nesting is actually what you want.