Initial Local Nexus Controller system

- Add FastAPI dashboard + API for service/database/key registries
- Add SQLite registry storage, port management, and process control
- Add import bundle workflow for auto-populating new programs

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nedpearson

.env.example

@@ -0,0 +1,19 @@
+# Local Nexus Controller configuration (DO NOT put real secrets in git)
+#
+# SQLite database file path (relative to project root is OK)
+LOCAL_NEXUS_DB_PATH=data/local_nexus.db
+
+# Web server bind
+LOCAL_NEXUS_HOST=127.0.0.1
+LOCAL_NEXUS_PORT=5010
+
+# Optional: protect write actions with a token.
+# If set, clients must send header: X-Local-Nexus-Token: <token>
+LOCAL_NEXUS_TOKEN=
+
+# Port assignment defaults
+LOCAL_NEXUS_PORT_RANGE_START=3000
+LOCAL_NEXUS_PORT_RANGE_END=3999
+
+# Logs
+LOCAL_NEXUS_LOG_DIR=data/logs

.gitignore

@@ -0,0 +1,20 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+
+# Local registry + logs
+data/*.db
+data/*.sqlite
+data/logs/*.log
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.vscode/
+
+# Python build artifacts
+dist/
+build/
+*.egg-info/
+

README.md

@@ -0,0 +1,60 @@
+# Local Nexus Controller
+
+Local Nexus Controller is a **Windows-friendly local dashboard + API** to **register, document, monitor, and control** all locally-hosted programs/services you build.
+
+It provides:
+- **Service registry** (SQLite)
+- **Database registry** (SQLite)
+- **Port management** (assignment + conflict detection)
+- **Secrets/keys references** (env-var references only; never store real secrets)
+- **Process control** (start/stop/restart; logs captured to `data/logs/`)
+- **Web dashboard** with drill-downs and an **Import Bundle** feature for auto-populating new programs
+
+## Quick start (PowerShell)
+
+From `C:\Users\nedpe\LocalNexusController`:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+copy .env.example .env
+python -m local_nexus_controller
+```
+
+Then open:
+- Dashboard: `http://127.0.0.1:5010`
+- API docs (Swagger): `http://127.0.0.1:5010/docs`
+
+## Import sample registry (4 services + 2 databases)
+
+```powershell
+python .\tools\import_bundle.py .\sample_data\import_bundle.json
+```
+
+Or use the dashboard:
+- Go to **Import** and paste the JSON bundle.
+
+## Import your existing local programs (auto-generated)
+
+This repo includes a bundle based on what was found on your machine:
+
+```powershell
+python .\tools\import_bundle.py .\sample_data\import_existing_bundle.json
+```
+
+Or use the dashboard:
+- Go to **Import** and paste `sample_data/import_existing_bundle.json`.
+
+## Auto-populating new programs you ask me to generate
+
+When you ask for a new program, you (and I) will produce an **Import Bundle JSON** that you can paste into:
+- Dashboard → **Import**, or
+- `POST /api/import/bundle`
+
+This ensures every new local program is automatically registered, categorized, assigned a port, and optionally assigned a database.
+
+## Notes
+
+- The controller stores **only references** to secrets (e.g., `OPENAI_API_KEY`) and where they are used. It never stores secret values.
+- Process control uses stored `start_command`/`stop_command` or the controller can terminate the tracked PID tree.

local_nexus_controller/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

local_nexus_controller/__main__.py

@@ -0,0 +1,16 @@
+import uvicorn
+
+from local_nexus_controller.settings import settings
+
+
+def main() -> None:
+    uvicorn.run(
+        "local_nexus_controller.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.reload,
+    )
+
+
+if __name__ == "__main__":
+    main()

local_nexus_controller/db.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Generator
+
+from sqlalchemy import text
+from sqlmodel import Session, SQLModel, create_engine
+
+from local_nexus_controller.settings import settings
+
+
+def _ensure_parent_dir(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+_ensure_parent_dir(settings.db_path)
+engine = create_engine(
+    f"sqlite:///{settings.db_path.as_posix()}",
+    connect_args={"check_same_thread": False},
+)
+
+
+def init_db() -> None:
+    SQLModel.metadata.create_all(engine)
+    _sqlite_migrate()
+
+
+def _sqlite_migrate() -> None:
+    """
+    Lightweight, additive migrations for local SQLite.
+    We only ADD columns; never drop/rename.
+    """
+
+    with engine.begin() as conn:
+        # Service.env_overrides (added in v0.2)
+        cols = [row[1] for row in conn.execute(text("PRAGMA table_info(service)")).fetchall()]
+        if cols and "env_overrides" not in cols:
+            conn.execute(text("ALTER TABLE service ADD COLUMN env_overrides TEXT"))
+
+
+def get_session() -> Generator[Session, None, None]:
+    with Session(engine) as session:
+        yield session

local_nexus_controller/main.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+from local_nexus_controller.db import init_db
+from local_nexus_controller.routers.api_databases import router as api_databases_router
+from local_nexus_controller.routers.api_import import router as api_import_router
+from local_nexus_controller.routers.api_keys import router as api_keys_router
+from local_nexus_controller.routers.api_ports import router as api_ports_router
+from local_nexus_controller.routers.api_services import router as api_services_router
+from local_nexus_controller.routers.api_summary import router as api_summary_router
+from local_nexus_controller.routers.ui import router as ui_router
+
+
+app = FastAPI(title="Local Nexus Controller", version="0.1.0")
+
+static_dir = Path(__file__).resolve().parent / "static"
+app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+app.include_router(ui_router)
+app.include_router(api_services_router, prefix="/api/services", tags=["services"])
+app.include_router(api_databases_router, prefix="/api/databases", tags=["databases"])
+app.include_router(api_ports_router, prefix="/api/ports", tags=["ports"])
+app.include_router(api_keys_router, prefix="/api/keys", tags=["keys"])
+app.include_router(api_import_router, prefix="/api/import", tags=["import"])
+app.include_router(api_summary_router, prefix="/api/summary", tags=["summary"])
+
+
+@app.on_event("startup")
+def _startup() -> None:
+    init_db()

local_nexus_controller/models.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from sqlalchemy import Column
+from sqlalchemy.types import JSON
+from sqlmodel import Field, Relationship, SQLModel
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _uuid_str() -> str:
+    return str(uuid.uuid4())
+
+
+class Service(SQLModel, table=True):
+    id: str = Field(default_factory=_uuid_str, primary_key=True, index=True)
+
+    name: str = Field(index=True)
+    description: str = Field(default="")
+    category: str = Field(default="general", index=True)
+
+    tags: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    tech_stack: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    dependencies: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    config_paths: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+
+    port: Optional[int] = Field(default=None, index=True)
+    local_url: Optional[str] = Field(default=None)
+    healthcheck_url: Optional[str] = Field(default=None)
+
+    working_directory: Optional[str] = Field(default=None)
+    start_command: str = Field(default="")
+    stop_command: str = Field(default="")
+    restart_command: str = Field(default="")
+
+    # Environment overrides passed at runtime (safe values only; never secrets here).
+    # Supports placeholders {PORT} and {HOST}.
+    env_overrides: dict[str, str] = Field(default_factory=dict, sa_column=Column(JSON))
+
+    # Runtime tracking
+    status: str = Field(default="stopped", index=True)  # running|stopped|error|unknown
+    process_pid: Optional[int] = Field(default=None, index=True)
+    process_started_at: Optional[datetime] = Field(default=None)
+    last_error: Optional[str] = Field(default=None)
+    log_path: Optional[str] = Field(default=None)
+
+    # Database linkage
+    database_id: Optional[str] = Field(default=None, foreign_key="database.id", index=True)
+    database_connection_string: Optional[str] = Field(default=None)
+    database_schema_overview: Optional[str] = Field(default=None)
+
+    created_at: datetime = Field(default_factory=_now_utc)
+    updated_at: datetime = Field(default_factory=_now_utc)
+
+    database: Optional["Database"] = Relationship(back_populates="services")
+    keys: list["KeyRef"] = Relationship(back_populates="service")
+
+
+class Database(SQLModel, table=True):
+    id: str = Field(default_factory=_uuid_str, primary_key=True, index=True)
+
+    database_name: str = Field(index=True, unique=True)
+    type: str = Field(default="sqlite", index=True)  # sqlite|postgres|mysql|mongo|...
+
+    host: Optional[str] = Field(default="localhost")
+    port: Optional[int] = Field(default=None)
+
+    username_env: Optional[str] = Field(default=None)
+    password_env: Optional[str] = Field(default=None)
+
+    connection_string: Optional[str] = Field(default=None)
+    schema_overview: Optional[str] = Field(default=None)
+
+    created_at: datetime = Field(default_factory=_now_utc)
+    updated_at: datetime = Field(default_factory=_now_utc)
+
+    services: list[Service] = Relationship(back_populates="database")
+
+
+class KeyRef(SQLModel, table=True):
+    id: str = Field(default_factory=_uuid_str, primary_key=True, index=True)
+
+    service_id: str = Field(foreign_key="service.id", index=True)
+    key_name: str = Field(index=True)
+    env_var: str = Field(index=True)
+    description: str = Field(default="")
+
+    created_at: datetime = Field(default_factory=_now_utc)
+
+    service: Service = Relationship(back_populates="keys")
+
+
+# -----------------------
+# API schemas (non-table)
+# -----------------------
+
+class ServiceCreate(SQLModel):
+    name: str
+    description: str = ""
+    category: str = "general"
+    tags: list[str] = Field(default_factory=list)
+    tech_stack: list[str] = Field(default_factory=list)
+    dependencies: list[str] = Field(default_factory=list)
+    config_paths: list[str] = Field(default_factory=list)
+    port: Optional[int] = None
+    local_url: Optional[str] = None
+    healthcheck_url: Optional[str] = None
+    working_directory: Optional[str] = None
+    start_command: str = ""
+    stop_command: str = ""
+    restart_command: str = ""
+    env_overrides: dict[str, str] = Field(default_factory=dict)
+    database_id: Optional[str] = None
+    database_connection_string: Optional[str] = None
+    database_schema_overview: Optional[str] = None
+
+
+class ServiceUpdate(SQLModel):
+    name: Optional[str] = None
+    description: Optional[str] = None
+    category: Optional[str] = None
+    tags: Optional[list[str]] = None
+    tech_stack: Optional[list[str]] = None
+    dependencies: Optional[list[str]] = None
+    config_paths: Optional[list[str]] = None
+    port: Optional[int] = None
+    local_url: Optional[str] = None
+    healthcheck_url: Optional[str] = None
+    working_directory: Optional[str] = None
+    start_command: Optional[str] = None
+    stop_command: Optional[str] = None
+    restart_command: Optional[str] = None
+    env_overrides: Optional[dict[str, str]] = None
+    database_id: Optional[str] = None
+    database_connection_string: Optional[str] = None
+    database_schema_overview: Optional[str] = None
+    status: Optional[str] = None
+    process_pid: Optional[int] = None
+    last_error: Optional[str] = None
+    log_path: Optional[str] = None
+
+
+class DatabaseCreate(SQLModel):
+    database_name: str
+    type: str = "sqlite"
+    host: Optional[str] = "localhost"
+    port: Optional[int] = None
+    username_env: Optional[str] = None
+    password_env: Optional[str] = None
+    connection_string: Optional[str] = None
+    schema_overview: Optional[str] = None
+
+
+class DatabaseUpdate(SQLModel):
+    database_name: Optional[str] = None
+    type: Optional[str] = None
+    host: Optional[str] = None
+    port: Optional[int] = None
+    username_env: Optional[str] = None
+    password_env: Optional[str] = None
+    connection_string: Optional[str] = None
+    schema_overview: Optional[str] = None
+
+
+class KeyRefCreate(SQLModel):
+    key_name: str
+    env_var: str
+    description: str = ""
+
+
+class ImportBundle(SQLModel):
+    """
+    This is the JSON shape used for auto-populating new programs.
+    Paste this into the dashboard Import page or POST it to /api/import/bundle.
+    """
+
+    service: ServiceCreate
+    database: Optional[DatabaseCreate] = None
+    keys: list[KeyRefCreate] = Field(default_factory=list)
+    requested_port: Optional[int] = None
+    auto_assign_port: bool = True
+    auto_create_db: bool = True
+    meta: dict[str, Any] = Field(default_factory=dict)

local_nexus_controller/routers/__init__.py

@@ -0,0 +1 @@
+# FastAPI routers live here.