nds-mapviewer 2026.2.1.dev92__tar.gz → 2026.2.1.dev94__tar.gz

{nds_mapviewer-2026.2.1.dev92 → nds_mapviewer-2026.2.1.dev94}/CHANGELOG.md

@@ -9,12 +9,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `--debug` flag to enable container debug logging (sets `HTTP_LOG_LEVEL=debug`)
+- `--env KEY=VALUE` (repeatable, short `-E`) to pass custom environment
+  variables into the container; overrides `--debug` on key collision
+- `--network NAME` to attach the container to a specific network (e.g. `host`);
+  in `host` mode port publishing is skipped and the viewer is reached on the
+  container's internal port
+- Run screen now shows a config line below the info banner with the source
+  (config file or directly-passed data-source path, e.g. a `*.ndslive`
+  filestore) and the mapped config mounted into the container
+- Accept an http(s) service URL directly as a source (e.g.
+  `mapviewer https://my-host/openapi.json`), turned into a
+  `SmartLayerTileService`; the bare-URL form configures no auth — use
+  ndslive-server as a proxy or a config.yaml with `http-settings` for
+  authenticated services
 - Default Docker image version pinned to package (`--image-version` defaults to
   matching calver instead of `"latest"`)
 - SCM-based versioning — package version derived from MapViewer git tags
 
 ### Fixed
 
+- Clipboard copy in the Docker screen now uses the native OS clipboard
+  (`clip.exe` / `pbcopy` / `wl-copy`/`xclip`/`xsel`) instead of relying on the
+  OSC 52 terminal escape, which is unreliable on Windows; warns when a copy
+  cannot be confirmed
+- Quitting the TUI no longer hangs — the log-follow stream is torn down by
+  terminating the process before closing pipes, and container shutdown is
+  bounded so the terminal is always returned to the user
+- `localhost`/`127.0.0.1` in service `uri` values and `http-settings` `scope`
+  values are now translated to `host.docker.internal`, so a service running on
+  the host machine is reachable from the container without `--network host`
 - Container readiness check uses log sentinel before HTTP polling to avoid
   startup crash (mapget#151)
 

{nds_mapviewer-2026.2.1.dev92/src/nds_mapviewer.egg-info → nds_mapviewer-2026.2.1.dev94}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nds-mapviewer
-Version: 2026.2.1.dev92
+Version: 2026.2.1.dev94
 Summary: CLI to run the NDS MapViewer Docker container for visualizing map data (NDS.Live, GeoJSON, and more)
 Author-email: NDS Association <support@nds-association.org>
 License: Proprietary
@@ -74,14 +74,48 @@ mapviewer                         # HomeScreen (or auto-loads ~/.nds/config.yaml
 mapviewer /path/to/data.ndslive   # View a local FileStore
 mapviewer /path/to/folder         # View a local SmartLayer folder
 mapviewer /path/to/geojson/       # View a GeoJSON folder
+mapviewer https://host/openapi.json  # Connect to a remote service (unauthenticated)
 mapviewer --demo                  # Try it with NDS Islands sample data
 
 mapviewer mywork                  # Load a saved config by name
 mapviewer /path/a.ndslive /path/b # Multiple sources at once
+
+mapviewer --demo --debug          # Enable debug logging in the container
+mapviewer --demo --env KEY=VALUE  # Set a custom container env var (repeatable)
+mapviewer --demo --network host   # Run the container on the host network
 ```
 
 All commands accept `-e community|member` and `-i VERSION`.
 
+### Remote service URLs
+
+A source can be an http(s) service URL (e.g. `mapviewer https://my-host/openapi.json`),
+which is turned into a `SmartLayerTileService`. The bare-URL form configures **no
+authentication** — for protected services, proxy them through `ndslive-server` or
+declare the service in a `config.yaml` with an `http-settings` block (api-key, basic,
+bearer, OAuth2, proxy).
+
+For a service running on your own machine, use `localhost`/`127.0.0.1`
+(e.g. `mapviewer http://127.0.0.1:8080/openapi.json`) — it is automatically
+rewritten to `host.docker.internal` so the container can reach it. You do **not**
+need `--network host` for this.
+
+### Container environment variables
+
+`--debug` turns on verbose logging in the MapViewer container (shorthand for
+`--env HTTP_LOG_LEVEL=debug`). Use `--env KEY=VALUE` (repeatable, short form
+`-E`) to pass arbitrary environment variables into the container; explicit
+`--env` entries override `--debug` on key collision. The resulting `-e` flags
+appear in the Docker screen's "Copy Command" output.
+
+### Container network
+
+`--network NAME` attaches the container to a specific network (e.g. a custom
+bridge or `host`). With `--network host` the container binds the host's port
+directly, so `--port`/`--bind` are ignored and the MapViewer is reached on its
+internal port (8089). Host networking behaves differently across platforms and
+runtimes — it is intended as a connectivity workaround.
+
 If `~/.nds/config.yaml` exists, `mapviewer` (with no arguments) loads it
 automatically and goes straight to the RunScreen.
 
@@ -89,6 +123,10 @@ If you edit `~/.nds/config.yaml` manually, use host paths there, not container
 paths. The CLI translates them into the correct container mounts when it starts
 the container runtime.
 
+The run screen shows, below the info banner, the source you passed (a config
+file or a directly-given data-source path such as a `*.ndslive` filestore) and
+the mapped config that was generated and mounted into the container.
+
 ## Editions
 
 | Edition | Formats | Access |

{nds_mapviewer-2026.2.1.dev92 → nds_mapviewer-2026.2.1.dev94}/README.md

@@ -41,14 +41,48 @@ mapviewer                         # HomeScreen (or auto-loads ~/.nds/config.yaml
 mapviewer /path/to/data.ndslive   # View a local FileStore
 mapviewer /path/to/folder         # View a local SmartLayer folder
 mapviewer /path/to/geojson/       # View a GeoJSON folder
+mapviewer https://host/openapi.json  # Connect to a remote service (unauthenticated)
 mapviewer --demo                  # Try it with NDS Islands sample data
 
 mapviewer mywork                  # Load a saved config by name
 mapviewer /path/a.ndslive /path/b # Multiple sources at once
+
+mapviewer --demo --debug          # Enable debug logging in the container
+mapviewer --demo --env KEY=VALUE  # Set a custom container env var (repeatable)
+mapviewer --demo --network host   # Run the container on the host network
 ```
 
 All commands accept `-e community|member` and `-i VERSION`.
 
+### Remote service URLs
+
+A source can be an http(s) service URL (e.g. `mapviewer https://my-host/openapi.json`),
+which is turned into a `SmartLayerTileService`. The bare-URL form configures **no
+authentication** — for protected services, proxy them through `ndslive-server` or
+declare the service in a `config.yaml` with an `http-settings` block (api-key, basic,
+bearer, OAuth2, proxy).
+
+For a service running on your own machine, use `localhost`/`127.0.0.1`
+(e.g. `mapviewer http://127.0.0.1:8080/openapi.json`) — it is automatically
+rewritten to `host.docker.internal` so the container can reach it. You do **not**
+need `--network host` for this.
+
+### Container environment variables
+
+`--debug` turns on verbose logging in the MapViewer container (shorthand for
+`--env HTTP_LOG_LEVEL=debug`). Use `--env KEY=VALUE` (repeatable, short form
+`-E`) to pass arbitrary environment variables into the container; explicit
+`--env` entries override `--debug` on key collision. The resulting `-e` flags
+appear in the Docker screen's "Copy Command" output.
+
+### Container network
+
+`--network NAME` attaches the container to a specific network (e.g. a custom
+bridge or `host`). With `--network host` the container binds the host's port
+directly, so `--port`/`--bind` are ignored and the MapViewer is reached on its
+internal port (8089). Host networking behaves differently across platforms and
+runtimes — it is intended as a connectivity workaround.
+
 If `~/.nds/config.yaml` exists, `mapviewer` (with no arguments) loads it
 automatically and goes straight to the RunScreen.
 
@@ -56,6 +90,10 @@ If you edit `~/.nds/config.yaml` manually, use host paths there, not container
 paths. The CLI translates them into the correct container mounts when it starts
 the container runtime.
 
+The run screen shows, below the info banner, the source you passed (a config
+file or a directly-given data-source path such as a `*.ndslive` filestore) and
+the mapped config that was generated and mounted into the container.
+
 ## Editions
 
 | Edition | Formats | Access |

{nds_mapviewer-2026.2.1.dev92 → nds_mapviewer-2026.2.1.dev94/src/nds_mapviewer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nds-mapviewer
-Version: 2026.2.1.dev92
+Version: 2026.2.1.dev94
 Summary: CLI to run the NDS MapViewer Docker container for visualizing map data (NDS.Live, GeoJSON, and more)
 Author-email: NDS Association <support@nds-association.org>
 License: Proprietary
@@ -74,14 +74,48 @@ mapviewer                         # HomeScreen (or auto-loads ~/.nds/config.yaml
 mapviewer /path/to/data.ndslive   # View a local FileStore
 mapviewer /path/to/folder         # View a local SmartLayer folder
 mapviewer /path/to/geojson/       # View a GeoJSON folder
+mapviewer https://host/openapi.json  # Connect to a remote service (unauthenticated)
 mapviewer --demo                  # Try it with NDS Islands sample data
 
 mapviewer mywork                  # Load a saved config by name
 mapviewer /path/a.ndslive /path/b # Multiple sources at once
+
+mapviewer --demo --debug          # Enable debug logging in the container
+mapviewer --demo --env KEY=VALUE  # Set a custom container env var (repeatable)
+mapviewer --demo --network host   # Run the container on the host network
 ```
 
 All commands accept `-e community|member` and `-i VERSION`.
 
+### Remote service URLs
+
+A source can be an http(s) service URL (e.g. `mapviewer https://my-host/openapi.json`),
+which is turned into a `SmartLayerTileService`. The bare-URL form configures **no
+authentication** — for protected services, proxy them through `ndslive-server` or
+declare the service in a `config.yaml` with an `http-settings` block (api-key, basic,
+bearer, OAuth2, proxy).
+
+For a service running on your own machine, use `localhost`/`127.0.0.1`
+(e.g. `mapviewer http://127.0.0.1:8080/openapi.json`) — it is automatically
+rewritten to `host.docker.internal` so the container can reach it. You do **not**
+need `--network host` for this.
+
+### Container environment variables
+
+`--debug` turns on verbose logging in the MapViewer container (shorthand for
+`--env HTTP_LOG_LEVEL=debug`). Use `--env KEY=VALUE` (repeatable, short form
+`-E`) to pass arbitrary environment variables into the container; explicit
+`--env` entries override `--debug` on key collision. The resulting `-e` flags
+appear in the Docker screen's "Copy Command" output.
+
+### Container network
+
+`--network NAME` attaches the container to a specific network (e.g. a custom
+bridge or `host`). With `--network host` the container binds the host's port
+directly, so `--port`/`--bind` are ignored and the MapViewer is reached on its
+internal port (8089). Host networking behaves differently across platforms and
+runtimes — it is intended as a connectivity workaround.
+
 If `~/.nds/config.yaml` exists, `mapviewer` (with no arguments) loads it
 automatically and goes straight to the RunScreen.
 
@@ -89,6 +123,10 @@ If you edit `~/.nds/config.yaml` manually, use host paths there, not container
 paths. The CLI translates them into the correct container mounts when it starts
 the container runtime.
 
+The run screen shows, below the info banner, the source you passed (a config
+file or a directly-given data-source path such as a `*.ndslive` filestore) and
+the mapped config that was generated and mounted into the container.
+
 ## Editions
 
 | Edition | Formats | Access |

{nds_mapviewer-2026.2.1.dev92 → nds_mapviewer-2026.2.1.dev94}/src/nds_mapviewer.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/nds_mapviewer.egg-info/top_level.txt
 src/ndslive/mapviewer/__init__.py
 src/ndslive/mapviewer/browser.py
 src/ndslive/mapviewer/cli.py
+src/ndslive/mapviewer/clipboard.py
 src/ndslive/mapviewer/config.py
 src/ndslive/mapviewer/container_runtime.py
 src/ndslive/mapviewer/docker_client.py
@@ -21,6 +22,8 @@ src/ndslive/mapviewer/ui.py
 src/ndslive/mapviewer/viewer.py
 tests/conftest.py
 tests/test_cli.py
+tests/test_clipboard.py
 tests/test_config.py
 tests/test_docker_client.py
+tests/test_tui.py
 tests/test_viewer.py

{nds_mapviewer-2026.2.1.dev92 → nds_mapviewer-2026.2.1.dev94}/src/ndslive/mapviewer/cli.py

@@ -73,6 +73,37 @@ def _get_pull_policy_default() -> str:
     return "prompt"
 
 
+def _build_environment(args: argparse.Namespace) -> dict[str, str]:
+    """Build the container environment dict from ``--debug`` and ``--env``.
+
+    ``--debug`` is shorthand for ``HTTP_LOG_LEVEL=debug``. Explicit ``--env``
+    entries are applied afterwards, so they win on key collision.
+
+    Raises:
+        SystemExit: If an ``--env`` entry is not in ``KEY=VALUE`` form.
+    """
+    env: dict[str, str] = {}
+    if getattr(args, "debug", False):
+        env["HTTP_LOG_LEVEL"] = "debug"
+    for item in getattr(args, "env", None) or []:
+        if "=" not in item:
+            console.print(
+                f"[red]Error:[/red] Invalid --env value '{item}', "
+                "expected KEY=VALUE"
+            )
+            raise SystemExit(2)
+        key, _, value = item.partition("=")
+        key = key.strip()
+        if not key:
+            console.print(
+                f"[red]Error:[/red] Invalid --env value '{item}', "
+                "empty key"
+            )
+            raise SystemExit(2)
+        env[key] = value
+    return env
+
+
 # ---------------------------------------------------------------------------
 # Command handler
 # ---------------------------------------------------------------------------
@@ -86,6 +117,7 @@ def cmd_main(args: argparse.Namespace) -> int:
         create_folder_config,
         create_geojson_config,
         create_classic_config,
+        create_service_config,
         get_demo_config,
     )
     from .tui import MapViewerApp
@@ -97,6 +129,8 @@ def cmd_main(args: argparse.Namespace) -> int:
     bind_address = args.bind
     pull_policy = args.pull_policy
     source_args = args.sources
+    environment = _build_environment(args)
+    network = getattr(args, "network", None)
 
     # --demo → demo config
     if args.demo:
@@ -108,6 +142,8 @@ def cmd_main(args: argparse.Namespace) -> int:
             port=port,
             bind_address=bind_address,
             pull_policy=pull_policy,
+            environment=environment,
+            network=network,
             run_config=config,
             run_label="Demo (NDS Islands)",
             is_demo=True,
@@ -128,6 +164,8 @@ def cmd_main(args: argparse.Namespace) -> int:
                     port=port,
                     bind_address=bind_address,
                     pull_policy=pull_policy,
+                    environment=environment,
+                    network=network,
                     run_config=config,
                     run_config_path=DEFAULT_CONFIG,
                     run_label="~/.nds/config.yaml",
@@ -151,6 +189,8 @@ def cmd_main(args: argparse.Namespace) -> int:
                     port=port,
                     bind_address=bind_address,
                     pull_policy=pull_policy,
+                    environment=environment,
+                    network=network,
                     run_config=config,
                     run_config_path=LEGACY_CONFIG,
                     run_label="~/.nds/mapviewer.yaml",
@@ -167,6 +207,8 @@ def cmd_main(args: argparse.Namespace) -> int:
             port=port,
             bind_address=bind_address,
             pull_policy=pull_policy,
+            environment=environment,
+            network=network,
         )
         app.run()
         return 0
