Start the desktop launcher¶

Most users do not need the launcher

Adaptive Learner runs directly in the browser - no installation, no Docker, no launcher: astrapi69.github.io/adaptive-learner. The desktop launcher is only for you if you want to self-host the app or run backend features (server mode, local sync) locally.

The desktop launcher is the easiest way to run Adaptive Learner with its own backend on your own machine. It is a small window that does everything else for you: it checks that Docker is running, downloads the ready-built app image from GitHub's registry on the first start (about 110-120 MB, a few minutes on a normal connection - nothing is built on your machine), starts the container, and then opens the app in your browser at http://localhost:8501. From the same window you can also stop the app, change the port, update, or uninstall everything.

The three ways to install¶

Way	For whom	What happens
Launcher (standard)	Everyone	Downloads the published image from `ghcr.io/astrapi69/adaptive-learner` and runs it. This page.
Registry-free (archive)	Machines without registry access	Download the image archive for your processor from the same release page as the launcher, place it next to the launcher's data - it is loaded INTO the pinned reference instead of being pulled. Archive and launcher must come from the same release; a mismatched version fails hard with the file named.
From source (developers)	Self-builders	Clone the repository, then `install.sh` or the compose stack. Builds locally; unchanged by this release.

The downloaded program deliberately has no tray icon: closing the window always quits the launcher there. The app itself keeps running in Docker and is right back on the next start. Only a source installation can add the tray icon, and then closing minimizes to it instead of quitting.

The port defaults to 8501 and can be changed in the launcher window; if it is taken, the launcher falls back to a free port. If you use browser storage mode, changing the port also changes where your data lives - see Changing the port before you do it.

Who can reach the app¶

By default the app is reachable only from this computer (127.0.0.1). That is deliberate: it has no login, and it holds your AI provider keys. Visible on the network, any device in the same network - an office LAN, a hotel or conference WLAN - could simply open and use it.

Reaching the app from another device, say your phone on your own WLAN, is still possible but a deliberate choice: set ADAPTIVE_LEARNER_BIND_ADDRESS=0.0.0.0 in the .env. Only do that in a network you trust, and remember that everyone in it then has the same access you do.

Prerequisite: Docker - the launcher checks it itself¶

The launcher requires a running Docker, because the app itself runs in a container. You do not need to verify anything manually: on start the launcher itself checks whether Docker is installed and running, also finds a Docker running under a different Docker context (such as Docker Desktop for Linux or rootless Docker), and shows a clear message with a fix when something is missing. If Docker is not installed at all yet: Install Docker Desktop.

The launcher's messages and what they mean:

Message	Meaning	Fix
"Docker is not installed (docker not in PATH)."	The `docker` command was not found.	Install Docker Desktop. The launcher shows the install link directly.
"Docker is installed but not started." or "Docker is not running. Checked context '...' (...): ..."	The Docker service is not running right now; the detailed form names the probed context, the socket, and Docker's original error.	Click the "Start Docker" button in the launcher (Linux) or open Docker Desktop (macOS/Windows), then "Retry".
"Docker is installed, but you don't have permission."	Your user is not in the `docker` group (Linux).	The launcher shows the exact command; log out and back in afterwards.
"Docker is not responding."	Docker is most likely still starting up (typical right after opening Docker Desktop).	Wait a moment, then "Retry".
"Docker is running via context '...' - the active context was unreachable, the launcher connected automatically."	Informational only: Docker ran under a different context, the launcher found it and uses it.	Nothing to do.
"Docker Desktop is installed but not in PATH."	The Docker Desktop app is there, but its command-line tool is not (yet) reachable.	Start Docker Desktop via the launcher button and wait briefly.

The context detection with detailed messages ships with the launcher version following docker-app-launcher#26; older versions show the shorter messages from the same table.

Download¶

All three launchers ship with every release at github.com/astrapi69/adaptive-learner/releases:

