Getting Started

This page walks through one full loop: install OpenBox, import a test game, launch it, and check the session in History. The test uses a disposable folder. You can remove the test entry afterward without touching real games.

Before you start

1. Install OpenBox for your system.
2. Create a test folder that contains one launchable file.

On Linux, the test file is a .sh script. These commands create one:

mkdir -p ~/openbox-test
cat > ~/openbox-test/test-game.sh <<'EOF'
#!/bin/bash
echo "OpenBox launch works" && sleep 3
EOF
chmod +x ~/openbox-test/test-game.sh

On Windows, use any small .exe file on your machine. For macOS, see the macOS guide.

Steps

1. Start OpenBox. On Linux, run openbox. On Windows, double-click openbox.cmd, or open OpenBox from the Start Menu. On macOS, open OpenBox.app from ~/Applications, or run openbox in a terminal. When the library is empty, the Set up your library dialog opens. Close it to use the Add games menu instead.
2. Scan the test folder. Open Add games, choose Scan a folder…, and select ~/openbox-test. The native window shows a folder picker. In browser mode (openbox --web), type the full path, such as /home/you/openbox-test. OpenBox adds the launchable file to the library. Scanning the same folder again does not create duplicates.
3. Find the card. The test game appears in the grid. Select it to open the detail pane, which shows the launch command, the platform, and the metadata fields.
4. Press PLAY. A starting overlay appears. When the process exits, the overlay reports either "Session ended, play time and history were saved" or the exit code of a failed run.
5. Check History. The session appears in the History view with its start time, duration, and exit status. The card's play count and play time update.

What you should see

One library entry, one completed session in History, and an updated play count and play time on the card.

To remove the test entry, select the game and choose Remove game in the detail pane. Removal can also delete the game's media files. It never deletes game files on disk.

ROMs need an emulator first

ROM files need an emulator profile before they can launch. Without one, OpenBox shows a Launch check notification. This is intentional, so nothing half-configured runs. The emulator guide covers profiles.

Next steps

Guide	Covers
Importing	Steam, Heroic, Lutris, Faugus, ROM folders, arcade sets, and Gameyfin
Emulators and launching	Profiles, command tokens, archives, and dependency checks
Big Box and handhelds	Controller layouts, gamescope, and TDP profiles
Sessions, saves, and backups	History, save discovery, and versioned backups

See also: Troubleshooting and FAQ.