seren-observatory 0.0.0.dev0__tar.gz

seren_observatory-0.0.0.dev0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: seren-observatory
+Version: 0.0.0.dev0
+Summary: Per-node management plane for the Seren cluster - manifest-driven service lifecycle, status, and orchestration.
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/ChadRoesler/SerenObservatory
+Project-URL: Repository, https://github.com/ChadRoesler/SerenObservatory
+Project-URL: Bug Tracker, https://github.com/ChadRoesler/SerenObservatory/issues
+Keywords: seren,jetson,observatory,fastapi,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-multipart>=0.0.12
+Requires-Dist: seren-meninges<2,>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: httpx2>=0.28; extra == "dev"

seren_observatory-0.0.0.dev0/SerenObservatory.pyproj

@@ -0,0 +1,123 @@
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
+  <PropertyGroup>
+    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">10.0</VisualStudioVersion>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectGuid>{e20990c9-b0f0-46ff-9f69-6537d00b7fbf}</ProjectGuid>
+    <ProjectHome>.</ProjectHome>
+    <ProjectTypeGuids>{1b580a1a-fdb3-4b32-83e1-6407eb2722e6};{888888a0-9f3d-457c-b088-3a5042f75d52}</ProjectTypeGuids>
+    <StartupFile>seren_observatory/app.py</StartupFile>
+    <WorkingDirectory>.</WorkingDirectory>
+    <OutputPath>dist\</OutputPath>
+    <Name>SerenObservatory</Name>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <DebugSymbols>true</DebugSymbols>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <DebugSymbols>true</DebugSymbols>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="seren_observatory\config.py" />
+    <Compile Include="seren_observatory\requirements.txt" />
+    <Compile Include="seren_observatory\app.py" />
+    <Compile Include="seren_observatory\auth.py" />
+    <Compile Include="seren_observatory\lifecycle.py" />
+    <Compile Include="seren_observatory\manifests.py" />
+    <Compile Include="seren_observatory\request_log.py" />
+    <Compile Include="seren_observatory\service_routes.py" />
+    <Compile Include="seren_observatory\system_routes.py" />
+    <Compile Include="seren_observatory\_version.py" />
+    <Compile Include="seren_observatory\__init__.py" />
+    <Compile Include="seren_observatory\services\comfy.py" />
+    <Compile Include="seren_observatory\services\coral.py" />
+    <Compile Include="seren_observatory\services\kokoro.py" />
+    <Compile Include="seren_observatory\services\llama.py" />
+    <Compile Include="seren_observatory\services\whisper.py" />
+    <Compile Include="seren_observatory\services\__init__.py" />
+    <Compile Include="seren_observatory\__main__.py" />
+    <Compile Include="tests\conftest.py" />
+    <Compile Include="tests\test_app.py" />
+    <Compile Include="tests\test_auth.py" />
+    <Compile Include="tests\test_config.py" />
+    <Compile Include="tests\test_manifests.py" />
+    <Compile Include="tests\__init__.py" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Include="seren_observatory\requirements.txt" />
+    <None Include="pyproject.toml" />
+    <None Include="README.md" Condition="Exists('README.md')" />
+  </ItemGroup>
+  <ItemGroup>
+    <Folder Include="seren_observatory\" />
+    <Folder Include="seren_observatory\services\" />
+    <Folder Include="seren_observatory\services\__pycache__\" />
+    <Folder Include="seren_observatory\viewer\" />
+    <Folder Include="seren_observatory\viewer\ui\" />
+    <Folder Include="tests\" />
+  </ItemGroup>
+  <ItemGroup>
+    <Content Include="seren-observatory.service.sample" />
+    <Content Include="seren-observatory.yaml.sample" />
+    <Content Include="seren_observatory\services\__pycache__\comfy.cpython-311.pyc" />
+    <Content Include="seren_observatory\services\__pycache__\coral.cpython-311.pyc" />
+    <Content Include="seren_observatory\services\__pycache__\kokoro.cpython-311.pyc" />
+    <Content Include="seren_observatory\services\__pycache__\llama.cpython-311.pyc" />
+    <Content Include="seren_observatory\services\__pycache__\whisper.cpython-311.pyc" />
+    <Content Include="seren_observatory\services\__pycache__\__init__.cpython-311.pyc" />
+    <Content Include="seren_observatory\viewer\ui\body.html" />
+    <Content Include="seren_observatory\viewer\ui\header_aside.html" />
+    <Content Include="seren_observatory\viewer\ui\scripts.js" />
+    <Content Include="seren_observatory\viewer\ui\styles.css" />
+    <Content Include="seren_observatory\viewer\ui\tabs.html" />
+  </ItemGroup>
+  <Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\Python Tools\Microsoft.PythonTools.targets" />
+  <!--
+    Publish target: runs ONLY when you explicitly invoke it.
+      VS:        right-click project -> Publish (or build configuration set
+                 to invoke the Publish target via msbuild /t:Publish)
+      Command:   msbuild SerenObservatory.pyproj /t:Publish /p:Configuration=Release
+
+    What it does:
+      1. Cleans __pycache__ from observatory/ so they don't end up in the tarball
+      2. Runs `tar` (Windows 10+ ships bsdtar at C:\Windows\System32\tar.exe)
+         to create $(PublishTarball) with `observatory/` at the top level — no
+         wrapping directory, no metadata files. This is exactly the layout
+         install_observatory_common in seren-v5/common.sh expects.
+      3. Verifies the tarball contains observatory/__init__.py at the top level
+         so a half-built artifact doesn't sneak through.
+
+    Why not AfterBuild: that fires on every build (including F5 to debug),
+    which would slow your edit-test loop and produce stale tarballs in
+    half-finished states. Publish is a deliberate "I'm ready to ship" step.
+  -->
+  <Target Name="Publish">
+    <Message Text="==&gt; Cleaning __pycache__ from seren_observatory/" Importance="high" />
+    <ItemGroup>
+      <PycacheDirs Include="seren_observatory\**\__pycache__\**" />
+    </ItemGroup>
+    <Delete Files="@(PycacheDirs)" />
+    <RemoveDir Directories="observatory\__pycache__;observatory\services\__pycache__" />
+    <Message Text="==&gt; Ensuring publish dir exists: $(SerenSetupDir)" Importance="high" />
+    <MakeDir Directories="$(SerenSetupDir)" Condition="!Exists('$(SerenSetupDir)')" />
+    <Message Text="==&gt; Building $(PublishTarball)" Importance="high" />
+    <!--
+      tar.exe (bsdtar on Win10+) syntax:
+        -c   create
+        -z   gzip
+        -f   output file
+      We tar from $(ProjectHome) so the path inside the archive is just
+      `seren_observatory/...` with no leading directory.
+    -->
+    <Exec Command="tar -czf &quot;$(PublishTarball)&quot; seren-observatory" WorkingDirectory="$(ProjectHome)" />
+    <Message Text="==&gt; Verifying tarball layout" Importance="high" />
+    <!--
+      Verify seren_observatory/__init__.py is present (correct package layout).
+      Verify seren_observatory/requirements.txt is present so nodes always have it
+      available for pip install -r after extract.
+    -->
+    <Exec Command="tar -tzf &quot;$(PublishTarball)&quot; | findstr /B /L &quot;seren_observatory/__init__.py&quot; &gt; nul" WorkingDirectory="$(ProjectHome)" />
+    <Exec Command="tar -tzf &quot;$(PublishTarball)&quot; | findstr /B /L &quot;seren_observatory/requirements.txt&quot; &gt; nul" WorkingDirectory="$(ProjectHome)" />
+    <Message Text="==&gt; Published: $(PublishTarball)" Importance="high" />
+  </Target>
+</Project>

