When the bench misbehaves

2.1 Nothing opens at all — Docker is asleep

Every app on the bench is a container, and containers only exist while Docker is running. After a restart, Docker is often not up yet — and then no address on the bench answers.

Recognise the "everything is dead" signal and fix it with the icon you already have.

in a terminal. If it prints an error about the daemon, Docker is not running — that is the whole diagnosis.

1. The signal. localhost:8080 does not load at all — not a broken page, no page. Every other address is the same.
2. The fix. Double-click the "Heidelberg AI Bench" icon. It wakes Docker, waits for it, and starts your apps. That is what it is for.
3. If Docker itself will not start. Open Docker Desktop by hand and watch the whale: while it animates, Docker is still starting, and the first start after an update takes a minute or two. On Windows, Docker asks for one restart after some updates.

• You'll see localhost:8080 loads again and the tiles come back one by one as each app finishes starting.
• Takeaway No page at all means Docker, not the bench. Start it with the icon and wait.

2.2 "port is already allocated"

The apps take fixed addresses: 8080 for the dashboard, 5678 for n8n, 3001 for AnythingLLM, 4000 for the gateway, 5001 for Dockge. If another program on your machine already holds one, that app cannot start and Docker says so in those words.

Find what holds the port and decide which of the two moves.

in a terminal — it shows which bench container claimed which port, and which one is missing from the list.

1. Read Docker's own words. The bench passes them through unchanged, because "port is already allocated" is the entire answer to most failed starts.
2. Find the other program. On a Mac or Linux: lsof -i :5678. On Windows: netstat -ano | findstr :5678, then look the process id up in Task Manager. A second n8n, a stray Grafana or an old bench are the usual suspects.
3. Decide who moves. If it is an old copy of a bench app, stop it — docker rm -f . If it is something you need, change the app's port instead: its compose.yaml lives in stacks//, and the left-hand number in "5678:5678" is the one on your machine.
4. Then start it again from the dashboard, or from Dockge at localhost:5001 if you edited the compose file.

• You'll see The tile turns green and the address answers.
• Takeaway A port is held by exactly one program. Either free it or move the app — never both.

2.3 Everything crawls — the machine is out of memory

Each app holds memory the whole time it runs, whether you use it or not. The dashboard prints what each one costs, and the sum against what your machine has.

Buy back memory in ten seconds instead of restarting the laptop.

1. Look before you guess. The dashboard shows a memory figure per app and a total for the machine. On a normal bench the whole set idles at about 1.2 GB; the model adds a couple of gigabytes while it answers.
2. Stop what you are not using. Press Stop on a tile. The app disappears from memory and its data stays on disk — starting it again later is a few seconds.
3. The model is the big one. If you are working with a cloud provider that afternoon, stop the model app: nothing else needs it, and it is the largest single tenant.
4. The store already warns you. Every tile prices itself against the memory actually free before the install, not after — a 1.2 GB app on 800 MB free is a tile that tells you so.

• You'll see The total drops immediately and the rest of the bench is responsive again.
• Takeaway Stopping an app is free and reversible. Reach for it before anything more drastic.

2.4 One app is broken — reset just that one

Remove on a tile stops the container and deletes it — and nothing else. The named volume with your data stays, and so does the folder in stacks/ that describes how the app was set up. Installing it again lands you back where you were.

Fix a single misbehaving app without touching the rest of the bench.

1. First, look at what it says. Dockge at localhost:5001 shows each stack's live log. Most "broken" apps are one clear line — a wrong key, a port, a permission.
2. Then Remove, then install again. From the app's gear page. This replaces the container and keeps the data.
3. Wrong model or wrong key? That is not a broken app: change the provider once on the dashboard and every app follows. Nothing is reconfigured per app.
4. Really start over? Removing the app's volume is the deliberate act that deletes its data — docker volume rm . It is not part of Remove on purpose.

• You'll see The tile comes back green with your documents, workflows or settings intact.
• Takeaway Remove is about the container, never about your work. Deleting data is a separate, explicit step.

2.5 Update the bench, or remove it completely

The kit changes several times a day. Your copy is a folder you unpacked once — so both launchers check the published version before doing anything else, and re-download when yours is behind.

Stay current without reinstalling, and leave no trace when you are done.

1. Updating is just starting it. The desktop icon compares your copy against the published one and fetches the newer one when there is one. Your configuration and data are untouched.
2. Changing your mind about the provider is the other launcher — the full setup, which asks the question again and rewrites only configuration.
3. Removing the bench is three things, in this order: stop every app from the dashboard, delete the HeidelbergBench folder in your home directory, and — if you want the disk space back — docker volume prune for the data and docker image prune -a for the images.
4. Docker itself is yours to keep. It is a general tool and other things may use it. Uninstall it separately, if you want to.

• You'll see After an update the page looks the same and behaves better. After a removal, docker ps lists nothing of the bench.
• Takeaway Update by starting it. Remove by stopping, deleting the folder, and pruning what you no longer want.