Self-Hosted Hub

Module: sc_neurocore.hub Primary API: write_hub_bundle(...) CLI: sc-neurocore hub-init

The self-hosted hub generator writes an offline-first Docker Compose bundle for local SC-NeuroCore Studio and opt-in benchmark execution. It is a bundle generator, not a hosted service and not a remote registry.

Generated Artefacts

Python

from sc_neurocore.hub import HubBundleConfig, write_hub_bundle

paths = write_hub_bundle(
    "build/hub",
    HubBundleConfig(
        bind_host="127.0.0.1",
        studio_port=8001,
        image="sc-neurocore-hub:local",
        offline=True,
    ),
)

The output directory contains:

Path	Purpose
docker-compose.yml	Studio and benchmark-runner services
.env.example	Offline/cache/model environment defaults
hub_manifest.json	Deterministic service, storage, network, and hardening contract
model_zoo_index.json	Built-in plugin, network-config, and pretrained-weight index
benchmark_plan.json	Opt-in benchmark-runner contract
README.md	Local operator instructions
cache/	Writable local cache mount
models/	Read-only user model mount
benchmarks/results/	Writable benchmark output mount

Security And Operations Contract

The generated Studio service defaults to 127.0.0.1, so it is not exposed outside the host unless the operator explicitly changes --bind-host. Offline mode sets SC_NEUROCORE_HUB_OFFLINE=1, HF_HUB_OFFLINE=1, and TRANSFORMERS_OFFLINE=1; --online clears those generated flags.

Compose hardening in the generated bundle:

Control	Setting
Runtime user	Non-root, inherited from deploy/Dockerfile
Root filesystem	read_only: true
Writable mounts	Cache, model/result directories as needed, plus /tmp tmpfs
Privilege escalation	no-new-privileges:true
Image pulling	pull_policy: never
Readiness	Studio /api/health healthcheck
Benchmarks	Opt-in benchmark profile

CLI

Bash

sc-neurocore hub-init --output build/hub --port 8001
docker compose -f build/hub/docker-compose.yml up studio

Optional flags:

Flag	Default	Meaning
--bind-host	127.0.0.1	Host address used for Studio port publishing
--port	8001	Studio service port
--hub-image	sc-neurocore-hub:local	Generated Compose image tag
--online	unset	Generate online-mode environment flags

Boundaries

The hub bundle does not build or publish container images by itself, does not submit hardware or cloud jobs, and does not claim benchmark results until the operator runs the opt-in benchmark profile. Real availability still depends on the container build and the package being installed with the Studio runtime dependencies.

API

sc_neurocore.hub

Self-hosted hub bundle generation.

HubBundleConfig dataclass

Configuration for a local self-hosted hub bundle.

Source code in src/sc_neurocore/hub/bundle.py

@dataclass(frozen=True)
class HubBundleConfig:
    """Configuration for a local self-hosted hub bundle."""

    bind_host: str = "127.0.0.1"
    studio_port: int = 8001
    image: str = "sc-neurocore-hub:local"
    offline: bool = True
    cache_dir: str = "cache"
    models_dir: str = "models"
    benchmarks_dir: str = "benchmarks"
    compose_name: str = "docker-compose.yml"

    def __post_init__(self) -> None:
        if not self.bind_host:
            raise ValueError("bind_host must not be empty")
        _validate_bind_host(self.bind_host)
        if not 1 <= self.studio_port <= 65535:
            raise ValueError("studio_port must be in the range 1..65535")
        if not self.image:
            raise ValueError("image must not be empty")
        for label, value in (
            ("cache_dir", self.cache_dir),
            ("models_dir", self.models_dir),
            ("benchmarks_dir", self.benchmarks_dir),
            ("compose_name", self.compose_name),
        ):
            _validate_relative_path(label, value)
        if PurePosixPath(self.compose_name).name != self.compose_name:
            raise ValueError("compose_name must be a file name, not a nested path")

build_benchmark_plan(config=None)

Build the benchmark-runner plan included in the hub bundle.

Source code in src/sc_neurocore/hub/bundle.py

def build_benchmark_plan(config: HubBundleConfig | None = None) -> dict[str, Any]:
    """Build the benchmark-runner plan included in the hub bundle."""

    cfg = config or HubBundleConfig()
    return {
        "schema_version": "sc-neurocore.hub-benchmark-plan.v1",
        "offline": cfg.offline,
        "runner": {
            "service": "benchmark-runner",
            "profile": "benchmark",
            "command": "python benchmarks/benchmark_suite.py --markdown",
            "results_dir": "/workspace/benchmarks/results",
        },
        "mounted_paths": {
            "benchmarks": f"./{cfg.benchmarks_dir}",
            "cache": f"./{cfg.cache_dir}",
        },
        "limitations": [
            "benchmark output depends on the host CPU and container runtime",
            "the benchmark profile is opt-in and is not started with the Studio service",
        ],
    }

build_hub_manifest(config=None)

Build a deterministic manifest for a self-hosted hub bundle.

Source code in src/sc_neurocore/hub/bundle.py

