- Run the installer.
Windows warns about an unknown publisher, because the file is unsigned. The Desk installs for your user only and needs no administrator rights.
- Let it set up Podman.
On the last page leave “Set up Podman now” ticked. A window shows
desk setupinstalling and starting Podman; Windows may ask for permission. The setup accepts the terms of Windows’ package manager for you and says so. Press a key when it has finished. - Start an app in the window.
The Desk opens its window; later you find it in the Start menu or with a click on its icon next to the clock. Press “Install and open” on n8n or Gitea. The first start downloads the app and takes a few minutes.
Quick start, commands, and recovery
Make Desk work
for you.
Start with the quick start for your system. Below it you find every command, the menu next to the clock, where your data is, and what to do when something does not start.
Start here · 0.2.0-alpha.15
Three quick starts.
- Install Podman.
Use the installer from podman.io, or
brew install podman. - Unpack the archive.
Open the Terminal in the unpacked folder. First, once:
xattr -d com.apple.quarantine desk desk-tray. The programs are not notarized by Apple, and without this line macOS stops them at once; the Terminal then says only “Killed: 9”. Then./desk setupprepares and starts Podman. - Start an app.
./desk open n8nstarts n8n and opens it in your browser. The archive also holdsdesk-tray, the window and the menu:./desk-tray --window. The window opened on a Mac in our test, but nobody has looked at it or at the menu on a Mac yet.
- Install Podman.
Ubuntu and Debian:
sudo apt install podman. Fedora:sudo dnf install podman. - Unpack the archive.
Move
deskto a folder on your PATH, for example~/.local/bin.desk doctorshows whether Podman was found. - Start an app.
desk start n8nprints the address when n8n answers;desk open n8nalso opens the browser. There is no menu program for Linux yet.
A Windows computer without WSL, the part of Windows that Podman needs; a Mac or Linux computer without Podman; Docker instead of Podman. If you hit one of these, desk doctor and desk setup say what they found.
After “Install and open”
Your first ten minutes.
Each app opens in your browser, at an address on your own computer. The account you make there exists on this computer only. From version 0.2.0-alpha.8 an app’s card has “First steps”, which leads here. We went through these first screens on our Windows test computer on 12 October 2026; an app’s own screens change with its version.
n8n
- What you see first. “Set up owner account”: an e-mail address, your name and a password of at least 8 characters with a number and a capital letter. n8n does not check the address and sends nothing to it. Write the password down: on your computer n8n has no way to mail you a new one.
- Three offers you may skip. n8n asks about your company (“Get started” goes on without answers), offers a licence key for your e-mail address (“Skip”) and offers an assistant that needs a model you pay for (“Set up later in Settings”). You need none of them.
- A model from Ollama. From 0.2.0-alpha.13 n8n reaches the Desk’s Ollama at
http://ai-lab-ollama:11434while Ollama runs; in an OpenAI node the address ishttp://ai-lab-ollama:11434/v1, with any word as the key. Opening n8n does not start Ollama: start it on its card, or fetch a model withdesk model qwen2.5:3b, which starts it first. T05-L02 builds a workflow with it. The Mac archive is still 0.2.0-alpha.12, which keeps the two apart. - A first task. “Build a workflow” opens the editor. The curriculum’s first automation is a form that fills a table: T05-L01 · Your First Automation: Build It, Break It, Switch It Off. That lesson uses n8n’s cloud. The Desk’s n8n has the same overview with “New data table”; we have not built the lesson’s workflow in it. One difference is certain: a workflow here runs only while your computer and n8n are running.
- Starter workflow. n8n-first-workflow.json counts three example agar plates and marks the one with more than 300 colonies for a second look. In the editor, the menu with the three dots, “Import from File”, then run it. Change the 300 or a count and run it again: that is the lesson’s “break it”. It needs no account anywhere and no internet. We imported and ran it in the Desk’s n8n version with n8n’s own command line; we have not clicked the import in the menu.
- Keep your work. In the editor, the menu with the three dots has “Download”. It saves the workflow as one file, which you can keep, show to your teacher or import into another n8n. We have not clicked this in the Desk’s version.
- The clock. A new installation uses German time. One made before 0.2.0-alpha.8 uses UTC: “Open the data folder”, then in
apps/n8n/.envsetGENERIC_TIMEZONE=Europe/Berlin, then “Stop” and “Open”. - In the curriculum. T05-L02 · Put AI in the Middle of a Workflow, and Check Every Answer, T05-L05 · Keep Your Automations Running for Months, and After You Leave and T11-L02 · A Local Model Your Tools Can Call.
Gitea
- What you see first. Gitea’s own page “Initial Configuration”. Leave every field as it is and scroll to the end.
- Make the administrator account there. Open “Administrator Account Settings” and fill in a user name, an e-mail address and a password, twice. Then press “Install Gitea”. The page calls this account optional. In the Desk it is not: without it Gitea answers “You cannot disable user self-registration without creating an administrator account.” Fill it in then and press the button again.
- After a few seconds you are signed in and see your empty dashboard.
- A first task. “+” at the top, “New Repository”, a name, tick “Initialize Repository”, then “Create Repository”. Your repository is at
http://127.0.0.1:33009/<your name>/<repository>. - Starter repository. gitea-starter.zip holds a prompt, three test cases, a change log and a README that walks through changing the prompt on a branch with a pull request, as in T03-L04. Unpack it. Make a new repository without ticking “Initialize Repository”, then “Upload File” and drop the four files. We have not tried this upload.
- Keep your work. A repository can be fetched with Git,
git clone http://127.0.0.1:33009/<your name>/<repository>.git, or as a ZIP file from the repository’s page. Both addresses answered in our test; we did not rungit cloneitself. - Only your computer. The address works on this computer and nowhere else. Nobody else can sign up or push to it.
- In the curriculum. T03-L04 · Release Prompt Changes Through Review, Tests and a Way Back and T08-L05 · Run Automatic Checks, an AI Reviewer and Releases You Can Roll Back. Both describe an institute’s Gitea that several people share; yours is for practising alone.
Open WebUI
- What you see first. “Welcome to your AI home.” with the button “Get started”. Then your name, an e-mail address, a password and “Create Admin Account”. The account exists on this computer only.
- Two things to close. A window with news about Open WebUI, and a note that a newer version of it is out. Leave that note alone: the Desk fixes each app’s version, and a newer Open WebUI comes with a later Desk.
- No model yet. The chat box says “Select a model”, and its list says “No models available”.
- Fetch your first model. Click “Select a model”, type
llama3.2:3binto the search field and click “Download "llama3.2:3b"”. It is 2 GB; on our line that took two minutes. Open WebUI then selects it. - Starter prompts. open-webui-prompts.json holds four prompts:
/explain,/claims,/methodsand/doubt, the last one asks the model where its answer could be wrong. “Workspace”, “Prompts”, then the import button and the file. In a chat, type/and the command; Open WebUI then asks for your text. We added them in the Desk’s Open WebUI version through the same call its import uses; we have not clicked the import button. - Ask something. The first answer took about a minute and a half on our test laptop, which has 16 GB of memory and computes on the processor: the model is loaded first.
- Why not a smaller model. We tried two.
smollm2:135manswers only “does not support tools”.qwen2.5:0.5banswers with talk about tasks instead of your question. Open WebUI hands every model a set of tools, and very small models cannot use them. - Memory. With all five apps running and this model loaded, Podman used 7.8 GB of the laptop’s 16 GB. On a laptop with 8 GB, stop the other apps first; we have not tried that.
- In the curriculum. T02-L04 · A Self-Hosted Assistant Your Team Can Use Safely and T11-L02 · A Local Model Your Tools Can Call.
Ollama
- No page of its own. Ollama runs the models; you use it through Open WebUI. “Open” on Ollama’s card shows one line of text that says it is running.
- It starts with Open WebUI. Opening Open WebUI starts Ollama first. Stopping Open WebUI leaves Ollama running; stop it on its own card.
- Where the models are. In the volume
ai-lab-ollama-data. With the three models above it held 2.6 GB. - In the curriculum. T11-L01 · Run an AI Model on Your Own Laptop, Offline.
Before you install
What it puts on your computer.
The numbers are from our Windows 11 test computer with 16 GB of memory and version 0.2.0-alpha.7. Yours will differ.
- The Desk itself: 6 MB. It goes into your own user folder and needs no administrator rights. It adds an entry to the Start menu and starts with Windows, as an icon next to the clock. Its settings are in the folder
.ai-labin your user folder. - Podman. The program that runs the apps. “Set up Podman” fetches it with Windows’ own package manager and prepares it; Windows asks for permission once. On our test computer that took one minute.
- WSL. Podman needs a part of Windows named WSL, which runs Linux programs. Many computers have it already. On one of ours, a freshly installed WSL started only after the computer was restarted. We have not tried the Desk’s setup on a computer without WSL.
- One file that grows. Podman keeps all apps and their data in one file on your disk. With n8n, Gitea and Miniflux installed it was 3.3 GB.
- The apps. Each is downloaded when you first start it: n8n 1.2 GB, Gitea 0.2 GB, Miniflux with its database 0.3 GB. Open WebUI and Ollama are 5.6 GB and 4.7 GB, before any model.
- Memory. With n8n, Gitea and Miniflux running, Podman used about 1.8 GB.
- What keeps running. An app keeps running when you close the window or quit the Desk. Uninstalling the Desk stops the apps (from version 0.2.0-alpha.8). After you sign in to Windows again, the Desk starts the apps that were running before. “Stop” on an app’s card ends that.
- Windows’ warning. The installer is not signed, so Windows warns before it runs. Its usual box says “Windows protected your PC”; “More info” and then “Run anyway” start the installer. On a German Windows: “Der Computer wurde durch Windows geschützt”, “Weitere Informationen”, “Trotzdem ausführen”. Your browser may first ask whether to keep the file. We have not photographed these boxes with our installer.
- Not for every computer. There is no download for Windows on ARM or for a Mac with an Intel processor.
When you are done
Switch it off. Remove it.
Each step here was done on our Windows test computer with version 0.2.0-alpha.7, except where it says otherwise. Where a command is needed: in the Desk’s window, “Advanced”, then “Open a Podman terminal”.
- Switch an app off. “Stop” on its card. It stays off, also after a restart, until you open it again. Its data stays.
- Free Podman’s memory too. In the Podman terminal:
podman machine stop. That took 25 seconds, and Podman’s memory fell from 1.8 GB to 0.6 GB within seconds. Nothing is deleted. The Desk starts Podman again when you open an app, or when you next sign in and apps were running. - Remove one app, with its data. Three steps.
1. “Stop”, then “Remove” on its card. The app’s container is gone; its data and settings are still there.
2. In the Podman terminal,podman volume lslists the data of all apps; an app’s volumes start withai-lab-and its name.podman volume rm ai-lab-n8n-datadeletes n8n’s work. This cannot be undone.
3. “Open the data folder” in the Desk, then delete the app’s folder underapps. It holds the app’s settings and the secrets the Desk made for it. - Delete downloads no app uses.
podman image prune -adeletes the downloaded programs of apps that are removed. Those of installed apps stay. - Remove the Desk. Windows Settings, Apps, Installed apps, “Heidelberg AI Desk (alpha)”, Uninstall. The program, its Start menu entry and its start with Windows are gone. From version 0.2.0-alpha.8 the uninstaller stops your apps first, which took ten seconds on our test computer. Their data stays, and so does the folder
.ai-lab. An earlier version leaves the apps running: stop them first. - Remove everything. From 0.2.0-alpha.11,
desk remove --everything --yesdeletes every app with its data and the folder.ai-lab, and says what is left; then go on withpodman machine rmand the two uninstalls below. By hand, in this order:podman machine rmin the Podman terminal deletes Podman’s file with every app, every download and all data, and gives the disk space back. Then uninstall the Desk, uninstall “Podman” in the same list of installed apps, and delete the folder.ai-labin your user folder. We removed Podman’s file this way with an earlier version; we have not uninstalled Podman itself or deleted.ai-labin a test. - macOS and Linux. The
podmancommands are the same in the Terminal. The Desk is the folder you unpacked; delete it and~/.ai-lab. Not tried.
From 0.2.0-alpha.8
Updates.
The Desk tells you when a newer version is out, and puts it in place when you say so.
- What it asks, and when. Thirty seconds after the menu next to the clock starts, and then once a day, the Desk fetches one small text file from this website:
https://ai.32dots.de/desk/latest.txt. The file names the newest version for Windows, macOS and Linux. The Desk sends nothing with the request: no name, no list of your apps, no number that identifies your computer. - What you see. Nothing, unless a newer version is out. Then the window says “Version … of the Desk is out” with the button “Update now”, and the menu has “Update to version …”.
- What “Update now” does. The Desk fetches the new file from this website, compares its size and its SHA-256 with the list, and puts it in place. On our Windows test computer that took four seconds: the window closes and comes back. Your apps keep running, and their data and settings are not touched.
- A file that does not match is deleted, and nothing is changed. The window says so and offers “Try again”.
- Nothing is installed without your click.
- By hand.
desk updatedoes the same on the command line;desk update lookonly says whether a newer version is out. In the window: “Advanced”, then “Look for a newer version”. - Before 0.2.0-alpha.8 the Desk had no update. Install the current version once from the downloads; it goes over the old one, and your apps and their data stay.
- What the check proves. That the file is the one this website names. The programs are not signed, so it does not prove who built them; that is the same as for the download in your browser.
Tried: the update from the window and from the command line on Windows 11, with three apps running; a file with a wrong SHA-256, which was refused; the command line on Linux and on a Mac. Not tried: the button in the window on a Mac, a download that breaks off, and the look once a day (we saw the first look only).
Command line
Every command.
The app names are n8n, gitea, open-webui and ollama. On macOS and Linux write ./desk when the program is not on your PATH. On Windows, from version 0.2.0-alpha.11, the installer puts the Desk on your PATH: in a new Command Prompt desk doctor works. In PowerShell the word desk opens a settings file of Windows with that name; from version 0.2.0-alpha.14 write aidesk doctor there, the same program under a second name (with an earlier version desk.exe doctor). The terminal the Desk opens (“Advanced”, “Open a Podman terminal”) puts the Desk first. With an earlier version write the whole path with its quotation marks: "%LOCALAPPDATA%\Programs\Heidelberg AI Desk Alpha\desk.exe" doctor.
| Command | What it does |
|---|---|
desk list | Shows the apps, their state and their addresses. |
desk start n8n | Installs the app if needed, starts it and waits until it answers. |
desk open n8n | Starts the app if needed, then opens it in your browser. |
desk stop n8n | Stops the app and keeps everything. desk stop --all stops every app. |
desk remove n8n | Removes the container and keeps data and settings. From 0.2.0-alpha.11, desk remove --everything says what it would delete, and desk remove --everything --yes deletes every app, all their data and the folder .ai-lab. Back up first. |
desk resume | Starts again what was running before a restart. |
desk logs n8n | Shows the app’s last 200 log lines. For a helper of an app: desk logs miniflux db. |
desk model | From 0.2.0-alpha.11. Fetches the language model llama3.2:3b into Ollama, about 2 GB, and starts Ollama first if it is not running. desk model qwen2.5:3b fetches another one. In the window: “Get the recommended model” on the Ollama and Open WebUI cards. |
desk backup n8n | From 0.2.0-alpha.11. Copies the app’s data and its passwords into a new folder in “Heidelberg AI Desk backups” in your user folder, or into a folder you name: desk backup n8n D:\stick. A running app is stopped for the copy and started again. Needs Podman. In the window: “Back up” on the card. |
desk restore n8n <folder> | From 0.2.0-alpha.11. Puts such a backup back, only into an app that has no data on this computer, so nothing is written over. The Desk says which command removes the old data first. |
desk doctor | Shows the data folder and which container runtime was found. |
desk setup | Windows: installs Podman if it is missing. Then gets Podman running. It also makes a new Podman machine when the old one is gone. |
desk update | Asks this website whether a newer Desk is out. If so, fetches it, checks its size and SHA-256 against what the website names, and puts it in place. The apps keep running. desk update look only says whether there is one. |
desk check my-app.yaml | Reads an app’s recipe, a Compose file, and says what it would run. Installs and starts nothing. In place of a file it takes a web address that starts with https; so does desk add. |
desk add my-app.yaml | Takes a recipe into your list of apps. Nobody has reviewed it: add it only if you trust who gave it to you. |
desk forget my-app | Takes an app you added out of the list, once it is removed. Its data stays. |
desk shelf | Fetches your shelves and lists their recipes. A shelf is a list of recipes on the web that a group shares. desk shelf add <address> names one, desk shelf forget <address> takes it out. See A shelf. |
desk version | Shows the version. |
Windows
The window and the menu next to the clock.
The Desk has a window. Open it from the Start menu, with a left click on the Desk’s icon next to the clock, or with “Open the Desk” in the menu. A right click on the icon opens the menu.
- Installed Apps. One card per app on your computer, with its state, “Open” or “Start and open”, and “Stop”. A stopped app also has “Remove”: it removes the container and keeps data and settings.
- App Store. Every app the Desk knows, with “Install and open”. “Show more apps” fetches the shelves, the lists of apps a group shares at a web address, and puts their apps among the cards. Below the cards: “Shelves” and “Add an app from a file”.
- On the left. Whether apps can run, how many are running, “Refresh” and “Open the data folder”. On Windows, “Set up Podman” appears here while Podman cannot be used.
- Advanced. “Open a Podman terminal” for everything the Desk has no button for, and Podman Desktop. Podman Desktop is a program of its own from the makers of Podman; it shows the containers, images, volumes and logs behind your apps. The Desk works without it. If it is not installed, the Desk asks first: on Windows it then installs it, a download of about 150 MB; on macOS and Linux it opens the download page.
- With the keyboard alone. Tab goes from button to button, Shift and Tab back; Enter or Space presses the button; Escape closes a box. From version 0.2.0-alpha.10 the window keeps your place when a card changes, for example after “Stop”. It has not been tried with a screen reader.
- Closing the window stops nothing. The icon next to the clock and the apps stay.
The menu holds the same actions in short:
- First line. The name and the version. The icon’s tooltip shows them too.
- One entry per app. It shows the state and holds two actions, “Start and open” and “Stop”, and the address the app answers at.
- Status line. Names the runtime that is running, or says what went wrong with the last action.
- Refresh. Reads the state again. The menu also does that when the pointer reaches the icon.
- Open the data folder. Shows where the settings are.
- Quit. Closes the menu only. The apps keep running.
When the menu starts, it starts Podman if needed and then the apps that were running before. If you ticked “Show the menu next to the clock when I sign in” in the installer, that happens each time you sign in to Windows.
From 0.2.0-alpha.4
Open WebUI and Ollama.
Ollama runs language models on your computer. Open WebUI is the chat window for them. Start Open WebUI, in the window or with desk open open-webui; the Desk starts Ollama first.
- A large download. The two images take 5.6 GB and 4.7 GB on disk. The first start takes as long as their download; on our line it took just under seven minutes. From version 0.2.0-alpha.15 the app’s card counts the download in MB and percent (Windows and Mac; on Linux only where Podman’s API service runs).
- The first account is the administrator. Open WebUI asks you to create an account when you open it for the first time. It is kept on your computer only.
- Fetch a model. A fresh Ollama has none. The first steps say how to fetch one from inside Open WebUI, and which one answered in our test.
- Processor only. The Desk gives a container no graphics card, so Ollama computes on the processor. Large models are slow that way.
- An Ollama you installed yourself. To use it instead, set
OLLAMA_BASE_URL=http://host.containers.internal:11434in Open WebUI’s settings file in the data folder and start Open WebUI again. This has not been tried yet. - Addresses. Open WebUI answers at
http://127.0.0.1:33000/, Ollama athttp://127.0.0.1:31434/.
On Windows 11 with Podman: the first account, three models fetched from inside Open WebUI, and a question that llama3.2:3b answered. The two apps have not been started on macOS and Linux yet; there only the connection between two apps was tried, with a small test app.
Your own app
Write a recipe, check it, pass it on.
An app for the Desk is one text file, a recipe. It is written in Compose, the usual language for describing containers, with one extra block named x-desk. This complete recipe runs a tiny web server:
name: ai-lab-whoami
x-desk:
format: 1
id: whoami
name: Whoami
category: Example
summary: A tiny web server that says which container answered.
port: 34100
ready: /
open: /
services:
whoami:
image: docker.io/traefik/whoami:v1.11.0
container_name: ai-lab-whoami
restart: unless-stopped
environment:
WHOAMI_PORT_NUMBER: 8080
WHOAMI_NAME: Heidelberg AI Desk
ports:
- "127.0.0.1:${AI_LAB_PORT}:8080"
- One container.
imagenames a fixed version.latest, or no version, is refused. - One local address. Under
portsthere is exactly one entry,"127.0.0.1:${AI_LAB_PORT}:<port inside>".portinx-deskis the port on your computer, from 1024 up, and not one another app uses (n8n has 35678, Gitea has 33009, Open WebUI has 33000, Ollama has 31434). - Data in named volumes. Write
data:/path/insideundervolumesand declaredataat the end of the file with anamethat starts withai-lab-<id>-. Folders of your computer are not handed to an app. - Settings. A value under
environmentis a fixed text, a text around${AI_LAB_PORT}, a setting the user may change, written${NAME:-value}, or a secret. - Secrets. Never write a password into a recipe. List a name with its length in bytes under
secretsinx-desk, and refer to it as${NAME}; the Desk makes the value on each user’s own computer. - Ready.
readyis a path the app answers once it has finished starting. The Desk reports the app as ready only then. - Another app. By itself no app can reach another. An app that others may use opens a network named like its container,
ai-lab-<id>; an app that uses it joins that network, markedexternal: true. There the used app answers under its container’s name and its port inside the container.
This is how the built-in Open WebUI reaches the built-in Ollama. The lines from Open WebUI’s recipe:
services:
open-webui:
environment:
OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://ai-lab-ollama:11434}
networks:
- ollama
networks:
ollama:
name: ai-lab-ollama
external: true
Looking up what a recipe needs
The app’s own documentation names its image, usually on a page called “Docker” or “Self-hosting”. The image answers the rest. These are Podman’s commands, here for Miniflux:
podman search --list-tags --limit 400 docker.io/miniflux/miniflux
podman pull docker.io/miniflux/miniflux:2.3.3
podman image inspect docker.io/miniflux/miniflux:2.3.3 --format '{{.Config.ExposedPorts}}'
podman image inspect docker.io/miniflux/miniflux:2.3.3 --format '{{.Config.Volumes}}'
curl -s -i http://127.0.0.1:34200/healthcheck
- The version. The first command lists the image’s versions. Take a full number such as
2.3.3;latest,nightlyand a bare2move to a newer image later. - The port inside.
map[8080/tcp:{}]says that the app listens on 8080, the number after the last colon underports. An image may name two; a recipe has one, the web page’s. - The data folders. PostgreSQL’s image answers
map[/var/lib/postgresql/data:{}]: that folder needs a volume. Many images name none, Miniflux’s and n8n’s among them; then the documentation does. After using the app for a while,podman diff ai-lab-<id>lists what the container wrote outside its volumes. - The ready path. The Desk counts an answer from 200 to 299. A forward to a sign-in page (302) does not count. The last command asks the started app; the first line of the answer has the number. In PowerShell write
curl.exe. Many apps have/healthor/healthz. With a path that never answers 200 the Desk waits four minutes and then says that the app did not answer.
Check the file with desk check my-app.yaml, or paste it under “Add an app from a file” in the window. The Desk either shows what the recipe would run or names the line to change. For a recipe that joins another app’s network the Desk also shows a line “Reaches”. Adding it puts the app into your list, marked “Not reviewed”.
The limits above bound what an app may do on your computer. They say nothing about what the image does with what you type into it. Add a recipe only if you trust who gave it to you.
An app with helpers
Many apps need a second program: a database, a queue, a worker. A recipe with format: 2 brings them along as helpers. This is the second half of the example miniflux.yaml, a small reader for news feeds that keeps everything in PostgreSQL:
services:
# The app itself: the service with the port, named like the app's id.
miniflux:
image: docker.io/miniflux/miniflux:2.3.3
container_name: ai-lab-miniflux
restart: unless-stopped
depends_on:
- db
environment:
# "db" is the helper below. The containers of one app find each other
# under their service names.
DATABASE_URL: postgres://miniflux:${DB_PASSWORD}@db/miniflux?sslmode=disable
RUN_MIGRATIONS: "1"
CREATE_ADMIN: "1"
ADMIN_USERNAME: ${ADMIN_USERNAME:-admin}
ADMIN_PASSWORD: ${ADMIN_PASSWORD}
BASE_URL: http://127.0.0.1:${AI_LAB_PORT}/
ports:
- "127.0.0.1:${AI_LAB_PORT}:8080"
# A helper. It has no port, so nothing but this app reaches it.
db:
image: docker.io/library/postgres:17.11-alpine
container_name: ai-lab-miniflux-db
restart: unless-stopped
environment:
POSTGRES_USER: miniflux
POSTGRES_DB: miniflux
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- db:/var/lib/postgresql/data
volumes:
db:
name: ai-lab-miniflux-db-data
- One service is the app: the one with
ports. It carries the app’s id as its name. Every other service is a helper, withoutportsand withoutnetworks; nothing but the app reaches it. - They find each other by name. The app reaches its database at
db, the helper’s service name. A helper reaches the app under the app’s id. - One secret, several places. Here the database gets
DB_PASSWORDas its password and the app gets it inside the database’s address. In format 2 a value may put several names together like this. - A password the Desk made. Miniflux makes its first account itself: the name is
admin, the password is the secretADMIN_PASSWORD. From version 0.2.0-alpha.9 the card of an app you added has “Passwords”, which shows the secrets the Desk made for it. They are kept in the app’s settings file on your computer and nowhere else. When your own recipe has such a password, say in itssummarywhich name signs in with it. depends_onandcommandare the two further lines of format 2: what starts first, and what a container runs in place of its image’s own start.- One app in the window. Install, Stop and Remove treat the app and its helpers as one; the card says “1 helper”. If a helper stops while the app runs, the Desk calls the app “partly running”, and starting it brings the helper back.
- Format 2 needs this version or a newer one. An older Desk says so and takes nothing. An app of one container stays
format: 1, which every Desk reads.
Apps that need a graphics card; a file handed to a container, such as a configuration file; waiting until a helper is ready (the Desk waits for the app’s own page).
Sharing apps
A shelf: recipes a group shares.
A shelf is a short list of recipes that lie next to it on the web. A course keeps one; every student sees in the App Store what the course offers. Every Desk starts with one shelf, the project’s own, at https://ai.32dots.de/shelf/shelf.yaml.
- In the window. Open the App Store and press “Show more apps”. The apps of your shelves then stand among the other cards. “Install” on one asks once: it says where the app comes from, shows under “What it runs” what it would run, and with “Install and open” adds the app, installs it and opens it. While that runs, the card says what the Desk is doing and, from version 0.2.0-alpha.9, counts the time. To name another shelf, paste its address under “Shelves”, below the cards, and press “Add this shelf”.
- On the command line.
desk shelflists what your shelves offer, with the command that adds each recipe.desk shelf add <address>names a shelf,desk shelf forget <address>takes it out. - Only when you ask. The Desk fetches a shelf on these buttons and commands, with your computer’s own program
curl, and at no other time. A shelf installs, starts and updates nothing. - A card says where its recipe came from. “Desk shelf”: the Desk fetched it from the project’s own shelf, where the Desk team tries every recipe before it is put there. “From” and the name of a computer: fetched from any other address; whoever keeps that shelf is whom you trust. “Not reviewed”: a recipe from a file, or a fetched one whose text was changed afterwards. Every recipe is checked the same way, wherever it comes from.
- A changed recipe. When a shelf later has another text for an app you have, “Shelves” says so and offers “Take the shelf’s recipe”. Taking it replaces your recipe; the app’s data stays.
- Taking a shelf out leaves the apps you added from it.
To keep a shelf of your own, put this list and the recipes it names into one folder that is handed out over https: a public Git repository (use the address of the raw file), a course’s website, any web server.
# The shelf of a course. shelf: 1 name: Automation course, winter term recipes: - whoami.yaml - miniflux.yaml
The list names 1 to 50 files ending in .yaml, each named after its app’s id. A path or an address of its own in the list is refused. How an app gets onto the Desk’s own shelf.
Your data
Where things are.
- Settings. One small file per app in the folder
.ai-lab/appsin your home folder: the port, generated secrets and the few values you may change.desk doctorprints the folder. - Your work. Workflows, repositories and accounts are in volumes that Podman keeps:
ai-lab-n8n-data,ai-lab-gitea-dataandai-lab-gitea-config. - Backup. Copying the settings folder does not copy your work. Use each app’s own export until the Desk has a backup command; the first steps name it for n8n and Gitea.
- What deletes data. No Desk command does. Resetting or removing Podman’s machine, or deleting its volumes, does.
What it costs
Free, and whose it is.
- The Desk is free of charge. Its source code is not public and it has no open-source licence.
- Each app has its own licence, set by its makers. n8n: the Sustainable Use License, which allows your own and internal use and forbids selling n8n as a service. Gitea: MIT. Open WebUI: the Open WebUI License, which allows use and asks that its name and logo stay. Ollama: MIT. Podman: Apache 2.0.
- A model has a licence too. Each model you pull into Ollama comes with its own; its page in Ollama’s library shows it.
- An app from a shelf is whatever its recipe names. The recipe says which image it runs; the image’s makers set the licence.
Recovery
When something does not start.
- Look first.
desk doctorsays whether a container runtime was found;desk listshows each app’s state. - Podman is not running.
desk setupstarts it, and on Windows installs it when it is missing. In the window on Windows, “Set up Podman” does the same. If Podman was only just installed, open a new terminal first. - “Podman’s machine is gone”. On Windows and macOS Podman keeps the apps and their data in a machine of its own. If that machine was deleted, the data went with it. The Desk does not put a new one in its place by itself: press “Set up Podman” or run
desk setup. The apps then start empty. - An app does not answer.
desk logs n8nshows what the app itself reported. The Desk waits for an answer and names this command when the time runs out. - After a restart nothing runs. Start the menu, or run
desk resume. - Asking for help. Send what
desk version,desk doctoranddesk listprint, your operating system and the exact message. Leave out keys, passwords and private addresses.