Using the stack on a Mac

Setup is done and the script printed SMOKE OK. This page is everything that comes after: your addresses and logins, the handful of commands you need, how to get your own files in and out, how to update, and what to do when something goes wrong. Bookmark it — you won’t need the setup guide again.

Your services

Open these in Safari or Chrome. If setup had to move a port your addresses differ from the defaults below — ./kingo credentials always prints the truth for your own Mac:

Not all of these run at the same time: in abp mode — what setup installs — only Langflow, n8n, CloudBeaver, Qdrant and PostgreSQL are on, and ./kingo credentials marks the others as off. See Modes for switching.

CloudBeaver looks empty at first (“No Connections”) — you have to log in via the gear icon → Login before the class database shows up, and give it the database password once. Two minutes, step by step: Using CloudBeaver.

MCP (Model Context Protocol) is how AI assistants such as Claude Desktop, Claude Code, or Cursor connect to tools. Point yours at the Jupyter MCP endpoint http://localhost:4040/mcp (header Authorization: Bearer kingo-mcp-2026) and it can write and run code in the class notebook for you. ./kingo mcp prints exactly this.

OpenCode (AI coding in the terminal) runs natively on your Mac — it is not inside the stack. Install it once with (works whether or not you have Homebrew):

curl -fsSL https://opencode.ai/install | bash

then run opencode in any Terminal. The first run asks for an API key; change it anytime with opencode auth login.

Everyday use

Open Terminal and go to the class folder:

cd ~/kingo-pod

then one command per job:

What if I just close the Terminal window? Nothing breaks — the stack keeps running in the background: your services stay reachable in the browser, and it keeps using its memory (4 GB in abp mode, up to 6 GB in full mode). It stops only when you run ./kingo down or shut down / restart the Mac. Your data survives all of these — closed windows, down, reboots. After a reboot, run ./kingo up again. (Docker Desktop users: the stack may come back by itself when Docker starts — ./kingo status shows what’s up.)

Modes: which services run

Not every class week needs all nine services, and an 8 GB Mac cannot run them all comfortably. A mode is the set of services that runs — the others are simply off (nothing is deleted; every mode keeps your data):

./kingo mode shows the current one. Switching is one line, for example:

cd ~/kingo-pod && ./kingo mode full

It takes about a minute: the stack stops, the Podman machine is resized to what the new mode wants, and the stack comes back with the new set of services. Your notebooks, dashboards, flows and workflows are all still there — switch back any time with ./kingo mode abp.

On a Mac with Podman, resizing the machine stops ALL containers on the Mac for about a minute — Kingo’s come back by themselves, containers from other courses do not. If any are running, kingo lists them and asks you to type yes first. (Docker Desktop: nothing is resized; only the services change.)

Want a different amount of memory than the mode asks for? ./kingo memory shows what the containers have and use right now; ./kingo memory 5 sets 5 GB (same one-minute restart); ./kingo memory auto lets the mode decide again.

Your own files — the shared folder

shared is a folder inside kingo-pod that both you and Langflow can see. Put your own files there: a SQLite database, a CSV, an Excel sheet, a PDF.

It is one folder with two names, because you and Langflow look at it from different sides:

So a database you drop in as ~/kingo-pod/shared/trials.sqlite is /app/shared/trials.sqlite when you type it into a Langflow component. It works the other way round too: whatever Langflow writes there shows up on your Mac. The folder is made for you — if it is not there, run ./kingo update once.

Opening a SQLite file in Langflow? The SQL component wants a database URL, not a path, and an absolute path takes four slashes: sqlite:////app/shared/trials.sqlite.

One line opens the folder in Finder (then ⌘-drag it to the Finder sidebar to keep it there):

open ~/kingo-pod/shared

Drag files in and out like in any other folder. Langflow sees them at once.

Keep private files out of it. Anything running inside Langflow can read, change and delete what is in this folder — including a flow someone else built and you imported. Never let it hold your only copy of something. Nothing outside this one folder is reachable from Langflow.

Using Docker Desktop? Files that Langflow itself writes into the folder can end up owned by the system rather than by you — deleting those from Finder or Terminal may then need sudo rm. Files you put in are never affected. With Podman (the default) this does not happen.

Keeping up to date

One line brings your installation up to date — newest class files, images and rebuilt containers. Safe to run any time, from any folder:

cd ~/kingo-pod && ./kingo update