Platform	File	Checksum
Linux	`adaptive-learner-launcher`	`adaptive-learner-launcher.sha256`
macOS	`adaptive-learner-launcher-macos.zip`	`adaptive-learner-launcher-macos.zip.sha256`
Windows	`adaptive-learner-launcher.exe`	`adaptive-learner-launcher.exe.sha256`

What is verified, and what is not¶

Every one of these is started once while it is being built, on exactly the operating system it is meant for. So it is established that it starts - on Linux, on Windows, and on macOS on Apple Silicon. The app image is verified per release: an anonymous download (no login) and a real start with a health check, separately for both processor types (Intel/AMD and ARM), on machines of that type. Not yet measured is the registry download on very old Docker engines (20.10-era); the engine chain itself is proven on such an engine against a different registry, and the GitHub-registry measurement is tracked upstream.

What is not established is how your operating system reacts to a downloaded file: the programs carry no paid signature, so macOS warns on first open ("unidentified developer") and Windows shows the SmartScreen notice. That is a warning, not a defect - how to confirm it once is under macOS and Windows below. Verify the checksum first; it is more reliable evidence than any dialog.

Linux¶

Verify the checksum (both files in the same folder):
```
sha256sum -c adaptive-learner-launcher.sha256
```
Set the execute permission. Browser downloads always strip it from the binary, so this step is always needed:
```
chmod +x adaptive-learner-launcher
```
Start it, easiest from the terminal:
```
./adaptive-learner-launcher
```
Double-clicking in the file manager can work too, depending on your environment; GNOME/Nautilus requires "Allow executing file as program" under Properties > Permissions. The terminal start has the advantage that you see error messages directly.

Known pitfalls:

"Permission denied": step 2 was skipped (chmod +x).
GLIBC error on start: the binary is built on Ubuntu 22.04 and needs glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+, Fedora 36+). On older distributions run the app via install.sh or Docker Compose directly instead.
App not reachable in the browser: if the browser does not open automatically, open http://localhost:8501 manually (or the port shown in the launcher window). By default the app listens only on 127.0.0.1, so it is reachable only from this computer; other devices reach it only after you deliberately enable network access - see "Who can reach the app" above.

macOS¶

Verify the checksum and unpack the ZIP:

shasum -a 256 -c adaptive-learner-launcher-macos.zip.sha256
unzip adaptive-learner-launcher-macos.zip

On first open, macOS blocks the program. Depending on your macOS version the dialog offers only "Move to Trash" and "Done" - no Open button. This is not an error and not a defect in the program: Adaptive Learner is not notarized by Apple, which requires a paid developer account.

How to open it anyway:

1. Dismiss the dialog with **Done** (not Move to Trash).
2. Open **System Settings > Privacy & Security** and scroll down.
3. There you will find the note that the program was blocked, with
   an **Open Anyway** button. Click it and confirm in the next
   dialog.

Every later start opens without asking.

In this situation the checksum from step 1 is your real safeguard: the system cannot confirm where the file came from - a matching checksum can.

Footnote for technical users. xattr -d com.apple.quarantine <file> also removes the block from the command line. It is deliberately NOT the route above: teaching people to clear a malware warning with a terminal command is exactly what an attacker asks of a victim. Use it only if you understand what it does and have verified the checksum.

Windows¶

Verify the checksum (PowerShell, both files in the same folder):

Get-FileHash .\adaptive-learner-launcher.exe -Algorithm SHA256
Get-Content .\adaptive-learner-launcher.exe.sha256

The two hash values must match.

Double-click adaptive-learner-launcher.exe. On the first start SmartScreen warns ("Windows protected your PC"): click More info, then Run anyway.

If something goes wrong¶

The launcher itself shows a notice dialog when Docker is not running and offers to start Docker Desktop.
The first start downloads the app image; the step checklist in the launcher window shows the progress, and every downloaded megabyte is visible - never a silent long wait. Later starts are fast and work offline.
--doctor on the command line prints one readiness report: configuration, Docker, tools, port, and state - all preconditions in one pass.
While the app is running you can always reach it at http://localhost:8501 (or your changed port); the "Open in browser" button in the launcher does the same.