seren_observatory-0.0.0.dev0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=70", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+# ── Project metadata ──────────────────────────────────────────────────────
+[project]
+name = "seren-observatory"
+dynamic = ["version"]
+description = "Per-node management plane for the Seren cluster - manifest-driven service lifecycle, status, and orchestration."
+license = { text = "GPL-3.0-or-later" }
+requires-python = ">=3.10"
+keywords = ["seren", "jetson", "observatory", "fastapi", "llm"]
+classifiers = [
+	"Development Status :: 4 - Beta",
+	"Environment :: No Input/Output (Daemon)",
+	"Framework :: FastAPI",
+	"Intended Audience :: Developers",
+	"Operating System :: POSIX :: Linux",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3.10",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Topic :: System :: Systems Administration",
+	"License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+]
+
+dependencies = [
+	"fastapi>=0.115.0",
+	"uvicorn[standard]>=0.32.0",
+	"pydantic>=2.9.0",
+	"httpx>=0.27.0",
+	"python-multipart>=0.0.12",
+	# Shared Seren core: get_version + the viewer baseplate (render_from_dir).
+	# NOTE: config + auth deliberately do NOT come from Meninges here - the
+	# Observatory's bearer is a ~/.seren/secrets.json safety interlock, not a
+	# Meninges-resolved config token. No [keyring] extra: this service never
+	# writes secrets to the OS keychain.
+	"seren-meninges>=1.0.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+	"pytest>=8.0",
+	"pytest-asyncio>=0.24",
+	"httpx2>=0.28",   # Starlette TestClient's successor HTTP backend (Tom Christie / pydantic); silences the httpx-deprecation warning
+]
+
+[project.scripts]
+seren-observatory = "seren_observatory.app:main"
+
+[project.urls]
+Homepage = "https://github.com/ChadRoesler/SerenObservatory"
+Repository = "https://github.com/ChadRoesler/SerenObservatory"
+"Bug Tracker" = "https://github.com/ChadRoesler/SerenObservatory/issues"
+
+# ── setuptools-scm: version from git tags ────────────────────────────────
+# Tags must be the form v1.2.3 on the repo root.
+# `python -m build` with no tags → 0.1.dev0+g<hash>.
+# SETUPTOOLS_SCM_PRETEND_VERSION overrides for local dev without tags.
+[tool.setuptools_scm]
+# Write version into the installed package so importlib.metadata works.
+# The file is gitignored - never commit it.
+version_file = "seren_observatory/_version.py"
+# Strip the leading 'v' so "v1.2.3" → "1.2.3"
+tag_regex = "^v(?P<version>[0-9]+\\.[0-9]+\\.[0-9]+.*)$"
+# Used when no git tags exist (local dev, fresh clone, make test).
+# SETUPTOOLS_SCM_PRETEND_VERSION overrides this when set (CI release builds).
+fallback_version = "0.0.0.dev0"
+
+# ── Package discovery ────────────────────────────────────────────────────
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["seren_observatory*"]
+
+# Ship the viewer fragment bricks inside the wheel: the leaf files in
+# viewer/ui/ that render_from_dir snaps onto the SerenMeninges baseplate.
+# Without this, pip strips non-.py files and GET /viewer renders an empty
+# shell on an installed copy (works in a dev checkout, silently breaks once
+# installed - the classic package-data gotcha).
+[tool.setuptools.package-data]
+seren_observatory = ["viewer/ui/*.html", "viewer/ui/*.css", "viewer/ui/*.js"]
+
+# ── pytest ───────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

seren_observatory-0.0.0.dev0/seren-observatory.service.sample

@@ -0,0 +1,33 @@
+# SerenMemory systemd unit (sample)
+#
+# Install:
+#   1. Edit __TARGET_USER__ and paths below
+#   2. sudo cp seren-observatory.service /etc/systemd/system/
+#   3. sudo systemctl daemon-reload
+#   4. sudo systemctl enable --now seren-observatory
+#
+# Logs:  journalctl -u seren-observatory -f
+
+[Unit]
+Description=SerenObservatory - A monitoring observatory for LLMs and tools
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=__TARGET_USER__
+WorkingDirectory=/home/__TARGET_USER__/seren-observatory
+
+# Use the venv's python. Adjust the venv path to wherever you installed.
+ExecStart=/home/__TARGET_USER__/seren-venvs/observatory/bin/python -m seren_observatory --config /home/__TARGET_USER__/seren-observatory/seren-observatory.yaml
+
+# Config can also come from env - uncomment + set as needed:
+# Environment=SEREN_AGENT_PORT=7777
+# Environment=SEREN_AGENT_MODEL_URL=http://localhost:8090/v1
+# Environment=SEREN_AGENT_BEARER_TOKEN=
+
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

seren_observatory-0.0.0.dev0/seren-observatory.yaml.sample

@@ -0,0 +1,22 @@
+# ═══════════════════════════════════════════════════════════════════════
+#  seren-observatory.yaml - config for SerenObservatory
+# ═══════════════════════════════════════════════════════════════════════
+#
+#  Copy to seren-observatory.yaml, edit, and run:
+#     python -m seren_observatory --config seren-observatory.yaml
+#
+#  Or just run with no config at all - the defaults below are baked in, so
+#  `python -m seren_observatory` works zero-config for a local dev spin.
+#
+#  Env vars override file values (handy for Docker/systemd):
+#     SEREN_AGENT_PORT, SEREN_AGENT_HOST, SEREN_AGENT_BEARER_TOKEN
+#
+# ═══════════════════════════════════════════════════════════════════════
+
+server:
+  host: 0.0.0.0
+  port: 7777
+  # Leave empty for no auth (trusted LAN / dev). Set a token to require
+  #   Authorization: Bearer <token>
+  # on every endpoint except / and /health.
+  bearer_token: ""

seren_observatory-0.0.0.dev0/seren_observatory/__init__.py

@@ -0,0 +1,23 @@
+"""
+seren-observatory - per-Jetson management plane.
+
+HTTP API exposing manifest-driven discovery and lifecycle of locally-installed
+Seren services (llama, kokoro, comfy, whisper, coral). Consumed by:
+    - SerenRuntimeHost (C#) for chat-app workflows
+    - SerenCommandCenter (SCC, future) for cluster orchestration
+    - The NUC dashboard for monitoring
+
+Routes are versioned under /api/v1/. See service_routes.py and system_routes.py.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("seren-observatory")
+except PackageNotFoundError:
+    # Running from a source checkout without an editable install.
+    # Set SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 and run:
+    #   pip install -e ".[dev]"
+    # to resolve this.
+    __version__ = "0.0.0.dev"

seren_observatory-0.0.0.dev0/seren_observatory/__main__.py

@@ -0,0 +1,37 @@
+"""Entry point for `python -m seren_observatory`.
+
+Accepts --config / -c to match the SerenMemory convention (Memory leads, the
+rest follow). Host/port come from the resolved config (which itself layers
+defaults < yaml < env). The bearer token is NOT a config concern - it's loaded
+separately from ~/.seren/secrets.json by auth.load_token(). See config.py.
+"""
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from .app import create_app
+from .config import load_config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="seren_observatory",
+        description="seren-observatory - per-node management plane.")
+    parser.add_argument(
+        "--config", "-c", default=None,
+        help="Path to seren-observatory.yaml (default: $SEREN_AGENT_CONFIG, then "
+             "~/seren-observatory/seren-observatory.yaml, falling back to built-in "
+             "defaults of 0.0.0.0:7777).")
+    args = parser.parse_args()
+
+    cfg = load_config(args.config)
+    app = create_app(cfg)
+
+    print(f"[seren-observatory] listening on {cfg.host}:{cfg.port}")
+    uvicorn.run(app, host=cfg.host, port=cfg.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

seren_observatory-0.0.0.dev0/seren_observatory/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.0.dev0'
+__version_tuple__ = version_tuple = (0, 0, 0, 'dev0')
+
+__commit_id__ = commit_id = None

seren_observatory-0.0.0.dev0/seren_observatory/app.py

@@ -0,0 +1,172 @@
+"""
+seren-observatory - main FastAPI app.
+
+Run with:
+    seren-observatory                          # via the installed console script
+    python -m seren_observatory                # config-aware entry (--config/-c)
+    python -m seren_observatory.app            # directly from the source tree
+    uvicorn seren_observatory.app:app          # ASGI server pointing at module app
+
+or via systemd / a launcher. Listens on 0.0.0.0:7777 by default.
+
+Config: host/port resolve via config.load_config() (defaults < yaml's server:
+block < env vars). The bearer token is loaded SEPARATELY from
+~/.seren/secrets.json by auth.load_token() - it's a safety interlock, not a
+config field. See config.py for why.
+"""
+from __future__ import annotations
+
+import os
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+
+from . import __version__, manifests
+from .auth import BearerAuthMiddleware, load_token
+from .config import ObservatoryConfig, load_config
+from .request_log import RequestLoggingMiddleware
+from .service_routes import register_all_services
+from .system_routes import router as system_router
+
+from seren_meninges import get_version
+from seren_meninges.viewer import render_from_dir
+
+# Version via the shared SerenMeninges helper: the installed wheel's
+# setuptools-scm metadata, falling back to the package __version__ for an
+# editable/dev checkout where dist metadata may be absent. get_version never
+# raises - the same one-liner the rest of the family uses, replacing the old
+# hand-rolled importlib.metadata block that drifted from the others.
+APP_VERSION = get_version("seren-observatory", fallback=__version__)
+
+
+def create_app(cfg: ObservatoryConfig | None = None) -> FastAPI:
+    # cfg is accepted so the config-aware entry points (python -m seren_observatory)
+    # can pass a resolved config. When called with no arg (e.g. the
+    # module-level `app` below, or `uvicorn seren_observatory.app:app`), fall back to
+    # load_config() so behaviour is identical either way. cfg currently carries
+    # host/port; those are consumed by the caller that runs uvicorn, so the app
+    # body doesn't need them - but we resolve it anyway so a future need (e.g.
+    # surfacing the bind in the root page) has it on hand without another load.
+    cfg = cfg or load_config()
+
+    app = FastAPI(
+        title="seren-observatory",
+        version=APP_VERSION,
+        description="Per-Jetson management plane. Manifest-driven service "
+                    "lifecycle, status, and orchestration. Bearer token auth "
+                    "on everything except /api/v1/system/{ping,version}.",
+    )
+
+    # Request logging - wraps every request, captures timing + status +
+    # 500 tracebacks. Logs go to BOTH stderr (journalctl) AND a rotating
+    # file at ~/seren-logs/observatory-requests.log (no sudo needed to read).
+    #
+    # MUST be added BEFORE auth so we log auth-rejected requests too -
+    # that's actually one of the most useful debug signals ("dashboard
+    # is failing - is the bearer token wrong, or is the route 500ing?")
+    #
+    # Starlette/FastAPI middleware order: LIFO at request time. So adding
+    # RequestLoggingMiddleware FIRST means it runs LAST on the way in
+    # (closest to the route), and FIRST on the way out - wrapping the
+    # entire chain. Adding auth SECOND means auth runs BEFORE logging on
+    # request, which is wrong. We want logging OUTERMOST.
+    #
+    # Correct stack (request flow top→bottom):
+    #     RequestLoggingMiddleware  (logs everything, including 401s)
+    #       BearerAuthMiddleware    (rejects unauthed, logging sees the rejection)
+    #         <route handler>
+    #
+    # FastAPI add_middleware adds in REVERSE order at runtime, so we add
+    # auth FIRST (will run inner) and logging SECOND (will run outer).
+    token = load_token()
+    app.add_middleware(BearerAuthMiddleware, expected_token=token)
+    app.add_middleware(RequestLoggingMiddleware)
+
+    # Root info page - no service data, just links + auth status indicator
+    @app.get("/", response_class=HTMLResponse)
+    async def root() -> str:
+        node = manifests.load_node()
+        host = (node or {}).get("hostname", "unknown")
+        auth_state = "configured" if token else "DISABLED (no token in ~/.seren/secrets.json)"
+        return f"""<!doctype html>
+<html><head><title>seren-observatory - {host}</title></head>
+<body style="font-family: system-ui; max-width: 720px; margin: 2rem auto; padding: 0 1rem;">
+<h1>seren-observatory</h1>
+<p>Per-Jetson management plane for the Seren cluster.</p>
+<dl>
+  <dt>Hostname:</dt> <dd>{host}</dd>
+  <dt>Observatory version:</dt> <dd>{APP_VERSION}</dd>
+  <dt>Auth:</dt> <dd>{auth_state}</dd>
+</dl>
+<h2>Endpoints</h2>
+<ul>
+  <li><a href="/docs">/docs</a> - interactive API docs (Swagger)</li>
+  <li><a href="/api/v1/system/ping">/api/v1/system/ping</a> - public liveness</li>
+  <li><a href="/api/v1/system/version">/api/v1/system/version</a> - public version</li>
+  <li>/api/v1/system/{{node, services, health, reclaim}} - auth required</li>
+  <li>/api/v1/service/{{name}}/{{start, stop, restart, health, status, logs, manifest}} - auth required</li>
+</ul>
+<p>Source of truth: ~/.seren/services/*.json + ~/.seren/node.json</p>
+</body></html>"""
+
+    # The Observatory glance - on the shared SerenMeninges baseplate.
+    @app.get("/viewer", response_class=HTMLResponse)
+    async def viewer() -> str:
+        # Node vitals, thermals, health rollup, and the service roster with
+        # lifecycle controls. PUBLIC route (the HTML shell needs no auth - see
+        # auth.PUBLIC_PATHS); its /api/v1/* fetches carry the token from the
+        # shell's key modal. With no token provisioned the read-only glance
+        # still works (safe GETs stay open); the action buttons fail closed
+        # (503) until ~/.seren/secrets.json exists - the deliberate interlock,
+        # surfaced in the UI instead of hidden.
+        return render_from_dir(
+            Path(__file__).resolve().parent / "viewer" / "ui",
+            title="seren-observatory",
+            brand="Seren<b>Observatory</b>",
+            subtitle=f"v{APP_VERSION} · per-node watch plane",
+            accent="#6eff70",
+        )
+
+    # System routes (ping, version, node, services, health, reclaim)
+    app.include_router(system_router)
+
+    # Per-service routes - one router per installed service
+    mounted = register_all_services(app)
+    print(f"[seren-observatory] mounted services: {mounted}")
+
+    return app
+
+
+# Module-level app for `uvicorn seren_observatory.app:app`
+app = create_app()
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    # Direct `python -m seren_observatory.app` path. Resolve config the same way the
+    # console script does so host/port behave identically. (`python -m
+    # seren_observatory` -> __main__.py is the preferred, --config-aware entry.)
+    _cfg = load_config()
+    uvicorn.run(app, host=_cfg.host, port=_cfg.port, log_level="info")
+
+
+def main() -> None:
+    """Console-script entry point: `seren-observatory` (declared in pyproject.toml).
+
+    Resolves config (defaults < yaml < env) and runs uvicorn. The CLI --config
+    flag is handled by __main__.py (`python -m seren_observatory`); the bare
+    console-script reads $SEREN_AGENT_CONFIG / the conventional path / defaults.
+    """
+    import uvicorn
+
+    cfg = load_config()
+    uvicorn.run(
+        "seren_observatory.app:app",
+        host=cfg.host,
+        port=cfg.port,
+        log_level="info",
+        reload=False,
+    )