Run it whenever your instructor announces an update. It works for every install, however old — nothing has to be downloaded by hand.

If something breaks

Always start with one command — it checks the usual suspects and tells you what to do:

./kingo doctor

FAQ

Why Podman and not Docker? They do the same job and this stack runs identically on both (our tests run on both, every day). We default to Podman because it’s fully open-source and free for everyone — Docker Desktop’s license requires payment at larger companies, and we don’t want the tooling you learn to expire with your student status. If Docker Desktop is already on your Mac, the setup script simply uses it — you are not missing anything either way.

I already use Docker / have my own database. Will this break my stuff? No. Kingo runs in its own containers (all named kingo-…) with its own storage. The only possible overlap is a port number — and setup/fixports resolves that automatically by moving Kingo, never your software.

The passwords are printed in a public repo?! Yes, on purpose. Every service is reachable only from your own Mac (127.0.0.1 — people on the same Wi-Fi cannot connect), so these are classroom conveniences, not secrets. The one real rule: the class shares an n8n encryption key, so never put a real API key into an n8n workflow you share or export.

Where is my data? Databases, notebooks, and workflows live in container volumes on your Mac and survive ./kingo down, reboots and mode switches. Only ./kingo reset deletes them (it asks first).

Where did Jupyter and Metabase go? They are off in abp mode, which is what setup installs — ./kingo status and ./kingo credentials say so. ./kingo mode full turns everything on (about a minute; see Modes); the instructor announces when a class week needs it.

Can I give the containers more or less memory myself? Yes: ./kingo memory 5 (or any number of GB). On a Mac with Podman that resizes the Podman machine right away — and, like every machine restart, stops ALL containers on the Mac for about a minute, not only Kingo’s. With Docker Desktop the memory slider is in Docker Desktop → Settings → Resources; the same warning applies to its Apply & restart.

Can I use extra Python packages (say, statsmodels)?

• JupyterLab (:8888) already ships the data-science standards — pandas, statsmodels, scikit-learn, seaborn, and friends. For anything else, run %pip install <package> in a notebook cell (repeat it if the stack was restarted since).
• Langflow: the class set (statsmodels, ragas, …) is built in — import statsmodels just works in Python components. Need one more? ./kingo langflow pip install <package> installs it on the spot; it lasts until the next ./kingo down + up, so run it again after that (or ask the instructor to add it for everyone). If the install upgraded a compiled package (pyarrow, numpy, pandas — pip lists what it installed), run ./kingo restart langflow before building a flow: the running Langflow still has the old one loaded, and the build would otherwise fail with “size changed, may indicate binary incompatibility”.
• JupyterHub (:8000) starts a minimal Python without the data packages — use %pip install there too, or simply do data work in JupyterLab.

How it all fits together

┌─ Your Mac ─────────────────────────────────────────────────┐
│                                                            │
│   Browser, KNIME, MCP clients, OpenCode                    │
│       │                                                    │
│       │  always talk to  localhost:<port>                  │
│       ▼  (published on 127.0.0.1 only)                     │
│  ┌─ Container engine (Podman or Docker) ───────────────┐   │
│  │                                                     │   │
│  │   one container per service:                        │   │
│  │   [Langflow] [n8n] [JupyterLab] [Metabase] ...      │   │
│  │       │        │                                    │   │
│  │       └────────┴──► [PostgreSQL]   [Qdrant]         │   │
│  │                                                     │   │
│  │   containers reach each other by service NAME:      │   │
│  │   postgres:5432, qdrant:6333                        │   │
│  └─────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────┘

Two address rules cover everything:

1. From your Mac (browser, KNIME, MCP clients): always localhost:<port>.
2. From one service to another — e.g. an n8n workflow or Langflow flow connecting to the database: use the service name as host, not localhost. PostgreSQL: host postgres, port 5432, database classroom, user student, password kingo2026. Qdrant: http://qdrant:6333. (Inside a container, localhost means the container itself — the most common mistake. Rule 2 is also why moved host ports never affect service-to-service connections.)

KNIME (optional)

KNIME runs on your Mac itself, not in a container: download KNIME Analytics Platform from https://www.knime.com/downloads and install it like any other app. To use the class database, create a PostgreSQL connection with host localhost, port 5432 (or your moved port from ./kingo credentials), database classroom, username student, password kingo2026. The stack must be running (./kingo up) while you use it.