Launch or Reconnect Byobu with byobu-launcher

byobu-launcher is the quiet gatekeeper that decides whether Byobu starts when you log in, and it refuses far more often than people expect. This guide shows you how to run it, read its safety checks, and switch automatic launching off and back on without losing a session. 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. Nothing in the normal workflow needs sudo. This guide uses the package's default backend on this machine, tmux, but the launcher still works with whatever backend your Byobu configuration selects.

1. Confirm the installed command

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

$ 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 point at the same launcher manpage on this installation. Prefer the longer name in scripts, so the next person reading them can see what it does.

2. Launch or reconnect from an interactive terminal

Run the launcher as your normal user:

$ byobu-launcher

• It hands control to Byobu. Byobu starts a new session, or reconnects to an existing detached one when it finds one.
• Never prefix it with sudo. The session belongs to your user; a root-owned home directory or root-owned Byobu files can make later starts fail or expose another user's session data.
• Detaching is not stopping. Use Byobu's detach key sequence for your backend, normally Ctrl-a d on tmux unless you have changed the escape key. Run byobu-launcher again to reconnect.

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

Nothing listed can mean two different things: the first launch exited rather than detached, or your configuration selects a different backend. Check which backend Byobu is configured to use before reaching for that backend's own status command.

3. Understand the launcher's safety checks

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

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

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

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: that requests the exact 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 a 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 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 over both:

$ 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

mkdir and touch operate inside your home directory and need no elevated privileges. If BYOBU_CONFIG_DIR points somewhere you cannot write, fix that user configuration rather than reaching for 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.