@@ -178,6 +220,18 @@ def cmd_main(args: argparse.Namespace) -> int:
     source_config_path: Path | None = None
 
     for source_arg in source_args:
+        # Remote service: an http(s) URL is turned into a SmartLayerTileService
+        # source directly. Checked before the path:mapId split below because
+        # URLs contain colons. No auth is configured for the bare-URL form —
+        # use ndslive-server as a proxy or a config.yaml for authenticated
+        # services.
+        if source_arg.startswith(("http://", "https://")):
+            config = create_service_config(source_arg)
+            descriptions.append(f"service: {source_arg}")
+            all_sources.extend(config.get("sources", []))
+            all_http_settings.extend(config.get("http-settings", []))
+            continue
+
         # Parse optional path:mapId syntax
         custom_map_id = None
         if ":" in source_arg:
@@ -240,9 +294,12 @@ def cmd_main(args: argparse.Namespace) -> int:
         port=port,
         bind_address=bind_address,
         pull_policy=pull_policy,
+        environment=environment,
+        network=network,
         run_config=merged,
         run_config_path=source_config_path,
         run_label=source_desc,
+        run_source_paths=source_args,
     )
     app.run()
     return 0
@@ -269,6 +326,9 @@ Examples:
   mapviewer /path/to/geojson/folder
   mapviewer --demo
 
