From e04823afa0023eabed5389faffb349be8f6c9a64 Mon Sep 17 00:00:00 2001
From: Muddyblack <70057554+Muddyblack@users.noreply.github.com>
Date: Tue, 29 Sep 2026 01:19:03 +0200
Subject: [PATCH] Add netlab-ui tool documentation and configuration files

---
 docs/extool/netlab-ui.md          | 38 ++++++++++++++++++++++++++++++
 docs/extools.md                   |  1 +
 netsim/tools/netlab_ui.yml        | 39 +++++++++++++++++++++++++++++++
 tests/topology/expected/tools.yml |  2 ++
 tests/topology/input/tools.yml    |  1 +
 5 files changed, 81 insertions(+)
 create mode 100644 docs/extool/netlab-ui.md
 create mode 100644 netsim/tools/netlab_ui.yml

diff --git a/docs/extool/netlab-ui.md b/docs/extool/netlab-ui.md
new file mode 100644
index 0000000000..edd5fc0c93
--- /dev/null
+++ b/docs/extool/netlab-ui.md
@@ -0,0 +1,38 @@
+(extool-netlab-ui)=
+# netlab-ui
+
+[netlab-ui](https://github.com/Muddyblack/netlab-ui) is a web-based topology editor and lab manager for _netlab_. 
+It displays the lab topology, lets you edit nodes, links, and module parameters, starts and stops the lab, and opens shells and log streams to lab devices in the browser. Just like the containerlab-app does but with direct support for netlab logic.
+
+Add the following lines to a lab topology file to start netlab-ui together with the lab:
+
+```
+tools:
+  netlab_ui:
+```
+
+The URL of the web interface is printed during the **netlab up** process. You can also display it with the **netlab connect netlab_ui** command.
+
+## Parameters
+
+You can change these tool parameters in the lab topology or in [user defaults](tools-enable-default) (**defaults.tools.netlab_ui**):
+
+* **host** -- the IP address the web server listens on. The default (`127.0.0.1`) accepts connections only from the lab server; use an SSH tunnel (for example, `ssh -L 8000:localhost:8000 labserver`) to reach it from your workstation, or set it to `0.0.0.0` together with **auth**.
+* **port** -- the TCP port of the web interface (default: `8000`). The [multilab plugin](plugin-multilab) ID is added to the port number, so you can use netlab-ui with several lab instances on the same server.
+* **auth** -- `user:password`. When set, the web interface, its API, and device terminals require HTTP basic authentication.
+* **image** -- the container image (default: `ghcr.io/muddyblack/netlab-ui:latest`). The image contains only the UI; it runs the _netlab_, Ansible, and _containerlab_ installed on the lab server, as the user who owns `~/.netlab`.
+
+For example, to make netlab-ui reachable from other hosts:
+
+```
+tools:
+  netlab_ui:
+    host: 0.0.0.0
+    auth: admin:changeme
+```
+
+## Notes
+
+* netlab-ui manages the lab in the directory in which you executed **netlab up**. The container runs with the same privileges as _containerlab_ (privileged mode, host network, and host PID namespace) and has access to the Docker socket, the lab directory, and the `~/.netlab` directory in which _netlab_ tracks running labs.
+* The container is removed when you shut down the lab with **netlab down**. When you stop or restart the lab from the netlab-ui web interface, the tool keeps running.
+* netlab-ui also runs without a lab topology. Install it as a Python package with `pipx install netlab-ui` (from [PyPI](https://pypi.org/project/netlab-ui/)) and start it with `netlab-ui`, or run the container with `docker compose`. See the [netlab-ui quick start](https://github.com/Muddyblack/netlab-ui#quick-start) for details.
diff --git a/docs/extools.md b/docs/extools.md
index 906be2d984..7c3b115a4f 100644
--- a/docs/extools.md
+++ b/docs/extools.md
@@ -62,6 +62,7 @@ _netlab_ includes definitions for the following tools:
    extool/nso.md
    extool/nuts.md
    extool/network_xray.md
+   extool/netlab-ui.md
 ```
 
 It's relatively easy to add your own tools to the **defaults.tools** dictionary. Read [](dev/extools.md) for more details.
diff --git a/netsim/tools/netlab_ui.yml b/netsim/tools/netlab_ui.yml
new file mode 100644
index 0000000000..e623c97f27
--- /dev/null
+++ b/netsim/tools/netlab_ui.yml
@@ -0,0 +1,39 @@
+#
+# netlab-ui: web-based topology editor and lab manager for netlab
+# https://github.com/Muddyblack/netlab-ui
+#
+# The container is the UI only. It runs the netlab, Ansible and containerlab installed on this
+# host by entering the host namespaces (nsenter), so it needs the same access containerlab has
+# (privileged, host network and PID namespace), the Docker socket, the lab directory mounted at
+# the same path (containerlab bind-mounts node files by path through the host Docker daemon),
+# and ~/.netlab (the lab registry) so 'netlab status' on the host and the UI see the same labs.
+#
+# Without a lab topology, install it with 'pipx install netlab-ui' instead.
+#
+---
+runtime: docker
+image: ghcr.io/muddyblack/netlab-ui:latest
+host: 127.0.0.1         # Listen on loopback; set to 0.0.0.0 (with 'auth') to reach it remotely
+port: 8000              # Plus the multilab ID when using the multilab plugin
+auth: ''                # 'user:password' enables HTTP Basic authentication
+docker:
+  up:
+    docker inspect '{name}_netlab_ui' >/dev/null 2>&1 ||
+    docker run -d
+      --name '{name}_netlab_ui'
+      --restart unless-stopped
+      --privileged --network host --pid host
+      -v /var/run/docker.sock:/var/run/docker.sock
+      -v /var/run/netns:/var/run/netns
+      -v "$(pwd):$(pwd)" -e NETLAB_WORKSPACE="$(pwd)"
+      -v "$HOME/.netlab:/root/.netlab"
+      -e NETLAB_UI_CONTAINER='{name}_netlab_ui'
+      -e UVICORN_HOST='{tools.netlab_ui.host or defaults.tools.netlab_ui.host}'
+      -e UVICORN_PORT={(tools.netlab_ui.port or defaults.tools.netlab_ui.port) + (defaults.multilab.id or 0)}
+      -e NETLAB_UI_AUTH='{tools.netlab_ui.auth or defaults.tools.netlab_ui.auth}'
+      '{tools.netlab_ui.image or defaults.tools.netlab_ui.image}'
+  message: >-
+    Open http://{sys.ipurl}:{(tools.netlab_ui.port or defaults.tools.netlab_ui.port) + (defaults.multilab.id or 0)}
+    in your browser (on a remote server, use an SSH tunnel unless netlab_ui.host is set)
+  down:
+    test -n "$NETLAB_UI_RUN" || docker rm -f '{name}_netlab_ui' >/dev/null
diff --git a/tests/topology/expected/tools.yml b/tests/topology/expected/tools.yml
index 943b797c4d..0bfd7d825b 100644
--- a/tests/topology/expected/tools.yml
+++ b/tests/topology/expected/tools.yml
@@ -33,5 +33,7 @@ provider: libvirt
 tools:
   graphite:
     runtime: docker
+  netlab_ui:
+    runtime: docker
   suzieq:
     runtime: docker
diff --git a/tests/topology/input/tools.yml b/tests/topology/input/tools.yml
index 373c4a0745..7e6f41b6ef 100644
--- a/tests/topology/input/tools.yml
+++ b/tests/topology/input/tools.yml
@@ -5,3 +5,4 @@ nodes:
 tools:
   graphite:
   suzieq:
+  netlab_ui: