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:
| Service | Address | Login |
|---|---|---|
| Langflow | http://localhost:7860 | none (logs in automatically) |
| n8n | http://localhost:5678 | create your own account on first visit |
| JupyterLab | http://localhost:8888 | none |
| JupyterHub | http://localhost:8000 | any username + password kingo2026 |
| Metabase | http://localhost:3000 | admin@kingo.local / Kingo2026! |
| CloudBeaver | http://localhost:8978 | student / Kingo2026! β how to connect |
| Qdrant | http://localhost:6333/dashboard | none |
| PostgreSQL | localhost:5432 |
student / kingo2026 (db: classroom) |
Not all of these run at the same time: in abp mode β what setup installs β
only Langflow, n8n, Mail, 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:
| Command | What it does |
|---|---|
./kingo up |
start everything (your data stays between runs) |
./kingo down |
stop everything |
./kingo status |
which services are up? |
./kingo credentials |
my addresses + logins |
./kingo mode |
which services run β and ./kingo mode full / abp / β¦ switches (see Modes) |
./kingo memory |
how much memory the containers may use; ./kingo memory 5 changes it |
./kingo mail |
set up the mailbox for the mail assistant (n8n workshop); ./kingo mail help shows the rest |
./kingo claude |
start Claude Code, your coding agent, in its sandbox (see Claude Code) |
./kingo claude --login |
the same with your Claude subscription in place of OpenRouter (see Your Claude subscription) |
./kingo shortcuts |
short commands for your terminal, such as kc for Claude Code and kc . for Claude Code in the folder you are in (see Shorter commands) |
./kingo doctor |
somethingβs wrong? start here |
./kingo version |
which version am I running? (send this when you ask for help) |
./kingo update |
get the newest class files + images (run it when the instructor announces an update) |
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 downor shut down / restart the Mac. Your data survives all of these β closed windows,down, reboots. After a reboot, run./kingo upagain. (Docker Desktop users: the stack may come back by itself when Docker starts β./kingo statusshows whatβs up.)
Modes: which services run
Not every class week needs all ten 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):
| Mode | What runs | Memory it wants |
|---|---|---|
abp (what setup installs) |
Langflow, n8n, Mail, CloudBeaver, Qdrant, PostgreSQL | 4 GB |
full |
all ten services | 6 GB |
bi |
JupyterLab, JupyterHub, Jupyter MCP, Metabase, CloudBeaver, Qdrant, PostgreSQL | 4.5 GB |
langflow |
Langflow, PostgreSQL | 3.5 GB |
n8n |
n8n, Mail, PostgreSQL | 2.5 GB |
./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,
kingolists them and asks you to typeyesfirst. (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:
| Looking from | The folder is called |
|---|---|
| your Mac | ~/kingo-pod/shared |
| inside Langflow | /app/shared |
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.
Claude Code β your coding agent
Claude Code is an AI that works with you in Terminal. It reads and writes files, runs commands, and in kingo-pod it can change your n8n workflows, your Langflow flows and your database. It uses the model GLM 5.3 Flash, paid with the OpenRouter key Yanbo gave you.
It runs in a sandbox called nono: on your Mac it can write in one folder
only, ~/kingo-pod/claude. It can read the rest of kingo-pod to understand
the stack, and nothing else on your Mac.
Install it once. One line installs the database tool psql and Claude
Code:
brew install libpq && curl -fsSL https://claude.ai/install.sh | bash
nono you do not install: ./kingo claude gets the version it needs by
itself, the first time you start it.
Already use Claude Code? Run the line anyway: it installs Claude Code the way Anthropic recommends, or brings it up to date. Your own settings and your login stay as they are. Did you install Claude Code with Homebrew or npm instead? Then you now have two installations.
./kingo claudealways takes the new one. To keep only the new one, remove the old one:brew uninstall --cask claude-codeornpm uninstall -g @anthropic-ai/claude-code.
Make a key in n8n for Claude. In n8n, click Settings at the bottom of
the left sidebar, then n8n API, then Create API key. Label: claude.
Expiration: Never. Click Save and copy the key: n8n shows it only once.
Start it:
cd ~/kingo-pod && ./kingo claude
Always start it this way: only ./kingo claude (or ./kingo yolo) sets it
up for the course. A plain claude is a standard Claude Code with
Anthropicβs settings β no sandbox, no keys, your own ~/.claude.
The first time, it asks for two keys: your OpenRouter key and the n8n key you
just made. Paste each one and press Enter; you do not see a key as you paste
it. The key for Langflow it makes by itself. Then Claude Code asks a few
questions of its own: pick a look, and say Yes when it asks whether you
trust the folder. To stop, type /exit. Every next time, ./kingo claude
starts it right away.
Hard to read? Type
/themein Claude Code and pick another look./themechanges only the colors of the text. The background is not Claude Codeβs: it belongs to your terminal, and you change it in the settings of the terminal (in Terminal: Terminal, Settings, Profiles).
Tell it your teamβs rules. Claude reads the file
~/kingo-pod/claude/AGENTS.md at every start. Paste your teamβs copy of
ws2_rules.html into it, below the heading Your teamβs rules, as the
file explains, then start Claude again. kingo writes the part above the
heading anew at every start, and a line of yours there it moves below the
heading. This line opens the file in TextEdit:
open -e ~/kingo-pod/claude/AGENTS.md
| Claude can | Claude cannot |
|---|---|
read and write in ~/kingo-pod/claude |
write anywhere else on your Mac |
read kingo-pod: compose.yml, the guides |
change kingo-pod, or run ./kingo |
| change your n8n workflows, Langflow flows and database | see your keys: it gets stand-ins |
| look things up on the web | see your own Claude Code settings, if you use Claude Code already |
look at the pages it writes, and click through them as a person would (look, clickthrough) |
open http addresses on your laptop, apart from your dev server with clickthrough --dev 5173 |
It asks before every command, unless you start it with
./kingo yolo. Inside the sandbox, Claude Codeβs requests for permission do not
protect your Mac β the sandbox does that either way β but they show you every
change to your workflows, flows and database before it happens. Without them,
save your workflows and flows first with ./kingo backup (your own tables are
not in it). And only run a command in your
own Terminal if you understand it: Claude cannot leave its sandbox, but a
command you type can.
A key stopped working?
./kingo claudechecks the keys at every start. A key that a service refuses is deleted, and the next start asks for it again. The keys are kept in~/.config/kingo/, where Claude cannot read them.
Your Claude subscription (optional)
Do you have a Claude subscription (Pro or Max)? Then Claude Code can use it in place of OpenRouter: Anthropicβs models, paid by your subscription. The course does not need this. Everything else stays the same: the sandbox, n8n, Langflow, the database, and your OpenRouter key, with which Claude can try the models of your flows.
cd ~/kingo-pod && ./kingo claude --login
The first start opens your browser. Log in to Claude there and allow the
access. Terminal then says Logged in., and Claude Code starts.
Every next time, ./kingo claude --login starts Claude Code right away.
- Back to OpenRouter: start with
./kingo claude, as before. Both ways stay set up, side by side. - One session at a time. Two sessions with
--loginat once break the login, sokingodoes not start a second one. Close the first session, then start the new one. - Claude Code says that you are not logged in? Run
./kingo claude logout, then start with--loginagain. - End the login:
./kingo claude logout.
Where the files are:
| What | Where |
|---|---|
| your work | ~/kingo-pod/claude, the same folder as without --login |
settings and history of the sessions with --login |
~/.kingo-claude-login |
| settings and history of the sessions without it | ~/.kingo-claude |
| your login | ~/.local/state/nono/oauth-capture |
The login is kept by nono, outside the sandbox, for up to 90 days. Only you can read that folder on your Mac; it is not encrypted. Claude Code gets stand-ins, which are of no use outside the sandbox. To remove the login from your Mac for good, log out and delete the folder in Terminal:
./kingo claude logout && rm -rf ~/.local/state/nono/oauth-capture
The folder holds only this login, unless you use nono for other tools too.
Shorter commands (optional)
One command adds short commands to Terminal, so that you need not go to
~/kingo-pod and type ./kingo first:
cd ~/kingo-pod && ./kingo shortcuts
It shows a list. Type the numbers you want, for example 1 3 5, and press
Enter. Enter alone takes all of them.
| Shortcut | What it does |
|---|---|
kc |
Claude Code for the course (./kingo claude); kc . in the folder you are in, kc ~/projects/thesis in that folder |
kcl |
the same with --login: your Claude subscription |
ky |
the same as kc, with ./kingo yolo: Claude works without asking |
kyl |
the same with --login |
kingo |
./kingo from any folder, for example kingo status |
They work in every new Terminal window, from any folder:
kcalone starts Claude Code for the course, as./kingo claudedoes.kc .starts Claude Code in the folder you are in, andkc ~/projects/thesisin that folder, without the course: it writes only in that folder, and there is no n8n, Langflow or database. Not in your home folder itself: make a folder first, for examplemkdir -p ~/projects/thesis. In~/kingo-pod,kc .is the course again, and Terminal says so in one line.
kingo writes the shortcuts into ~/.zshrc, between two lines that it marks,
and keeps a copy of the file first. If you use one of these names already,
kingo asks before it writes it. ./kingo update writes them anew when kingo
changes them. To take them out again: ./kingo shortcuts remove.
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. Before a new
version starts, it saves a copy of your Langflow flows and n8n workflows in
kingo-pod/backups/, so your instructor can bring them back if something
goes wrong.
Optional this term: Kingo 1.5. It brings Langflow 1.12, which fixes a
memory bug in Langflow 1.8: chats with the same name share one memory, even
in different flows.
./kingo update does not install it by itself. Read
the optional upgrade to Kingo 1.5 and decide with your team
first.
If something breaks
Always start with one command β it checks the usual suspects and tells you what to do:
./kingo doctor
| What you see | What to do |
|---|---|
Terminal says ./kingo: No such file or directory |
Youβre in the wrong folder. Run cd ~/kingo-pod first. |
Other software on this machine is already using ports Kingo needs |
Run ./kingo fixports, then ./kingo up. Kingo moves itself to free ports β your other software is untouched. Your addresses change; ./kingo credentials shows the new ones. |
Same message right after ./kingo down, but you started nothing new |
No real collision β the engineβs port forwarder didnβt let go. Current kingo frees these leftovers by itself (get it: ./kingo update), so first just run ./kingo up again. If it persists: ./kingo fixports moves past it, or restart the engine (podman machine stop && podman machine start; Docker Desktop: quit and reopen) β note: an engine restart stops ALL your containers, not just Kingoβs. |
The Kingo stack is ALREADY RUNNING under your other engine |
Nothing is broken β the stack is up under your other container engine. Follow the two commands the message prints. |
ALL of Kingo's ports are busy |
The stack is most likely already running (possibly under your other engine). Run ./kingo status β if services show up, youβre done, nothing is wrong. |
| I have Docker Desktop, but setup installed Podman | Docker wasnβt running during setup. Both work β no need to change anything. To switch to Docker anyway: ./kingo down (stops the Podman stack first), then echo KINGO_ENGINE=docker >> .env.local, then ./kingo up. |
Podman has no ready machine / Podman wonβt start |
Run podman machine start, then ./kingo up. Still broken: podman machine stop, then podman machine start. |
Docker is installed but not running |
Open the Docker Desktop app, wait until it says βrunningβ, try again. |
| Mac feels slow / fans spin (8 GB Macs) | Run a lighter mode: ./kingo mode abp (4 GB) β or, for one tool at a time, ./kingo mode langflow (3.5 GB) or ./kingo mode n8n (2.5 GB). The containers keep their memory no matter what, so everything else on the Mac shares the rest β above all a browser with dozens of tabs, which alone can take 2β3 GB (the Langflow and n8n tabs count too): close what you do not need. ./kingo down when you are not using the stack also helps. |
brew: command not found when you install Claude Code |
The line needs Homebrew. It is missing, or Terminal does not find it. Do Step 1 β Install Homebrew, with its βNext stepsβ lines. Open a new Terminal window and run the line again. |
| Anything else | ./kingo down, then ./kingo up. If it persists: screenshot the error and ask the instructor / TA. |
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 statsmodelsjust 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 langflowbefore 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 installthere 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:
- From your Mac (browser, KNIME, MCP clients): always
localhost:<port>. - 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, port5432, databaseclassroom, userstudent, passwordkingo2026. Qdrant:http://qdrant:6333. (Inside a container,localhostmeans 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.