Start a Standalone Openbox Session with openbox-session

You will start Openbox as a lightweight X session and add user-level programs that launch with it. This guide uses the installed Openbox package version 3.6.1-12build5. Allow about 15 minutes if X already works and you only need a small autostart file.

This is a session launcher, not a remote shell command. You need a working X display and the openbox package. Do not run it from a text-only console and expect a desktop to appear there. It does not provide a desktop environment, panel, notification service or session manager for you.

1. Check the installed command

Confirm which executable will be used and record the package version:

$ command -v openbox-session
/usr/bin/openbox-session
$ dpkg-query -W -f='${Version}\n' openbox
3.6.1-12build5

Your version may differ. Keep the version with your notes because startup details can change between distribution packages.

The package also provides x-session-manager as an alias. It resolves to the same launcher on this machine, so a display manager may invoke either name:

$ readlink -f /usr/bin/x-session-manager
/usr/bin/openbox-session

2. Launch it from your X session

If you use startx, put the launcher in ~/.xinitrc. The final command should normally replace the shell process:

exec openbox-session

If a graphical login manager offers an Openbox session entry, select the entry that names the session rather than an entry that only starts the window manager. The official Openbox documentation describes openbox-session as the standalone option, without GNOME or KDE.

Checkpoint: after logging in, the Openbox root menu should respond to a right-click on the desktop. A bare, empty desktop is possible: Openbox manages windows, but does not automatically install a panel or launcher.

Do not add command-line options to this launcher. The installed script accepts no arguments and prints this syntax when given one:

$ openbox-session --help
Syntax: openbox-session

See the openbox-session(1) manpage for help.

3. Add a user autostart file

Create the directory and file as your ordinary user. This changes only your session, so it does not need sudo:

mkdir -p "$HOME/.config/openbox"
editor "$HOME/.config/openbox/autostart"

Use a real editor in place of editor. Start each long-running graphical program in the background:

# Start programs for this Openbox session.
xsetroot -solid grey &
# tint2 &
# nm-applet &

Replace the commented examples only with programs that are installed on your system. The trailing & matters. Without it, the script waits for that program to finish and later startup lines do not run. The example /etc/xdg/openbox/autostart is a useful local reference:

$ sed -n '1,120p' /etc/xdg/openbox/autostart

Checkpoint: syntax-check the file before logging out:

$ sh -n "$HOME/.config/openbox/autostart"
$ printf '%s\n' "$?"
0

4. Understand which startup file runs

The manpage says the user file ~/.config/openbox/autostart is used when it exists, otherwise the system file /etc/xdg/openbox/autostart is used. The installed 3.6.1 helper is more specific than that wording: it runs the system file first and then the user file. It also accepts the corresponding .sh names, and then runs XDG autostart entries if the helper is available.

That distinction matters if you are trying to suppress a distribution startup command. Adding a user file does not suppress the system file in this package. Inspect both before troubleshooting duplicate panels or settings:

$ ls -l /etc/xdg/openbox/autostart "$HOME/.config/openbox/autostart" 2>/dev/null
$ test -x /usr/lib/x86_64-linux-gnu/openbox-autostart && echo helper-present

The launcher also reads environment files before starting Openbox. For user-specific variables, use ~/.config/openbox/environment. Keep shell assignments there, and do not put commands that must be started as applications in that file.

5. Recover from a bad autostart change

If the session becomes unusable, switch to another terminal with the usual X terminal shortcut, log in on a text console, or edit the file from another session. Rename the user file to disable it without deleting your work:

$ mv "$HOME/.config/openbox/autostart" "$HOME/.config/openbox/autostart.disabled"
$ mv "$HOME/.config/openbox/environment" "$HOME/.config/openbox/environment.disabled" 2>/dev/null || true

Log in again after making that change. If only one program is failing, restore the file and comment out that command instead. Do not edit /etc/xdg/openbox/autostart as a first response: it is a system-wide file and changing it requires elevated privileges and affects other users.