// OPENBOX DOCS

Getting started

Import one local executable and launch it safely.

This path is for a first run with a local executable folder. Use a disposable folder if you are testing, so the experiment cannot touch real games.

The goal is a full loop: install, import one game, see it in the library, launch it, and confirm the session was recorded. It also proves the data model works: the entry you import is the entry that launches, and the session you play is the session that appears in history.

Before you start

Follow Installation and start the Web UI. You should see the three-column workspace: filters on the left, an empty cover grid in the center, and the detail pane on the right.
Make one folder containing a single executable .sh file. For a realistic first test, use a short script like this:

#!/bin/bash
echo "OpenBox launch works" && sleep 3

Make it executable (chmod +x). A non-executable file with no launch command is the most common first-launch failure, and the app now reports it explicitly instead of silently failing.

The Web UI workspace looks like this once you have a library entry — filters on the left, the cover grid in the center, and the selected game's detail pane on the right:

Steps

1
Install and start the Web UI. From the AppImage, Flatpak, or source as described on the Installation page. When the library is empty, the welcome wizard appears; you can close it and use the topbar buttons, or start from its Import a ROM or game folder step.
note
You should see: An empty cover grid in the center, no cards in any view. The welcome wizard suggests importing a folder or scanning for emulators. If the browser did not open, look at the terminal — OpenBoxGL printed http://127.0.0.1:PORT/?token=.... Open that URL manually.
2
Choose Import Folder. Click Import Folder in the topbar (or the wizard's folder step). The web UI asks for the absolute path of the folder to import. Because the browser cannot browse your filesystem, you type or paste the path, for example /home/you/test-game.
note
You should see: A text input field labeled "Folder path". Type or paste the path and press Enter. There is no file picker — you must provide the full path.
3
Select a folder containing one executable .sh file. The import scans the folder for supported files (.sh, .appimage, .exe, .iso, .rom, common console extensions, and archives), checks each against existing library entries so nothing is duplicated, and adds what is new. If the import also finds a known emulator on your system, it may offer to install or configure a profile; with a plain .sh file, nothing extra is needed.
note
You should see: Either a brief notification ("X found, Y added") or the imported card appearing instantly in the grid. If zero files were added, re-check the path — the importer prints a specific error when no recognized files exist. Existing entries are never duplicated.
4
Confirm the imported title in the library. A grid card appears with the game's name. The detail pane on the right shows the launch path, the platform, and empty metadata fields that you can later fill from the LaunchBox Games Database or edit by hand.
note
You should see: One card in the grid whose label matches your file's name or folder name. Selecting it opens the detail pane showing a PLAY button (greyed out until a platform profile is set), the file path, and an empty Emulator row. No artwork exists yet — you'll add that later.
5
Open the game card to view its details. Selecting the card opens its detail pane: the launch command, the launch profile for its platform, per-game overrides, save locations, and history stay together here. This is also where you review or fix a launch failure.
note
You should see: A hero area (empty, no background art), the game name, a PLAY button with a Find metadata / Edit metadata row below it. On the right side, an Information section showing "Source" (folder import), the file path, and no Play Time or History entries yet.
6
Select PLAY and watch the session result. PLAY runs the game's launch command without a shell. For a .sh file, that means bash <path>. A lifecycle overlay appears ("Starting"), the process starts, and after it exits, the overlay reports the outcome: either "Session ended, play time and history were saved" for a clean exit, or the actual exit code for a failure. The session is recorded with start time, duration, and exit status.
note
You should see: If the path or permissions are wrong, PLAY stays greyed-out with a message naming which part is missing. If correct, a small "Starting…" banner appears at the top, then "Session ended" with the play time and a link to the History view. The game card's "Play count" increments to 1 and "Play time" grows to match the script's duration.

Expected result

One library entry, visible as a card in the grid.
One completed session in the History view with a non-zero-free exit code and a play time of a few seconds.
play_count incremented and playtime_seconds grown on the game card.

ROMs are the deliberate exception: they require a configured platform emulator profile before they can launch. An .nes file with no emulator profile produces a launch validation error until you set one, by design, so nothing half-configured ever runs.

Common failures and recovery

The game is missing after import

Check the folder path you typed. The import resolves ~ but does not guess; a wrong path imports nothing and reports it. Re-run Import Folder with the correct absolute path. Existing entries are never duplicated, so re-importing the same folder is safe.

PLAY is disabled or launch fails with a validation error

Open the game detail view. The message tells you which part is missing:

"has no launch command and its file is not executable": make the file executable (chmod +x), or set a launch command for the platform in Emulator profiles, or set one per game under Edit game. This check runs before anything spawns, so no half-started process is left behind.
"The configured path no longer exists": the imported file was moved or deleted. Point the game at the new path under Edit game, or re-import the folder.
"Set a launch command for the platform": the platform has no profile. See Emulators and launching.

The session reports a failure

An immediate exit with a non-zero code reports "Session failed" with the exit code and a hint to check the launch command and emulator install. If your test script exits 0, the session is recorded as a normal end. If you never see the lifecycle overlay at all, check that the browser tab still holds the current token (closing and reopening the tab on the same server is fine; starting a second server instance opens a new token, and the old tab keeps working because the token lives in the URL).

The browser did not open

Run the entry point from a terminal. OpenBoxGL prints http://127.0.0.1:PORT/?token=... and you can open that URL yourself. The server binds to loopback only; nothing is exposed to the network.

I imported the wrong folder

Removing an entry is safe: select the game and use Remove game in the detail pane. Removal can optionally delete that game's media files, but it never deletes your game files on disk.

Data safety during this walkthrough

Every change the walkthrough makes is contained in the data directory:

The import appends one entry to library.json.
The launch appends one session to the history in the same file.
Writes are atomic, owner-only, and go through the last-known-good .bak copy, so an interrupted write cannot corrupt the library.

Nothing is sent anywhere: no account, no telemetry, and no network traffic unless you click a metadata or media action. If you used a disposable folder, removing the entry leaves the data directory back where it started.

Next steps

Importing for Steam, Heroic, Lutris, ROM folders, and arcade sets.
Emulators and launching for command tokens and platform profiles.
Interfaces and data for where every file lives.
Metadata and media for enrichment after the first import.