web

Serve a CLABE experiment's terminal UI over a local web port.

Thin wrapper around :mod:textual_serve so the existing Textual TUI can be reached from a browser without building a separate web frontend. The server binds to localhost by default; for remote access, forward the port over SSH (ssh -L) rather than exposing it to the network.

This is an optional feature: install the web extra (pip install 'aind-clabe[web]') to make it available.

serve

serve(
    command: str,
    *,
    host: str = DEFAULT_HOST,
    port: int = DEFAULT_PORT,
    title: str = "CLABE",
    open_browser: bool = False,
) -> None

Serves a CLABE TUI command over a local web port.

Each browser connection launches command as its own subprocess. The clabe serve command guards against this by passing --single-session, so a stray second connection refuses to start rather than fighting the live session over the rig.

Parameters:

Name	Type	Description	Default
command	str	Shell command that starts the CLABE TUI, e.g. "python -m clabe.cli run experiment.py --frontend tui".	required
host	str	Interface to bind. Defaults to localhost; keep it there and use SSH port forwarding for remote access.	DEFAULT_HOST
port	int	TCP port to listen on.	DEFAULT_PORT
title	str	Title shown in the browser tab.	'CLABE'
open_browser	bool	When set, open the web UI in the local default browser once the server is ready. Leave off for headless/remote hosts.	False

Raises:

Type	Description
ImportError	If the optional web extra is not installed.
RuntimeError	If the server cannot bind (e.g. the port is in use).

Source code in src/clabe/web.py

def serve(
    command: str,
    *,
    host: str = DEFAULT_HOST,
    port: int = DEFAULT_PORT,
    title: str = "CLABE",
    open_browser: bool = False,
) -> None:
    """
    Serves a CLABE TUI command over a local web port.

    Each browser connection launches ``command`` as its own subprocess. The
    ``clabe serve`` command guards against this by passing ``--single-session``,
    so a stray second connection refuses to start rather than fighting the live
    session over the rig.

    Args:
        command: Shell command that starts the CLABE TUI, e.g.
            ``"python -m clabe.cli run experiment.py --frontend tui"``.
        host: Interface to bind. Defaults to localhost; keep it there and use
            SSH port forwarding for remote access.
        port: TCP port to listen on.
        title: Title shown in the browser tab.
        open_browser: When set, open the web UI in the local default browser
            once the server is ready. Leave off for headless/remote hosts.

    Raises:
        ImportError: If the optional ``web`` extra is not installed.
        RuntimeError: If the server cannot bind (e.g. the port is in use).
    """
    try:
        from textual_serve.server import Server
    except ImportError as exc:
        raise ImportError(
            "Serving the web UI requires the optional 'web' extra. Install it with: pip install 'aind-clabe[web]'"
        ) from exc

    from aiohttp import web as aiohttp_web

    templates_dir = _patched_templates_dir()
    kwargs = {"host": host, "port": port, "title": title}
    if templates_dir is not None:
        kwargs["templates_path"] = templates_dir
    server = Server(command, **kwargs)
    original_make_app = server._make_app

    async def _make_app_with_finish():
        """Builds textual-serve's app and adds the Finish shutdown route."""
        app = await original_make_app()

        async def _handle_finish(request):
            """Schedules a graceful shutdown and acknowledges the request."""
            asyncio.get_running_loop().call_later(0.25, server.request_exit)
            return aiohttp_web.json_response({"status": "stopping"})

        app.router.add_post("/finish", _handle_finish)
        return app

    server._make_app = _make_app_with_finish

    _announce(host, port)
    if open_browser:
        _open_browser_when_ready(host, port)
    try:
        server.serve()
    except OSError as exc:
        raise RuntimeError(
            f"Could not start the web server on {host}:{port} ({exc}). "
            "Is the port already in use? Try a different --port."
        ) from exc