# Backplane

**A governed extension runtime for open-weight language models.**

Backplane turns a frozen model into a programmable system. Teams mount small,
versioned cards for tenant policy, memory, exact tools, adapters, sensors, and
activation interventions without treating the base model as mutable application
state.

The commercial product is **Backplane Runtime**. The public site and control-plane
sandbox live at [backplane.cyberelf.link](https://backplane.cyberelf.link/).

## What ships in this repository

- A tenant-isolated runtime with API-key hashing, SQLite namespaces, card-stack
  routing, bounded requests, rate limits, and scoped receipts.
- A compatibility-aware microbatch scheduler.
- A Hugging Face backend using normal KV-cached generation, optional 4-bit
  loading, bounded automatically removed activation hooks, and hash-bound
  per-request PEFT adapters.
- A vLLM/OpenAI-compatible backend for governed prompt/output processing and
  per-request LoRA routing. Arbitrary activation cards are explicitly rejected
  until a worker plugin exists.
- Reproducible `.bpcard` archives signed with Ed25519.
- A declarative card boundary that rejects executable archive members.
- An OpenAI-compatible API, management boundary, CLI, benchmark harness, and
  three-tenant pilot.
- A public interactive control-plane sandbox. Its backend is deterministic and
  clearly labeled; it does not pretend the VPS is running a GPU model.

## Quick start

```powershell
python -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[test]"
.\.venv\Scripts\python -m backplane_runtime.cli smoke
.\.venv\Scripts\python -m backplane_runtime.cli benchmark
.\.venv\Scripts\python -m backplane_runtime.cli serve --port 8994
```

Then open `http://127.0.0.1:8994/api/docs`.

Run the local-model backend:

```python
from backplane_runtime.backends import TransformersBackend
from backplane_runtime.runtime import BackplaneRuntime

runtime = BackplaneRuntime(
    "./work/state.sqlite3",
    backend=TransformersBackend("Qwen/Qwen3-1.7B"),
)
```

Register local adapter artifacts with the operator-owned backend registry. The
signed card contains the artifact hash and activation policy, never a filesystem
path:

```python
backend = TransformersBackend(
    "./models/base",
    local_files_only=True,
    quantization="4bit",
    dtype="bfloat16",
    adapter_registry={"capability.route": "./private/adapters/capability-route"},
    model_label="qwen-family-local-v1",
    system_prompt="The application-owned system contract.",
)
```

```json
{
  "activation_mode": "typed-envelope",
  "metadata_key": "adapter_envelope",
  "operator_type": "GLOBAL_ANCHOR",
  "term": "declared-term",
  "artifact_sha256": "<sha256 of adapter_config.json + adapter weights>",
  "system_prompt_sha256": "<sha256 of the application system contract>"
}
```

The caller supplies an exact five-field JSON envelope containing schema version,
operator type, term, boolean `apply`, and the request prompt. The card checks
duplicate keys, types, size, declared operator, and exact prompt equality. User
prompt text has no routing authority. The effective activation spec is included
in the execution stack digest, preventing active and inactive requests from
sharing a batch identity. Public card IDs are deterministically mapped to
PyTorch-safe internal adapter names; signed manifests and receipts retain the
original card identity.

Point the control plane at vLLM:

```python
from backplane_runtime.backends import VLLMBackend

backend = VLLMBackend(
    "http://127.0.0.1:8000",
    model="Qwen/Qwen3-8B",
)
```

The configured base model is fixed unless an active signed adapter card names a
governed `served_model`; caller metadata cannot substitute a model.

## Card package boundary

A card package contains exactly four files:

```text
manifest.json
config.json
checksums.json
signature.json
```

The runtime rejects additional files, unsafe archive paths, checksum changes,
unknown signers under a trust policy, and non-Ed25519 signatures. Packages are
declarative: they select audited implementations rather than importing arbitrary
Python from an archive.

```powershell
backplane keygen --private publisher.pem --public publisher.pub.pem
backplane pack --manifest examples\cards\policy.manifest.json `
  --config examples\cards\policy.config.json `
  --private publisher.pem --output policy.bpcard
backplane verify policy.bpcard
```

## Product boundary

Backplane does **not** claim that hooks, LoRA, activation patching, memory, or
guardrails are individually new. Its product claim is the governed composition
layer:

- one frozen host;
- explicit card manifests;
- per-tenant card stacks and state;
- compatibility-aware batching;
- enforced request and mutation budgets;
- signed packages;
- telemetry and content-addressed receipts;
- reversible activation hooks;
- honest backend capability negotiation.

See [STATUS.md](STATUS.md) for the seven production milestones and their current
state. Historical research receipts are preserved in
[evidence/research_receipts.json](evidence/research_receipts.json) with their
limitations.

## Repository map

```text
src/backplane_runtime/   runtime, packages, API, backends, benchmark
tests_py/                runtime and security acceptance tests
examples/                declarative cards and pilot configuration
evidence/                bounded receipts from the research prototype
docs/                    architecture, security, deployment, and pilot guides
app/                     product website and interactive public sandbox
deploy/                  systemd and Nginx production templates
```

## Validation

```powershell
$env:PYTHONPATH = "src"
python -m compileall -q src
pytest -q tests_py
python -m backplane_runtime.cli smoke
python -m backplane_runtime.cli benchmark
npm.cmd run build
```

## License

AGPL-3.0-or-later for the public core, with commercial licensing available from
Cyberelf Labs. Contact [justin@cyberelf.link](mailto:justin@cyberelf.link).


## Scheduler lifecycle

The scheduler bounds its waiting queue (256 requests by default), rejects new
submissions once shutdown begins, skips cancelled work before backend dispatch,
and resolves waiting callers if its worker is cancelled or fails. Cancelling a
caller waiting for `close()` does not cancel shutdown itself. Compatible batches
retain their stack identities. Receipt `queue_ms` measures time until backend
execution starts; it no longer includes that request's own generation time.
Backend execution already in progress must still implement its own timeout or
cancellation contract. The public sandbox uses the declared deterministic backend.
