nbdmux 0.1.0__tar.gz

nbdmux-0.1.0/.github/workflows/ci-cd.yml

@@ -0,0 +1,146 @@
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Refuse to re-release a version PyPI already has. PyPI is immutable, but a
+  # retag-after-publish would rebuild the GitHub release assets from a newer
+  # commit and silently drift from the frozen wheel. (bty/withcache integrity
+  # guard, mirrored.)
+  check-not-published:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Refuse if version is already on PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          if curl -sfL "https://pypi.org/pypi/nbdmux/json" \
+             | python3 -c "import sys, json; sys.exit(0 if '${version}' in json.load(sys.stdin)['releases'] else 1)"; then
+            echo "::error::v${version} is already on PyPI; refusing to re-release."
+            exit 1
+          fi
+          echo "v${version} not on PyPI; proceeding."
+
+  lint:
+    needs: check-not-published
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: make lint format-check
+
+  test:
+    needs: check-not-published
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      # Real nbd-server isn't spawned in unit tests (handlers use a fake)
+      # so we don't install it on the runner. The deploy/Containerfile is
+      # what ships it on the operator's host.
+      - run: make test
+
+  wheels:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: make wheel
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  tag-release:
+    needs: [lint, test, wheels]
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT }}
+      - name: Tag the version if it is new
+        run: |
+          set -euo pipefail
+          version=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/nbdmux/__init__.py)
+          test -n "$version" || { echo "could not read __version__"; exit 1; }
+          tag="v${version}"
+          if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
+            echo "${tag} already exists; nothing to do."
+            exit 0
+          fi
+          git tag "${tag}"
+          git push origin "${tag}"
+          echo "Tagged ${tag}; ci-cd.yml will publish it."
+
+  publish-pypi:
+    needs: [lint, test, wheels]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: make wheel
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  publish-image:
+    needs: [lint, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push multi-arch image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: deploy/Containerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ghcr.io/safl/nbdmux:latest
+            ghcr.io/safl/nbdmux:${{ github.ref_name }}

nbdmux-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+data/
+images/
+*.tmp

nbdmux-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Simon A. F. Lund
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nbdmux-0.1.0/Makefile

@@ -0,0 +1,81 @@
+# nbdmux -- common tasks (and the home of the CI logic: the GitHub workflows
+# call these targets, so everything CI does is reproducible locally).
+# Run `make` for the list. Override vars on the CLI, e.g.
+#   make serve PORT=4040            make bump VERSION=0.2.0
+PYTHON    ?= python3
+RUFF      ?= ruff
+PRECOMMIT ?= pre-commit
+PORT      ?= 4040
+NBD_PORT  ?= 10809
+# Containerized deploy: prefer podman, fall back to docker.
+COMPOSE   ?= $(shell command -v podman >/dev/null 2>&1 && echo podman || echo docker) compose
+COMPOSE_FILE = deploy/compose.yml
+
+# Single source of truth = src/nbdmux/__init__.py; pyproject derives it via Hatch.
+SRC_VERSION = $(shell sed -n 's/^__version__ = "\(.*\)"/\1/p' src/nbdmux/__init__.py)
+
+.DEFAULT_GOAL := help
+.PHONY: help dev hooks-install hooks lint format format-check test \
+        wheel serve up down logs version bump check clean
+
+help: ## Show this help
+	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+		| awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+# -- dev setup -------------------------------------------------------------
+dev: ## Install dev tooling (ruff, build, pre-commit)
+	$(PYTHON) -m pip install --upgrade ruff build pre-commit
+
+hooks-install: ## Install the git pre-commit hook
+	$(PRECOMMIT) install
+
+hooks: ## Run all pre-commit hooks over the tree
+	$(PRECOMMIT) run --all-files
+
+# -- lint / test (CI: lint job, test job) ----------------------------------
+lint: ## Lint with ruff
+	$(RUFF) check .
+
+format: ## Auto-format with ruff
+	$(RUFF) format .
+
+format-check: ## Check formatting (no changes)
+	$(RUFF) format --check .
+
+test: ## Run the test suite
+	$(PYTHON) -m unittest discover -s tests -v
+
+# -- wheels / sdist --------------------------------------------------------
+wheel: ## Build sdist + pure wheel
+	$(PYTHON) -m build
+
+# -- run -------------------------------------------------------------------
+serve: ## Run nbdmux locally (set NBDMUX_ADMIN_PASSWORD to gate the UI)
+	PYTHONPATH=src $(PYTHON) -m nbdmux.server --data-dir ./data --port $(PORT) --nbd-port $(NBD_PORT)
+
+# -- deploy (containerized via compose) ------------------------------------
+up: ## Bring up the containerized nbdmux
+	$(COMPOSE) -f $(COMPOSE_FILE) up -d --build
+	@echo "nbdmux up -> operator UI: http://localhost:$(PORT)/  NBD: tcp://localhost:$(NBD_PORT)"
+
+down: ## Stop and remove the nbdmux container
+	$(COMPOSE) -f $(COMPOSE_FILE) down
+
+logs: ## Follow the nbdmux logs
+	$(COMPOSE) -f $(COMPOSE_FILE) logs -f
+
+# -- version (single source: src/nbdmux/__init__.py) -----------------------
+version: ## Show the version
+	@echo "src/nbdmux/__init__.py: $(SRC_VERSION)"
+
+bump: ## Bump the version (usage: make bump VERSION=0.2.0)
+	@test -n "$(VERSION)" || { echo "usage: make bump VERSION=X.Y.Z"; exit 2; }
+	sed -i 's/^__version__ = ".*"/__version__ = "$(VERSION)"/' src/nbdmux/__init__.py
+	@$(MAKE) --no-print-directory version
+
+# -- aggregate / cleanup ---------------------------------------------------
+check: lint format-check test ## Everything CI checks, locally
+
+clean: ## Remove build/test artifacts
+	rm -rf dist build *.egg-info .pytest_cache
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +

nbdmux-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: nbdmux
+Version: 0.1.0
+Summary: HTTP-controlled NBD-export multiplexer for a small lab (boot Linux images over the network with overlayfs+tmpfs writes)
+Project-URL: Homepage, https://github.com/safl/nbdmux
+Author-email: "Simon A. F. Lund" <safl@safl.dk>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: lab,nbd,netboot,overlayfs,ramboot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Boot
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# nbdmux
+
+HTTP-controlled NBD-export multiplexer for a small lab. Register local
+disk-image files as named NBD exports over an HTTP control plane; nbdmux
+keeps an `nbd-server` subprocess alive that serves all registered
+exports on a single TCP port. Targets `nbd-client` against that port
+from an initramfs and boot the image with overlayfs over tmpfs for
+writes (see [bty][bty]'s `ramboot` boot mode for the canonical consumer).
+
+Designed as a peer to [withcache][withcache]: small lab, single sidecar
+container, no third-party Python deps. Operationally:
+
+```
+[ bty-web ] --HTTP--> [ nbdmux ]  --supervises-->  [ nbd-server ]
+                          |                              |
+                          |                            TCP 10809
+                          |                              |
+                          v                              v
+                     SQLite state                  [ target's
+                     (exports table)                nbd-client ]
+```
+
+## Components
+
+| Path                       | What it is                                                              |
+|----------------------------|-------------------------------------------------------------------------|
+| `src/nbdmux/server.py`     | The daemon. HTTP control plane + nbd-server subprocess management + operator UI |
+| `src/nbdmux/client.py`     | Stdlib-only Python client library for other tools                           |
+| `deploy/Containerfile`     | Single-image deploy (Python + nbd-server)                                   |
+| `deploy/compose.yml`       | Reference compose stack                                                 |
+
+## System dependency
+
+nbdmux runs `nbd-server` (from the classical `nbd` project) as a
+subprocess. Install at the OS level:
+
+```sh
+# Debian / Ubuntu
+sudo apt install nbd-server
+
+# Fedora
+sudo dnf install nbd
+```
+
+The container deploy bundles it. Also make sure the `nbd` kernel
+module + `nbd-client` are available on the consuming Linux box (the
+target you're booting); they're in the same `nbd` package.
+
+## Install
+
+```sh
+pipx install nbdmux            # or: uv tool install nbdmux
+```
+
+Run the daemon (development; the container deploy is the recommended
+production path):
+
+```sh
+nbdmux-server --data-dir ./data --port 4040 --nbd-port 10809
+```
+
+Register an image:
+
+```sh
+curl -X POST http://localhost:4040/exports \
+     -H 'Content-Type: application/json' \
+     -d '{"name": "debian-sysdev", "file": "/path/to/debian-sysdev.img", "readonly": true}'
+```
+
+Then on a target Linux box:
+
+```sh
+modprobe nbd
+nbd-client <nbdmux-host> 10809 -name debian-sysdev /dev/nbd0
+fdisk -l /dev/nbd0   # the .img's partition table
+```
+
+## HTTP control plane
+
+| Method | Path                | Body                                          | Returns        |
+|--------|---------------------|-----------------------------------------------|----------------|
+| GET    | `/exports`          | -                                             | array of exports |
+| POST   | `/exports`          | `{name, file, readonly?: bool}`               | the new export |
+| DELETE | `/exports/{name}`   | -                                             | 204            |
+| GET    | `/healthz`          | -                                             | `ok`           |
+| GET    | `/`                 | -                                             | operator dashboard |
+
+## Auth
+
+Single-tenant, server-signed cookie -- same pattern as withcache. Set
+`NBDMUX_ADMIN_PASSWORD` to gate the operator UI + the HTTP control
+plane. Unset = open with a startup warning.
+
+The NBD port itself is unauthenticated (nbd-server's classical model);
+LAN-only assumption, firewall is the operator's responsibility.
+
+## License
+
+BSD-3-Clause.
+
+[bty]: https://github.com/safl/bty
+[withcache]: https://github.com/safl/withcache

nbdmux-0.1.0/README.md

@@ -0,0 +1,102 @@
+# nbdmux
+
+HTTP-controlled NBD-export multiplexer for a small lab. Register local
+disk-image files as named NBD exports over an HTTP control plane; nbdmux
+keeps an `nbd-server` subprocess alive that serves all registered
+exports on a single TCP port. Targets `nbd-client` against that port
+from an initramfs and boot the image with overlayfs over tmpfs for
+writes (see [bty][bty]'s `ramboot` boot mode for the canonical consumer).
+
+Designed as a peer to [withcache][withcache]: small lab, single sidecar
+container, no third-party Python deps. Operationally:
+
+```
+[ bty-web ] --HTTP--> [ nbdmux ]  --supervises-->  [ nbd-server ]
+                          |                              |
+                          |                            TCP 10809
+                          |                              |
+                          v                              v
+                     SQLite state                  [ target's
+                     (exports table)                nbd-client ]
+```
+
+## Components
+
+| Path                       | What it is                                                              |
+|----------------------------|-------------------------------------------------------------------------|
+| `src/nbdmux/server.py`     | The daemon. HTTP control plane + nbd-server subprocess management + operator UI |
+| `src/nbdmux/client.py`     | Stdlib-only Python client library for other tools                           |
+| `deploy/Containerfile`     | Single-image deploy (Python + nbd-server)                                   |
+| `deploy/compose.yml`       | Reference compose stack                                                 |
+
+## System dependency
+
+nbdmux runs `nbd-server` (from the classical `nbd` project) as a
+subprocess. Install at the OS level:
+
+```sh
+# Debian / Ubuntu
+sudo apt install nbd-server
+
+# Fedora
+sudo dnf install nbd
+```
+
+The container deploy bundles it. Also make sure the `nbd` kernel
+module + `nbd-client` are available on the consuming Linux box (the
+target you're booting); they're in the same `nbd` package.
+
+## Install
+
+```sh
+pipx install nbdmux            # or: uv tool install nbdmux
+```
+
+Run the daemon (development; the container deploy is the recommended
+production path):
+
+```sh
+nbdmux-server --data-dir ./data --port 4040 --nbd-port 10809
+```
+
+Register an image:
+
+```sh
+curl -X POST http://localhost:4040/exports \
+     -H 'Content-Type: application/json' \
+     -d '{"name": "debian-sysdev", "file": "/path/to/debian-sysdev.img", "readonly": true}'
+```
+
+Then on a target Linux box:
+
+```sh
+modprobe nbd
+nbd-client <nbdmux-host> 10809 -name debian-sysdev /dev/nbd0
+fdisk -l /dev/nbd0   # the .img's partition table
+```
+
+## HTTP control plane
+
+| Method | Path                | Body                                          | Returns        |
+|--------|---------------------|-----------------------------------------------|----------------|
+| GET    | `/exports`          | -                                             | array of exports |
+| POST   | `/exports`          | `{name, file, readonly?: bool}`               | the new export |
+| DELETE | `/exports/{name}`   | -                                             | 204            |
+| GET    | `/healthz`          | -                                             | `ok`           |
+| GET    | `/`                 | -                                             | operator dashboard |
+
+## Auth
+
+Single-tenant, server-signed cookie -- same pattern as withcache. Set
+`NBDMUX_ADMIN_PASSWORD` to gate the operator UI + the HTTP control
+plane. Unset = open with a startup warning.
+
+The NBD port itself is unauthenticated (nbd-server's classical model);
+LAN-only assumption, firewall is the operator's responsibility.
+
+## License
+
+BSD-3-Clause.
+
+[bty]: https://github.com/safl/bty
+[withcache]: https://github.com/safl/withcache

nbdmux-0.1.0/deploy/Containerfile

@@ -0,0 +1,43 @@
+# nbdmux container -- bundles the daemon + nbd-server + minimal Python.
+#
+# Build:  podman build -t ghcr.io/safl/nbdmux:dev -f deploy/Containerfile .
+# Run:    see deploy/compose.yml for the production shape.
+#
+# Two ports:
+#   4040   HTTP control plane + operator UI
+#  10809   NBD (nbd-server)
+
+FROM debian:trixie-slim
+
+RUN apt-get update \
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        nbd-server \
+        python3 \
+        python3-pip \
+        ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE /app/
+COPY src/ /app/src/
+RUN pip install --break-system-packages --no-cache-dir .
+
+# Persistent state lives under /data. The compose stack binds this to a
+# named volume so a container rebuild keeps registered exports.
+ENV NBDMUX_DATA_DIR=/data
+VOLUME ["/data"]
+
+# Image files we serve as NBD exports live under /images (a read-only
+# bind from the host that holds the actual .img bytes). This is just
+# the convention; the daemon will serve any absolute path the operator
+# registers.
+VOLUME ["/images"]
+
+EXPOSE 4040 10809
+
+HEALTHCHECK --interval=15s --timeout=3s --start-period=5s \
+    CMD python3 -c "import urllib.request, sys; \
+        sys.exit(0 if urllib.request.urlopen('http://localhost:4040/healthz', timeout=2).status == 200 else 1)"
+
+ENTRYPOINT ["nbdmux-server"]
+CMD ["--data-dir", "/data", "--port", "4040", "--nbd-port", "10809"]

nbdmux-0.1.0/deploy/compose.yml

@@ -0,0 +1,27 @@
+# Reference compose stack -- run as a sidecar (e.g. next to bty + withcache).
+#
+# Usage:
+#   cp envvars.example envvars && "${EDITOR:-vi}" envvars   # set NBDMUX_ADMIN_PASSWORD
+#   podman compose --env-file envvars up -d
+#   #   http://<host>:4040/   (operator UI)
+#   #   tcp://<host>:10809    (NBD)
+
+services:
+  nbdmux:
+    image: ghcr.io/safl/nbdmux:latest
+    restart: unless-stopped
+    environment:
+      NBDMUX_ADMIN_PASSWORD: "${NBDMUX_ADMIN_PASSWORD:-}"
+    ports:
+      - "${HOST_HTTP_PORT:-4040}:4040"
+      - "${HOST_NBD_PORT:-10809}:10809"
+    volumes:
+      # Persistent: state.db + nbd-server.conf survive restarts here.
+      - nbdmux-data:/data
+      # Read-only bind of the host directory holding the .img files
+      # nbdmux will serve as NBD exports. Operator places files here
+      # (or, in the bty integration, bty-web decompresses into here).
+      - "${IMAGES_HOST_DIR:-./images}:/images:ro"
+
+volumes:
+  nbdmux-data:

nbdmux-0.1.0/deploy/envvars.example

@@ -0,0 +1,16 @@
+# Copy to ``envvars`` and edit. The compose stack reads this via --env-file.
+
+# Gate the operator UI + control-plane writes. Empty = open (logs a
+# startup warning; only safe on a LAN-internal nbdmux).
+NBDMUX_ADMIN_PASSWORD=
+
+# Optional: host ports to publish. Default: same as the in-container
+# defaults (4040 HTTP, 10809 NBD).
+#HOST_HTTP_PORT=4040
+#HOST_NBD_PORT=10809
+
+# Where the .img files live on the host. Bound read-only into the
+# container at /images. nbdmux serves whatever absolute path the
+# operator registers via POST /exports; using a single host directory
+# for the .img files just keeps the bind-mount simple.
+#IMAGES_HOST_DIR=./images

nbdmux-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nbdmux"
+dynamic = ["version"]  # single source of truth: src/nbdmux/__init__.py:__version__
+description = "HTTP-controlled NBD-export multiplexer for a small lab (boot Linux images over the network with overlayfs+tmpfs writes)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Simon A. F. Lund", email = "safl@safl.dk" }]
+keywords = ["nbd", "netboot", "ramboot", "overlayfs", "lab"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Boot",
+    "Topic :: System :: Filesystems",
+]
+dependencies = []  # stdlib only, by design (delegates to the system's nbd-server)
+
+[project.urls]
+Homepage = "https://github.com/safl/nbdmux"
+
+[project.scripts]
+nbdmux-server = "nbdmux.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nbdmux"]
+
+[tool.hatch.version]
+path = "src/nbdmux/__init__.py"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E402"]

nbdmux-0.1.0/src/nbdmux/__init__.py

@@ -0,0 +1,23 @@
+"""nbdmux -- HTTP-controlled NBD-export multiplexer.
+
+Two surfaces:
+
+- ``nbdmux-server`` (``nbdmux.server:main``) -- the daemon. Manages an
+  ``nbd-server`` subprocess that exposes registered local files as
+  named NBD exports on a TCP port (default 10809). Operator dashboard
+  + HTTP control API on a separate port (default 4040).
+- ``nbdmux.client`` -- a tiny stdlib-only library for other tools
+  (e.g. bty) to register / list / unregister exports without
+  reimplementing the HTTP API.
+
+Designed for the same niche as ``withcache``: a small lab, a single
+sidecar container, no third-party Python deps. The system-level
+dependency is ``nbd-server`` (Debian / Ubuntu: ``apt install
+nbd-server``; Fedora: ``dnf install nbd``).
+"""
+
+from .client import add_export, list_exports, remove_export
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "add_export", "list_exports", "remove_export"]