def build_hub_manifest(config: HubBundleConfig | None = None) -> dict[str, Any]:
    """Build a deterministic manifest for a self-hosted hub bundle."""

    cfg = config or HubBundleConfig()
    return {
        "schema_version": SCHEMA_VERSION,
        "offline_default": cfg.offline,
        "services": {
            "studio": {
                "kind": "fastapi_studio",
                "url": f"http://{cfg.bind_host}:{cfg.studio_port}",
                "compose_service": "studio",
                "command": _studio_container_command(cfg),
                "healthcheck": f"http://127.0.0.1:{cfg.studio_port}/api/health",
                "writable_paths": [
                    "/var/lib/sc-neurocore/cache",
                    # Declared container tmpfs path, not a host tempfile.
                    "/tmp",  # nosec B108
                ],
            },
            "benchmark_runner": {
                "kind": "opt_in_benchmark_runner",
                "compose_service": "benchmark-runner",
                "profile": "benchmark",
                "command": "python benchmarks/benchmark_suite.py --markdown",
                "writable_paths": [
                    "/workspace/benchmarks/results",
                    "/var/lib/sc-neurocore/cache",
                    # Declared container tmpfs path, not a host tempfile.
                    "/tmp",  # nosec B108
                ],
            },
        },
        "service_contracts": {
            "studio": {
                "readiness_endpoint": "/api/health",
                "serves": [
                    "visual SNN design studio API",
                    "local model catalogue",
                    "local simulation and code-generation endpoints",
                ],
                "does_not_provide": [
                    "remote model hosting",
                    "automatic container-image publishing",
                    "hardware or cloud job submission",
                ],
            },
            "benchmark_runner": {
                "activation": "docker compose --profile benchmark run --rm benchmark-runner",
                "serves": ["local benchmark-suite execution"],
                "does_not_provide": ["continuous benchmark daemon"],
            },
        },
        "storage": {
            "cache": cfg.cache_dir,
            "models": cfg.models_dir,
            "benchmark_results": f"{cfg.benchmarks_dir}/results",
        },
        "artefacts": {
            "compose": cfg.compose_name,
            "env_example": ".env.example",
            "model_zoo_index": "model_zoo_index.json",
            "benchmark_plan": "benchmark_plan.json",
            "manifest": "hub_manifest.json",
        },
        "model_zoo": build_model_zoo_index(),
        "benchmark_plan": build_benchmark_plan(cfg),
        "network_policy": {
            "bind_host": cfg.bind_host,
            "ingress_scope": _ingress_scope(cfg.bind_host),
            "external_egress_required": False,
            "offline_environment": _offline_environment(cfg),
        },
        "container_hardening": {
            "non_root_runtime_user": True,
            "read_only_root_filesystem": True,
            "no_new_privileges": True,
            "tmpfs_paths": [
                # Explicit Docker tmpfs mount inside the container.
                "/tmp",  # nosec B108
            ],
            "restart_policy": "unless-stopped",
        },
        "limitations": [
            "bundle generation does not build or publish a container image",
            "Studio availability depends on installing the package with the studio extra",
            "benchmark results are generated only when the benchmark profile is run",
        ],
    }

build_model_zoo_index()

Build a deterministic model-zoo index for hub manifests.

Source code in src/sc_neurocore/hub/bundle.py

def build_model_zoo_index() -> dict[str, Any]:
    """Build a deterministic model-zoo index for hub manifests."""

    registry = PluginRegistry.with_builtins()
    plugin_entries = []
    for name in registry.list_plugins():
        plugin = registry.get(name)
        if plugin is None:
            continue
        meta = plugin.meta()
        plugin_entries.append(
            {
                "name": meta.name,
                "version": meta.version,
                "description": meta.description,
                "state_variables": list(meta.state_variables),
                "parameters": dict(sorted(meta.parameters.items())),
            }
        )

    network_entries = [
        {
            "name": builder.__name__,
            "kind": "network_config",
            "import_path": f"{builder.__module__}.{builder.__name__}",
        }
        for builder in _NETWORK_BUILDERS
    ]

    pretrained_entries = [
        {
            "name": name,
            "kind": "pretrained_weights",
            "weight_file": weight_file,
        }
        for name, (_, weight_file) in sorted(_PRETRAINED_REGISTRY.items())
    ]

    return {
        "schema_version": "sc-neurocore.model-zoo-index.v1",
        "plugins": plugin_entries,
        "network_configs": network_entries,
        "pretrained": pretrained_entries,
    }

write_hub_bundle(output_dir, config=None)

Write a local Docker Compose hub bundle and return generated paths.

Source code in src/sc_neurocore/hub/bundle.py

def write_hub_bundle(
    output_dir: str | Path, config: HubBundleConfig | None = None
) -> dict[str, Path]:
    """Write a local Docker Compose hub bundle and return generated paths."""

    cfg = config or HubBundleConfig()
    root = Path(output_dir)
    root.mkdir(parents=True, exist_ok=True)
    for rel in (
        cfg.cache_dir,
        cfg.models_dir,
        cfg.benchmarks_dir,
        f"{cfg.benchmarks_dir}/results",
    ):
        (root / rel).mkdir(parents=True, exist_ok=True)

    paths = {
        "compose": root / cfg.compose_name,
        "env_example": root / ".env.example",
        "manifest": root / "hub_manifest.json",
        "model_zoo_index": root / "model_zoo_index.json",
        "benchmark_plan": root / "benchmark_plan.json",
        "readme": root / "README.md",
    }
    manifest = build_hub_manifest(cfg)
    paths["compose"].write_text(_compose_yaml(cfg, _relative_repo_context(root)), encoding="utf-8")
    paths["env_example"].write_text(_env_example(cfg), encoding="utf-8")
    paths["manifest"].write_text(_json(manifest), encoding="utf-8")
    paths["model_zoo_index"].write_text(_json(manifest["model_zoo"]), encoding="utf-8")
    paths["benchmark_plan"].write_text(_json(manifest["benchmark_plan"]), encoding="utf-8")
    paths["readme"].write_text(_readme(cfg), encoding="utf-8")
    return paths