+  # Connect to a remote service (unauthenticated)
+  mapviewer https://my-host/openapi.json
+
   # Multiple sources at once
   mapviewer /path/a.ndslive /path/to/geojson/
 
@@ -291,7 +351,7 @@ Examples:
     parser.add_argument(
         "sources",
         nargs="*",
-        help="One or more data source paths or saved config names",
+        help="One or more data source paths, http(s) service URLs, or saved config names",
     )
     parser.add_argument(
         "--demo",
@@ -323,6 +383,27 @@ Examples:
         "--bind", default="127.0.0.1",
         help="Host address to bind (default: 127.0.0.1, use 0.0.0.0 for network access)",
     )
+    parser.add_argument(
+        "--env", "-E",
+        action="append",
+        metavar="KEY=VALUE",
+        dest="env",
+        default=[],
+        help="Set a container environment variable (repeatable), "
+             "e.g. --env HTTP_LOG_LEVEL=debug",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging in the container (sets HTTP_LOG_LEVEL=debug)",
+    )
+    parser.add_argument(
+        "--network",
+        metavar="NAME",
+        default=None,
+        help="Container network to attach (e.g. 'host'). With 'host' the "
+             "MapViewer binds the host port directly and --port/--bind are ignored.",
+    )
 
     pull_group = parser.add_mutually_exclusive_group()
     pull_group.add_argument(

nds_mapviewer-2026.2.1.dev94/src/ndslive/mapviewer/clipboard.py

@@ -0,0 +1,81 @@
+"""Cross-platform clipboard helper.
+
+Textual's ``App.copy_to_clipboard`` relies on the OSC 52 terminal escape
+sequence, which many Windows terminals (conhost, some Windows Terminal
+configs, PowerShell hosts) silently drop — so the copy buttons appear to do
+nothing.  This module copies via the native OS clipboard utility first and
+only falls back to OSC 52 when no native tool is available.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+
+
+def _run_copy(cmd: list[str], text: str) -> bool:
+    """Pipe *text* into *cmd* on stdin; return True on success."""
+    try:
+        proc = subprocess.run(
+            cmd,
+            input=text,
+            text=True,
+            capture_output=True,
+            timeout=5,
+        )
+        return proc.returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def _native_copy(text: str) -> bool:
+    """Copy *text* using the platform-native clipboard tool.
+
+    Returns True if a tool was found and reported success.
+    """
+    system = platform.system()
+
+    if system == "Windows":
+        # clip.exe ships with every supported Windows version.
+        clip = shutil.which("clip") or shutil.which("clip.exe")
+        if clip:
+            return _run_copy([clip], text)
+        return False
+
+    if system == "Darwin":
+        if shutil.which("pbcopy"):
+            return _run_copy(["pbcopy"], text)
+        return False
+
+    # Linux / other Unix — try Wayland then X11 helpers.
+    if shutil.which("wl-copy"):
+        if _run_copy(["wl-copy"], text):
+            return True
+    if shutil.which("xclip"):
+        if _run_copy(["xclip", "-selection", "clipboard"], text):
+            return True
+    if shutil.which("xsel"):
+        if _run_copy(["xsel", "--clipboard", "--input"], text):
+            return True
+    return False
+
+
+def copy_text(text: str, app=None) -> bool:
+    """Copy *text* to the clipboard, returning True on confirmed success.
+
+    Tries the native OS clipboard utility first (reliable on Windows where
+    OSC 52 is commonly unsupported).  If no native tool is available and an
+    *app* is given, falls back to Textual's OSC 52 escape — which cannot be
+    confirmed, so this returns False to let callers warn the user.
+    """
+    if _native_copy(text):
+        return True
+
+    if app is not None:
+        try:
+            app.copy_to_clipboard(text)
+        except Exception:
+            pass
+
+    return False

{nds_mapviewer-2026.2.1.dev92 → nds_mapviewer-2026.2.1.dev94}/src/ndslive/mapviewer/config.py

@@ -138,6 +138,22 @@ def _transform_localhost(host: str) -> str:
     return host
 
 
+def _transform_localhost_url(url: str) -> str:
+    """Rewrite a localhost host in an http(s) URL to host.docker.internal.
+
+    Used for source ``uri`` values and ``http-settings`` ``scope`` values so a
+    service running on the host machine (e.g. ``http://127.0.0.1:8080/...``) is
+    reachable from inside the container. Non-http(s) values and non-localhost
+    hosts are returned unchanged.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        return url
+    if not _is_localhost(parsed.netloc):
+        return url
+    return parsed._replace(netloc=_transform_localhost(parsed.netloc)).geturl()
+
+
 def _is_external_or_bundle_url(value: str) -> bool:
     """Return True for URLs that should not be rewritten as local files."""
     return value.startswith(("http://", "https://", "bundle"))
@@ -313,6 +329,12 @@ def transform_config(
             if local_path:
                 local_paths.append(local_path)
                 path_locations.append(("sources", idx, "uri", uri))
+            else:
+                # Remote service on the host: localhost/127.0.0.1 must become
+                # host.docker.internal to be reachable from inside the container.
+                new_uri = _transform_localhost_url(uri)
+                if new_uri != uri:
+                    transformed["sources"][idx]["uri"] = new_uri
 
         # Check folder field (ClassicFolder, GeoJsonFolder)
         folder = source.get("folder", "")
@@ -327,6 +349,15 @@ def transform_config(
         if host and _is_localhost(host):
             transformed["sources"][idx]["host"] = _transform_localhost(host)
 
+    # Translate localhost in http-settings scopes so auth settings keep
+    # matching the rewritten source URIs.
+    for setting in transformed.get("http-settings", []) or []:
+        scope = setting.get("scope", "")
+        if scope:
+            new_scope = _transform_localhost_url(scope)
+            if new_scope != scope:
+                setting["scope"] = new_scope
+
     # Find optimal mount points
     path_to_mount_parent = _find_common_parent(local_paths)
 

{nds_mapviewer-2026.2.1.dev92 → nds_mapviewer-2026.2.1.dev94}/src/ndslive/mapviewer/docker_client.py

@@ -36,6 +36,9 @@ IMAGE_NAME = "nds-mapviewer"
 
 KNOWN_TAGS = ["latest", "dev", "dev-rc"]
 
+# Port the MapViewer HTTP server listens on inside the container.
+CONTAINER_PORT = 8089
+
 
 # ---------------------------------------------------------------------------
 # Container info dataclass (replaces Docker SDK Container object)
@@ -543,6 +546,7 @@ def run_container(
     config_dir: str | Path | None = None,
     volumes: list[str] | None = None,
     environment: dict[str, str] | None = None,
+    network: str | None = None,
     name: str = CONTAINER_NAME,
     detach: bool = True,
     remove_existing: bool = False,
@@ -556,6 +560,9 @@ def run_container(
         config_dir: Config directory to mount at ``/config``.
         volumes: Additional volume mounts as ``"host:container:mode"`` strings.
         environment: Environment variables.
+        network: Container network to attach (e.g. ``"host"``). When ``"host"``,
+            port publishing is skipped because the container binds the host's
+            port directly.
         name: Container name.
         detach: Run in detached mode.
         remove_existing: Remove existing container if running.
@@ -571,12 +578,20 @@ def run_container(
             rt.run("stop", "-t", "2", name, timeout=30)
         rt.run("rm", name, check=False, timeout=10)
 
+    use_host_net = network == "host"
+
     # Build command
     cmd: list[str] = ["run"]
     if detach:
         cmd.append("-d")
     cmd.extend(["--name", name])
-    cmd.extend(["-p", f"{bind_address}:{port}:8089"])
+    if network:
+        cmd.extend(["--network", network])
+    # Host networking ignores published ports — the container binds the
+    # host's port directly — so skip the -p mapping to avoid the runtime
+    # warning/error.
+    if not use_host_net:
+        cmd.extend(["-p", f"{bind_address}:{port}:{CONTAINER_PORT}"])
 
     # Volume mounts
     if config_dir:
@@ -592,8 +607,10 @@ def run_container(
         for key, value in environment.items():
             cmd.extend(["-e", f"{key}={value}"])
 
-    # Extra hosts for host.docker.internal on Linux
-    cmd.extend(rt.get_extra_host_args())
+    # Extra hosts for host.docker.internal on Linux. The host-gateway mapping
+    # conflicts with host networking, so skip it in that mode.
+    if not use_host_net:
+        cmd.extend(rt.get_extra_host_args())
 
     # Labels
     cmd.extend(["--label", "app=ndslive-mapviewer"])
@@ -673,6 +690,22 @@ class ContainerLogStream:
     def close(self, timeout: float = 3.0) -> None:
         if self._proc.poll() is not None:
             return
+        # Terminate the process FIRST so the OS closes the write end of the
+        # pipe and any thread blocked in `for line in proc.stdout` unblocks
+        # via EOF. Closing the pipe from another thread while it is being
+        # read is unsafe in CPython and can leave the reader (and thus app
+        # shutdown) hung indefinitely.
+        self._proc.terminate()
+        try:
+            self._proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            self._proc.kill()
+            try:
+                self._proc.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                pass
+        # Now that the process is gone, closing the pipes is safe and frees
+        # the file descriptors.
         for pipe in (getattr(self._proc, "stdout", None), getattr(self._proc, "stderr", None)):
             if pipe is None:
                 continue
@@ -680,17 +713,6 @@ class ContainerLogStream:
                 pipe.close()
             except Exception:
                 pass
-        self._proc.terminate()
-        try:
-            self._proc.wait(timeout=timeout)
-            return
-        except subprocess.TimeoutExpired:
-            pass
-        self._proc.kill()
-        try:
-            self._proc.wait(timeout=timeout)
-        except subprocess.TimeoutExpired:
-            pass
 
 
 _READY_SENTINEL = "NDS MapViewer is ready!"