Deploy from 4dfd54f2

.env.example

@@ -0,0 +1,73 @@
+# Matrix Runtime — example environment configuration
+#
+# Copy to .env and adjust. Every variable below is actually read by the binary
+# (see internal/config, internal/auth, internal/email). NEVER commit real
+# secrets — keep your filled-in .env out of version control.
+
+# ---- Core --------------------------------------------------------------------
+# Mode: local-dev | customer-agent | cloud-worker | hf-space
+MATRIX_RUNTIME_MODE=customer-agent
+# HTTP port. $PORT (PaaS convention) is also honored; if busy, the next free
+# port is used automatically.
+MATRIX_RUNTIME_PORT=8080
+# Writable data directory (SQLite db, model cache, sandboxes, secret key).
+MATRIX_RUNTIME_DATA_DIR=/var/lib/matrix-runtime
+# Externally reachable base URL (used in links/emails). Optional.
+MATRIX_RUNTIME_PUBLIC_URL=
+
+# ---- API authentication ------------------------------------------------------
+# Operator bearer token. REQUIRED in production modes — without it the API is
+# unauthenticated for non-session callers (the readiness probe warns, and
+# protected endpoints fail closed). Generate: openssl rand -hex 32
+MATRIX_RUNTIME_API_TOKEN=
+
+# ---- Database ----------------------------------------------------------------
+# Default: a local SQLite file under the data dir. For multi-user / HA, set a
+# PostgreSQL (e.g. Neon) URL — MatrixCloud isolates all objects in its own
+# schema so the instance can be shared safely.
+#   MATRIXCLOUD_DATABASE_URL / MATRIX_RUNTIME_DB_URL / DATABASE_URL (first wins)
+MATRIXCLOUD_DATABASE_URL=
+MATRIXCLOUD_DB_SCHEMA=matrixcloud
+# Override the SQLite path (when no Postgres URL is set).
+MATRIX_RUNTIME_DB_PATH=
+
+# ---- Secrets at rest ---------------------------------------------------------
+# 32-byte key (hex or base64) used to encrypt BYO provider credentials
+# (AES-256-GCM). If unset, a key is generated once into <data-dir>/secret.key.
+# Set this explicitly in production so secrets survive a fresh data dir.
+MATRIXCLOUD_SECRET_KEY=
+
+# ---- Transactional email (Resend) -------------------------------------------
+# Used for welcome/verification and password-reset emails. Without a key the
+# sender runs in log-only mode (no email sent), which is fine for local dev.
+RESEND_API_KEY=
+MATRIXCLOUD_EMAIL_FROM=MatrixCloud <noreply@matrixhub.io>
+# Public console URL used to build email links (reset/verify).
+MATRIXCLOUD_APP_URL=https://cloud.matrixhub.io
+
+# ---- Limits & retention ------------------------------------------------------
+MATRIX_RUNTIME_MAX_TTL_SECONDS=600
+MATRIX_RUNTIME_MAX_CONCURRENT_JOBS=5
+# Requests/min per client IP on write+auth endpoints (0 disables).
+MATRIX_RUNTIME_RATE_LIMIT_RPM=120
+# Background retention (purge terminal jobs/scratch + prune old logs).
+MATRIX_RUNTIME_JOB_RETENTION_HOURS=24
+MATRIX_RUNTIME_LOG_RETENTION_HOURS=72
+MATRIX_RUNTIME_CLEANUP_INTERVAL_MINUTES=15
+
+# ---- MatrixShell -------------------------------------------------------------
+# Executes commands in a local Python sandbox. OFF by default in production
+# modes; ON by default only in local-dev. Set true/false to override.
+MATRIX_SHELL_ENABLED=false
+
+# ---- Control plane (hybrid join) --------------------------------------------
+MATRIX_CLOUD_URL=https://cloud.matrixhub.io
+MATRIX_RUNTIME_JOIN_TOKEN=
+# Optional identity overrides.
+MATRIX_RUNTIME_ID=
+MATRIX_RUNTIME_WORKSPACE=
+
+# ---- Hugging Face ------------------------------------------------------------
+# Optional operator HF token (users can also bring their own per-workspace).
+HF_TOKEN=
+MATRIX_RUNTIME_HF_CACHE_DIR=

.gitattributes

@@ -0,0 +1,34 @@
+# Keep source and text files LF on every platform (Windows/WSL included).
+# This prevents CRLF checkouts that break `gofmt` and `make fmt-check`.
+
+* text=auto eol=lf
+
+*.go        text eol=lf
+*.mod       text eol=lf
+*.sum       text eol=lf
+*.js        text eol=lf
+*.jsx       text eol=lf
+*.css       text eol=lf
+*.html      text eol=lf
+*.json      text eol=lf
+*.yaml      text eol=lf
+*.yml       text eol=lf
+*.md        text eol=lf
+*.sh        text eol=lf
+*.svg       text eol=lf
+Makefile    text eol=lf
+Dockerfile  text eol=lf
+*.tmpl      text eol=lf
+*.in        text eol=lf
+
+# Shell scripts must stay LF and keep their exec bit semantics.
+scripts/*.sh text eol=lf
+
+# Binary assets — never normalise.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary

.gitignore

@@ -0,0 +1,31 @@
+# Build output
+/bin/
+/dist/
+/.devdata/
+
+# Test / coverage artifacts
+coverage.out
+coverage.html
+
+# Local runtime data
+/var/lib/matrix-runtime/
+
+# Editor / OS
+*.swp
+.DS_Store
+
+# Local secrets / generated k8s secret
+deploy/k8s/secret.yaml
+deploy/docker-compose/.env
+
+# Python (clients/python) — keep uv.lock, ignore envs/caches/builds
+.venv/
+**/.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+clients/python/dist/
+clients/python/build/

Dockerfile

@@ -0,0 +1,33 @@
+# MatrixCloud — Hugging Face Docker Space
+#
+# Self-contained: builds matrix-runtime from the source shipped in this Space
+# repo (the deploy script / workflow push the full repo here). It does NOT clone
+# GitHub, so it always builds exactly the committed code — no branch/cache drift.
+# Serves the API + embedded console on port 7860 (HF's default app port); the
+# launcher app/main.py preps the environment and execs the binary.
+
+# ---- build ----
+FROM golang:1.24-bookworm AS build
+WORKDIR /src
+COPY . .
+RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/matrix-runtime ./cmd/matrix-runtime
+
+# ---- runtime ----
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ca-certificates curl git nodejs npm python3 python3-pip pipx \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=build /out/matrix-runtime /usr/local/bin/matrix-runtime
+COPY requirements.txt /app/requirements.txt
+RUN pip3 install --no-cache-dir --break-system-packages -r /app/requirements.txt
+COPY app /app/app
+
+# HF Spaces give you a writable /tmp; durable data should live in Postgres
+# (set MATRIXCLOUD_DATABASE_URL). Listening port matches app_port in README.md.
+ENV MATRIX_RUNTIME_MODE=cloud-worker \
+    MATRIX_RUNTIME_PORT=7860 \
+    MATRIX_RUNTIME_DATA_DIR=/tmp/matrixcloud \
+    MATRIX_SHELL_ENABLED=false \
+    HF_HOME=/tmp/hf
+EXPOSE 7860
+ENTRYPOINT ["python3", "/app/app/main.py"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Matrix Cloud / agent-matrix contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Makefile

@@ -0,0 +1,282 @@
+# Matrix Runtime — Makefile
+#
+# Common targets:
+#   make help       list every target
+#   make build      build a local binary into ./bin
+#   make test       full verification: fmt-check, vet, race tests + coverage
+#   make install    build + install the binary (auto-uses sudo when needed)
+#   make uninstall  remove an installed binary (and systemd unit if present)
+#
+# Install without root (user-local, no sudo):
+#   make install PREFIX=$HOME/.local
+# Production install with systemd + data dir + service user (needs root):
+#   sudo make install INSTALL_SYSTEMD=1
+
+SHELL := /usr/bin/env bash
+
+# ---- Module / binary -------------------------------------------------------
+MODULE  := github.com/agent-matrix/matrix-runtime
+BINARY  := matrix-runtime
+PKG     := ./cmd/matrix-runtime
+BIN_DIR := bin
+
+# ---- Install locations (GNU-style; honour DESTDIR/PREFIX) ------------------
+DESTDIR ?=
+PREFIX  ?= /usr/local
+BINDIR  ?= $(PREFIX)/bin
+
+# Production install knobs
+INSTALL_SYSTEMD ?= 0
+SERVICE_USER    ?= matrix
+DATA_DIR        ?= /var/lib/matrix-runtime
+SYSTEMD_DIR     ?= /etc/systemd/system
+ENV_FILE        ?= /etc/matrix-runtime/matrix-runtime.env
+
+# ---- Version stamping ------------------------------------------------------
+VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
+COMMIT  ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo none)
+DATE    ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
+
+LDFLAGS := -s -w \
+	-X $(MODULE)/internal/config.Version=$(VERSION) \
+	-X $(MODULE)/internal/config.Commit=$(COMMIT) \
+	-X $(MODULE)/internal/config.Date=$(DATE)
+
+# Static, reproducible production build.
+GOFLAGS_PROD := -trimpath
+CGO_ENABLED  ?= 0
+
+GO_FILES := $(shell find . -name '*.go' -not -path './legacy/*')
+
+.DEFAULT_GOAL := build
+# Run a shell script robustly even if a Windows/WSL checkout gave it CRLF line
+# endings: strip CR first, then run with bash (no exec-bit dependency).
+RUNSH = sh_strip_run() { sed -i 's/\r$$//' "$$1" 2>/dev/null || true; bash "$$1" "$${@:2}"; }; sh_strip_run
+
+.PHONY: all build prod-build run test fmt fmt-check vet lint tidy coverage \
+        docker compose-up compose-down smoke install uninstall \
+        install-systemd release clean help web web-auto normalize \
+        venv py-install py-test py-lint setup
+
+## all: build the frontend bundle and the backend binary
+all: web prod-build
+
+## normalize: strip CRLF -> LF from scripts, Makefile and Go (Windows/WSL fix)
+normalize:
+	@for f in $$(find . -path ./legacy -prune -o \( -name '*.sh' -o -name '*.go' \) -print) Makefile; do \
+		sed -i 's/\r$$//' "$$f" 2>/dev/null || true; \
+	done
+	@echo "normalize: line endings set to LF"
+
+## web: build the enterprise console bundle (web/src -> web/static/app.js)
+web:
+	@$(RUNSH) scripts/build-web.sh
+
+# web-auto: rebuild the console bundle when a JS toolchain is available, else
+# fall back to the committed web/static/app.js (already embedded in the binary).
+# Best-effort: never fails the build (works offline / air-gapped / CRLF checkout).
+web-auto:
+	@if command -v npx >/dev/null 2>&1; then \
+		$(RUNSH) scripts/build-web.sh || echo "web build failed — using committed web/static/app.js"; \
+	else \
+		echo "==> npx not found — using committed frontend (web/static/app.js, embedded)"; \
+	fi
+
+## build: compile a local binary into ./bin (backend API + embedded console)
+build:
+	@mkdir -p $(BIN_DIR)
+	go build -trimpath -ldflags "$(LDFLAGS)" -o $(BIN_DIR)/$(BINARY) $(PKG)
+	@echo "built $(BIN_DIR)/$(BINARY) ($(VERSION))"
+
+## prod-build: optimized, static, version-stamped binary
+prod-build:
+	@mkdir -p $(BIN_DIR)
+	CGO_ENABLED=$(CGO_ENABLED) go build $(GOFLAGS_PROD) -ldflags "$(LDFLAGS)" -o $(BIN_DIR)/$(BINARY) $(PKG)
+	@echo "built $(BIN_DIR)/$(BINARY) ($(VERSION), static)"
+
+## run: start the whole MatrixCloud (API + console + SQLite) in local-dev mode
+run: web-auto
+	@echo "==> MatrixCloud starting — the console URL is printed below"
+	@echo "    (if port 8080 is busy it falls back to the next free port; override with MATRIX_RUNTIME_PORT)"
+	go run -ldflags "$(LDFLAGS)" $(PKG) --mode local-dev
+
+## test: full verification gate (fmt, vet, race tests + coverage)
+test: fmt-check vet
+	go test -race -covermode=atomic -coverprofile=coverage.out ./...
+	@go tool cover -func=coverage.out | tail -1
+
+## fmt: normalise line endings (CRLF->LF) and gofmt all non-legacy Go files
+fmt:
+	@for f in $(GO_FILES); do sed -i 's/\r$$//' "$$f" 2>/dev/null || true; done
+	@gofmt -w $(GO_FILES)
+	@echo "gofmt: formatted $(words $(GO_FILES)) files (LF normalised)"
+
+## fmt-check: fail if any Go file has CRLF endings or is not gofmt-clean
+fmt-check:
+	@crlf="$$(grep -lUP '\r$$' $(GO_FILES) 2>/dev/null || true)"; \
+	if [ -n "$$crlf" ]; then \
+		echo "These files have CRLF (Windows) line endings — gofmt requires LF:"; \
+		echo "$$crlf" | sed 's/^/  /'; \
+		echo ""; \
+		echo "Fix:  make fmt"; \
+		echo "This repo ships .gitattributes to keep LF; if git re-introduces CRLF run:"; \
+		echo "      git add --renormalize . && git checkout ."; \
+		exit 1; \
+	fi; \
+	unformatted="$$(gofmt -l $(GO_FILES))"; \
+	if [ -n "$$unformatted" ]; then \
+		echo "These files are not gofmt-clean:"; echo "$$unformatted" | sed 's/^/  /'; \
+		echo "Run 'make fmt'."; exit 1; \
+	fi; \
+	echo "gofmt: clean"
+
+## vet: run go vet
+vet:
+	go vet ./...
+
+## lint: run golangci-lint if installed (optional)
+lint:
+	@if command -v golangci-lint >/dev/null 2>&1; then \
+		golangci-lint run ./...; \
+	else \
+		echo "golangci-lint not installed; skipping (using 'go vet' via 'make vet')"; \
+	fi
+
+## tidy: ensure go.mod is tidy
+tidy:
+	go mod tidy
+
+## coverage: open a coverage report
+coverage: test
+	go tool cover -html=coverage.out -o coverage.html
+	@echo "wrote coverage.html"
+
+# ---- Python client (clients/python) — uv-managed .venv ---------------------
+PY_DIR := clients/python
+
+## venv: create clients/python/.venv with uv (fast) and install the client
+venv:
+	@if command -v uv >/dev/null 2>&1; then \
+		cd $(PY_DIR) && uv sync --extra dev && \
+		echo "venv ready: $(PY_DIR)/.venv  (run: source $(PY_DIR)/.venv/bin/activate)"; \
+	else \
+		echo "uv not found — install it for fast setup: https://docs.astral.sh/uv/"; \
+		echo "falling back to python venv + pip…"; \
+		cd $(PY_DIR) && python3 -m venv .venv && ./.venv/bin/pip install -e '.[dev]'; \
+	fi
+
+## py-install: install the matrixcloud client + CLI into the .venv
+py-install: venv
+
+## py-test: run the Python client test suite
+py-test:
+	@cd $(PY_DIR) && if command -v uv >/dev/null 2>&1; then uv run pytest; else ./.venv/bin/pytest; fi
+
+## py-lint: lint the Python client (ruff)
+py-lint:
+	@cd $(PY_DIR) && if command -v uv >/dev/null 2>&1; then uv run ruff check .; else ./.venv/bin/ruff check .; fi
+
+## setup: build the runtime AND set up the Python client venv (full dev setup)
+setup: build venv
+	@echo "setup complete — run 'make run' to start MatrixCloud, or 'cd $(PY_DIR) && uv run mxc status'"
+
+## docker: build the container image
+docker:
+	docker build -t $(BINARY):$(VERSION) -t $(BINARY):local .
+
+## compose-up / compose-down: docker compose helpers
+compose-up:
+	docker compose -f deploy/docker-compose/docker-compose.yml up --build
+
+compose-down:
+	docker compose -f deploy/docker-compose/docker-compose.yml down
+
+## smoke: run the smoke test against a running instance
+smoke:
+	@$(RUNSH) scripts/smoke-test.sh
+
+## install: install the runtime (backend API + embedded MatrixCloud console).
+##          Auto-elevates with sudo when the target dir needs root. Use
+##          PREFIX=$HOME/.local for a user install with no root. Set
+##          INSTALL_SYSTEMD=1 (as root) to also install a systemd service.
+install: web-auto prod-build
+	@bindir="$(DESTDIR)$(BINDIR)"; sudo=""; \
+	if [ "$$(id -u)" = "0" ] || [ -w "$$(dirname "$$bindir")" ] || [ -w "$$bindir" ]; then \
+		: ; \
+	elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then \
+		sudo="sudo"; echo "==> $$bindir needs root — using passwordless sudo"; \
+	else \
+		bindir="$$HOME/.local/bin"; \
+		echo "==> $(BINDIR) needs root and passwordless sudo is unavailable —"; \
+		echo "    installing to $$bindir instead (override with PREFIX=... or run: sudo make install)"; \
+	fi; \
+	echo "==> installing $(BINARY) (backend + embedded console) to $$bindir"; \
+	$$sudo install -d "$$bindir" && \
+	$$sudo install -m 0755 "$(BIN_DIR)/$(BINARY)" "$$bindir/$(BINARY)" && \
+	echo "installed: $$bindir/$(BINARY)"; \
+	case ":$$PATH:" in *":$$bindir:"*) ;; *) echo "note: add $$bindir to your PATH — e.g.  echo 'export PATH=\"$$bindir:\$$PATH\"' >> ~/.bashrc";; esac; \
+	echo "run it:  $(BINARY) --mode local-dev   # then open http://localhost:8080"
+	@if [ "$(INSTALL_SYSTEMD)" = "1" ]; then $(MAKE) install-systemd; else \
+		echo "(systemd service available via: sudo make install INSTALL_SYSTEMD=1)"; fi
+
+## install-systemd: provision service user, data dir, env file and unit
+install-systemd:
+	@echo "==> provisioning systemd service"
+	@id -u "$(SERVICE_USER)" >/dev/null 2>&1 || useradd --system --no-create-home --shell /usr/sbin/nologin "$(SERVICE_USER)"
+	install -d -o "$(SERVICE_USER)" -g "$(SERVICE_USER)" "$(DESTDIR)$(DATA_DIR)"
+	install -d "$(DESTDIR)$(dir $(ENV_FILE))"
+	@if [ ! -f "$(DESTDIR)$(ENV_FILE)" ]; then \
+		install -m 0640 deploy/systemd/matrix-runtime.env.example "$(DESTDIR)$(ENV_FILE)"; \
+		echo "installed env file: $(DESTDIR)$(ENV_FILE) (edit before starting)"; \
+	else echo "env file exists, leaving as-is: $(DESTDIR)$(ENV_FILE)"; fi
+	install -d "$(DESTDIR)$(SYSTEMD_DIR)"
+	sed -e "s|@BINDIR@|$(BINDIR)|g" \
+	    -e "s|@ENV_FILE@|$(ENV_FILE)|g" \
+	    -e "s|@DATA_DIR@|$(DATA_DIR)|g" \
+	    -e "s|@SERVICE_USER@|$(SERVICE_USER)|g" \
+	    deploy/systemd/matrix-runtime.service.in > "$(DESTDIR)$(SYSTEMD_DIR)/matrix-runtime.service"
+	@echo "installed unit: $(DESTDIR)$(SYSTEMD_DIR)/matrix-runtime.service"
+	@echo "next: sudo systemctl daemon-reload && sudo systemctl enable --now matrix-runtime"
+
+## uninstall: remove the installed binary (and systemd unit if present)
+uninstall:
+	@bindir="$(DESTDIR)$(BINDIR)"; sudo=""; \
+	if [ "$$(id -u)" != "0" ] && [ -e "$$bindir/$(BINARY)" ] && [ ! -w "$$bindir" ]; then \
+		command -v sudo >/dev/null 2>&1 && sudo="sudo"; fi; \
+	$$sudo rm -f "$$bindir/$(BINARY)"; \
+	if [ -f "$(DESTDIR)$(SYSTEMD_DIR)/matrix-runtime.service" ]; then \
+		$$sudo rm -f "$(DESTDIR)$(SYSTEMD_DIR)/matrix-runtime.service"; \
+		echo "removed systemd unit (run: sudo systemctl daemon-reload)"; \
+	fi; \
+	echo "uninstalled $(BINARY)"
+
+## release: cross-compile static binaries into ./dist
+release:
+	@mkdir -p dist
+	@for osarch in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do \
+		os=$${osarch%/*}; arch=$${osarch#*/}; \
+		out="dist/$(BINARY)-$$os-$$arch"; \
+		echo "building $$out"; \
+		CGO_ENABLED=0 GOOS=$$os GOARCH=$$arch \
+			go build $(GOFLAGS_PROD) -ldflags "$(LDFLAGS)" -o "$$out" $(PKG) || exit 1; \
+	done
+	@echo "release artifacts in ./dist"
+
+## clean: remove build artifacts
+clean:
+	rm -rf $(BIN_DIR) dist coverage.out coverage.html
+
+## help: list targets
+help:
+	@printf "\n  \033[1;32mMatrix Runtime\033[0m — the execution plane for Matrix Cloud\n"
+	@printf "  backend API + embedded MatrixCloud console + SQLite, in one binary\n\n"
+	@printf "  \033[1mTargets\033[0m\n"
+	@grep -E '^## [a-z][a-z-]*:' $(MAKEFILE_LIST) \
+		| sed -E 's/^## ([a-z-]+): /\1|/' \
+		| awk -F'|' '{printf "    \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+	@printf "\n  \033[1mQuick start\033[0m\n"
+	@printf "    make run                     start everything → http://localhost:8080\n"
+	@printf "    make build                   build bin/matrix-runtime\n"
+	@printf "    make test                    fmt-check + vet + race tests + coverage\n"
+	@printf "    sudo make install            install to /usr/local/bin\n"
+	@printf "    make install PREFIX=\$$HOME/.local   user install, no root\n\n"

README.md

@@ -0,0 +1,36 @@
+---
+title: MatrixCloud
+emoji: 🟢
+colorFrom: green
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+short_description: "Self-hostable execution plane for AI: MCP, models, agents."
+---
+
+# MatrixCloud
+
+The self-hostable **execution plane** for MatrixCloud: run MCP server sandboxes,
+inspect Hugging Face models, use the MatrixShell operator terminal, and bring
+your own HF token to run HF LLMs — all from one console.
+
+This Space runs the single static `matrix-runtime` binary (API + embedded React
+console). The container launcher is `app/main.py`; the binary is built from the
+[`agent-matrix/matrix-runtime`](https://github.com/agent-matrix/matrix-runtime)
+repository at build time.
+
+## Configure (Space → Settings → Variables and secrets)
+
+**Secrets**
+- `MATRIXCLOUD_DATABASE_URL` — PostgreSQL/Neon DSN (durable accounts across
+  rebuilds). Without it, data lives in ephemeral `/tmp` and resets on restart.
+- `MATRIXCLOUD_SECRET_KEY` — `openssl rand -hex 32` (stable encryption key).
+- `RESEND_API_KEY` — optional; enables welcome/password-reset emails.
+
+**Variables**
+- `MATRIXCLOUD_DB_SCHEMA=matrixcloud`
+- `MATRIXCLOUD_APP_URL=https://<owner>-matrixcloud.hf.space`
+
+Open the Space URL, create an account, and you're in.

api/audit.go

@@ -0,0 +1,67 @@
+package api
+
+import (
+	"log"
+	"net"
+	"net/http"
+	"strings"
+
+	"github.com/agent-matrix/matrix-runtime/internal/store"
+)
+
+// clientIP best-effort extracts the caller IP, honoring common proxy headers
+// (the API typically runs behind Cloudflare / an ingress).
+func clientIP(r *http.Request) string {
+	if v := r.Header.Get("CF-Connecting-IP"); v != "" {
+		return v
+	}
+	if v := r.Header.Get("X-Forwarded-For"); v != "" {
+		return strings.TrimSpace(strings.Split(v, ",")[0])
+	}
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		return host
+	}
+	return r.RemoteAddr
+}
+
+// audit records a sensitive action. It is best-effort: a nil store or a write
+// error never affects the request outcome (only logged).
+func (s *Server) audit(r *http.Request, workspaceID, actor, action, target, status string, meta map[string]any) {
+	if s.store == nil {
+		return
+	}
+	if err := s.store.RecordAudit(store.AuditEvent{
+		WorkspaceID: workspaceID,
+		Actor:       actor,
+		Action:      action,
+		Target:      target,
+		IP:          clientIP(r),
+		Status:      status,
+		Meta:        meta,
+	}); err != nil {
+		log.Printf("audit: could not record %s: %v", action, err)
+	}
+}
+
+// truncate shortens s to at most n characters for audit targets.
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…"
+}
+
+// handleCloudAudit returns the workspace's recent audit events.
+func (s *Server) handleCloudAudit(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	events, err := s.store.ListAudit(u.WorkspaceID, 200)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not load audit log")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"events": events})
+}

api/auth_test.go

@@ -0,0 +1,106 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/agent-matrix/matrix-runtime/internal/config"
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+	"github.com/agent-matrix/matrix-runtime/internal/store"
+)
+
+func authServer(t *testing.T) *Server {
+	t.Helper()
+	cfg := config.Defaults(config.ModeLocalDev)
+	cfg.DataDir = t.TempDir()
+	st, err := store.Open(filepath.Join(t.TempDir(), "auth.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+	return NewServer(cfg, jobs.NewManager(cfg), st)
+}
+
+func do(t *testing.T, srv *Server, method, path, token, body string) (*httptest.ResponseRecorder, map[string]any) {
+	t.Helper()
+	var rdr *httptest.ResponseRecorder = httptest.NewRecorder()
+	req := httptest.NewRequest(method, path, jsonBody(body))
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	srv.Handler().ServeHTTP(rdr, req)
+	var out map[string]any
+	_ = json.Unmarshal(rdr.Body.Bytes(), &out)
+	return rdr, out
+}
+
+func TestAuthFlow(t *testing.T) {
+	srv := authServer(t)
+
+	// signup
+	rec, body := do(t, srv, http.MethodPost, "/v1/auth/signup", "", `{"name":"Neo","email":"neo@zion.io","password":"redpill1"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("signup status %d: %v", rec.Code, body)
+	}
+	token, _ := body["token"].(string)
+	if token == "" {
+		t.Fatal("expected a session token")
+	}
+	user, _ := body["user"].(map[string]any)
+	if user["role"] != "Owner" || user["workspace"] == "" {
+		t.Errorf("unexpected user %v", user)
+	}
+
+	// me with token
+	rec, body = do(t, srv, http.MethodGet, "/v1/auth/me", token, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("me status %d", rec.Code)
+	}
+
+	// me without token -> 401
+	rec, _ = do(t, srv, http.MethodGet, "/v1/auth/me", "", "")
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("me-no-token status %d, want 401", rec.Code)
+	}
+
+	// duplicate signup -> 409
+	rec, _ = do(t, srv, http.MethodPost, "/v1/auth/signup", "", `{"name":"X","email":"neo@zion.io","password":"redpill1"}`)
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("dup signup status %d, want 409", rec.Code)
+	}
+
+	// wrong login -> 401
+	rec, _ = do(t, srv, http.MethodPost, "/v1/auth/login", "", `{"email":"neo@zion.io","password":"nope"}`)
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("bad login status %d, want 401", rec.Code)
+	}
+
+	// correct login -> 200
+	rec, body = do(t, srv, http.MethodPost, "/v1/auth/login", "", `{"email":"neo@zion.io","password":"redpill1"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("login status %d", rec.Code)
+	}
+
+	// logout invalidates the session
+	rec, _ = do(t, srv, http.MethodPost, "/v1/auth/logout", token, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("logout status %d", rec.Code)
+	}
+	rec, _ = do(t, srv, http.MethodGet, "/v1/auth/me", token, "")
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("me after logout status %d, want 401", rec.Code)
+	}
+}
+
+func TestAuthUnavailableWithoutStore(t *testing.T) {
+	cfg := config.Defaults(config.ModeLocalDev)
+	cfg.DataDir = t.TempDir()
+	srv := NewServer(cfg, jobs.NewManager(cfg), nil)
+	rec, _ := do(t, srv, http.MethodPost, "/v1/auth/login", "", `{"email":"a@b.io","password":"x"}`)
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("expected 503 without store, got %d", rec.Code)
+	}
+}

api/cloud_test.go

@@ -0,0 +1,119 @@
+package api
+
+import (
+	"net/http"
+	"testing"
+)
+
+func TestCloudRuntimeAndProviderFlow(t *testing.T) {
+	srv := authServer(t)
+
+	// Create a workspace owner and grab a session token.
+	rec, body := do(t, srv, http.MethodPost, "/v1/auth/signup", "", `{"name":"Maya","email":"maya@acme.io","password":"hunter22"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("signup %d: %v", rec.Code, body)
+	}
+	token, _ := body["token"].(string)
+
+	// Mint a join token.
+	rec, body = do(t, srv, http.MethodPost, "/v1/cloud/join-tokens", token, `{"label":"my space","max_uses":1,"ttl_minutes":60}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("mint join token %d: %v", rec.Code, body)
+	}
+	secret, _ := body["secret"].(string)
+	if secret == "" {
+		t.Fatal("expected a join-token secret")
+	}
+
+	// Register a runtime using the join token (no session — simulates a remote Space).
+	rec, body = do(t, srv, http.MethodPost, "/v1/cloud/runtimes/register", "",
+		`{"join_token":"`+secret+`","name":"maya-space","kind":"hf-space","hf_space":"maya/matrixcloud","caps":["mcp.test"]}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("register runtime %d: %v", rec.Code, body)
+	}
+	runtimeToken, _ := body["runtime_token"].(string)
+	if runtimeToken == "" {
+		t.Fatal("expected a runtime token")
+	}
+
+	// The join token is single-use now.
+	rec, _ = do(t, srv, http.MethodPost, "/v1/cloud/runtimes/register", "",
+		`{"join_token":"`+secret+`","name":"again"}`)
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("reused join token should 401, got %d", rec.Code)
+	}
+
+	// Heartbeat with the runtime token.
+	rec, _ = do(t, srv, http.MethodPost, "/v1/cloud/runtimes/heartbeat", runtimeToken, `{"status":"online","caps":["mcp.test","model.inspect"]}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("heartbeat %d", rec.Code)
+	}
+	// Bad runtime token rejected.
+	rec, _ = do(t, srv, http.MethodPost, "/v1/cloud/runtimes/heartbeat", "bogus", `{"status":"online"}`)
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("bad heartbeat token should 401, got %d", rec.Code)
+	}
+
+	// The owner sees the runtime online.
+	rec, body = do(t, srv, http.MethodGet, "/v1/cloud/runtimes", token, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("list runtimes %d", rec.Code)
+	}
+	rts, _ := body["runtimes"].([]any)
+	if len(rts) != 1 {
+		t.Fatalf("expected 1 runtime, got %d", len(rts))
+	}
+
+	// Store a BYO Hugging Face credential; only a hint is ever returned.
+	rec, body = do(t, srv, http.MethodPost, "/v1/cloud/providers", token,
+		`{"provider":"huggingface","label":"default","secret":"hf_supersecret9","meta":{"default_model":"Qwen/Qwen2.5-7B-Instruct"}}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("set provider %d: %v", rec.Code, body)
+	}
+	rec, body = do(t, srv, http.MethodGet, "/v1/cloud/providers", token, "")
+	provs, _ := body["providers"].([]any)
+	if len(provs) != 1 {
+		t.Fatalf("expected 1 provider, got %v", body)
+	}
+	p0, _ := provs[0].(map[string]any)
+	if hint, _ := p0["hint"].(string); hint == "" || hint == "hf_supersecret9" {
+		t.Errorf("provider must expose only a hint, got %v", p0["hint"])
+	}
+
+	// Cloud endpoints require auth.
+	rec, _ = do(t, srv, http.MethodGet, "/v1/cloud/runtimes", "", "")
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("unauth list should 401, got %d", rec.Code)
+	}
+}
+
+func TestAuditLogRecordsActions(t *testing.T) {
+	srv := authServer(t)
+	_, body := do(t, srv, http.MethodPost, "/v1/auth/signup", "", `{"name":"Auditor","email":"audit@acme.io","password":"hunter22"}`)
+	token, _ := body["token"].(string)
+
+	// Generate a couple of auditable actions.
+	do(t, srv, http.MethodPost, "/v1/cloud/join-tokens", token, `{"label":"x","max_uses":1}`)
+	do(t, srv, http.MethodPost, "/v1/cloud/providers", token, `{"provider":"huggingface","secret":"hf_abc1234"}`)
+
+	rec, b := do(t, srv, http.MethodGet, "/v1/cloud/audit", token, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("audit list %d: %v", rec.Code, b)
+	}
+	events, _ := b["events"].([]any)
+	actions := map[string]bool{}
+	for _, e := range events {
+		if m, ok := e.(map[string]any); ok {
+			actions[m["action"].(string)] = true
+		}
+	}
+	for _, want := range []string{"user.signup", "runtime.join_token.created", "provider.credential.added"} {
+		if !actions[want] {
+			t.Errorf("missing audit action %q (got %v)", want, actions)
+		}
+	}
+	// Unauthenticated access is rejected.
+	if rec, _ := do(t, srv, http.MethodGet, "/v1/cloud/audit", "", ""); rec.Code != http.StatusUnauthorized {
+		t.Errorf("unauth audit = %d, want 401", rec.Code)
+	}
+}

api/handlers_auth.go

@@ -0,0 +1,204 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/agent-matrix/matrix-runtime/internal/store"
+)
+
+var emailRe = regexp.MustCompile(`^[^\s@]+@[^\s@]+\.[^\s@]+$`)
+
+// userJSON is the public shape of a user returned to the console.
+func userJSON(u *store.User) map[string]any {
+	return map[string]any{
+		"id":             u.ID,
+		"name":           u.Name,
+		"email":          u.Email,
+		"role":           u.Role,
+		"workspace":      u.WorkspaceName,
+		"workspace_slug": u.WorkspaceSlug,
+		"workspace_id":   u.WorkspaceID,
+	}
+}
+
+func (s *Server) requireStore(w http.ResponseWriter) bool {
+	if s.store == nil {
+		writeError(w, http.StatusServiceUnavailable, "user store is not available")
+		return false
+	}
+	return true
+}
+
+func (s *Server) handleSignup(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	var req struct{ Name, Email, Password, Workspace string }
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	req.Email = strings.TrimSpace(req.Email)
+	if !emailRe.MatchString(req.Email) {
+		writeError(w, http.StatusBadRequest, "enter a valid email address")
+		return
+	}
+	if len(req.Password) < 6 {
+		writeError(w, http.StatusBadRequest, "password must be at least 6 characters")
+		return
+	}
+	if strings.TrimSpace(req.Name) == "" {
+		writeError(w, http.StatusBadRequest, "name is required")
+		return
+	}
+	u, err := s.store.Signup(req.Name, req.Email, req.Password, req.Workspace)
+	if err != nil {
+		if errors.Is(err, store.ErrEmailTaken) {
+			writeError(w, http.StatusConflict, err.Error())
+			return
+		}
+		writeError(w, http.StatusInternalServerError, "could not create account")
+		return
+	}
+	token, err := s.store.CreateSession(u.ID)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not start session")
+		return
+	}
+	s.audit(r, u.WorkspaceID, u.ID, "user.signup", u.Email, "success", nil)
+	// Best-effort welcome + verification email (never blocks signup success).
+	if verifyTok, verr := s.store.CreateEmailVerification(u.ID, 24*time.Hour); verr == nil {
+		go func() {
+			ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+			defer cancel()
+			_ = s.email.SendWelcome(ctx, u.Email, u.Name, verifyTok)
+		}()
+	}
+	writeJSON(w, http.StatusCreated, map[string]any{"token": token, "user": userJSON(u)})
+}
+
+func (s *Server) handleLogin(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	var req struct{ Email, Password string }
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	u, err := s.store.Login(req.Email, req.Password)
+	if err != nil {
+		s.audit(r, "", strings.ToLower(strings.TrimSpace(req.Email)), "user.login", req.Email, "failure", nil)
+		writeError(w, http.StatusUnauthorized, "invalid email or password")
+		return
+	}
+	token, err := s.store.CreateSession(u.ID)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not start session")
+		return
+	}
+	s.audit(r, u.WorkspaceID, u.ID, "user.login", u.Email, "success", nil)
+	writeJSON(w, http.StatusOK, map[string]any{"token": token, "user": userJSON(u)})
+}
+
+func (s *Server) handleMe(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	u, err := s.store.UserBySession(bearer(r))
+	if err != nil {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"user": userJSON(u)})
+}
+
+func (s *Server) handleLogout(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	token := bearer(r)
+	all := r.URL.Query().Get("all") == "true"
+	if all {
+		if u, err := s.store.UserBySession(token); err == nil {
+			_ = s.store.DeleteUserSessions(u.ID)
+		}
+	}
+	_ = s.store.DeleteSession(token)
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
+}
+
+func bearer(r *http.Request) string {
+	return strings.TrimSpace(strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer "))
+}
+
+// handleForgotPassword always responds 200 (to avoid leaking which emails are
+// registered). When the email matches a user, a reset link is emailed via
+// Resend with a single-use, 1-hour token.
+func (s *Server) handleForgotPassword(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	var req struct{ Email string }
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	const ok = "If an account exists for that email, a reset link is on its way."
+	u, err := s.store.UserByEmail(req.Email)
+	if err != nil {
+		// Don't reveal absence; respond identically.
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true, "message": ok})
+		return
+	}
+	token, err := s.store.CreatePasswordReset(u.ID, time.Hour)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not start password reset")
+		return
+	}
+	if err := s.email.SendPasswordReset(r.Context(), u.Email, token); err != nil {
+		writeError(w, http.StatusBadGateway, "could not send reset email")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "message": ok})
+}
+
+// handleResetPassword consumes a reset token and sets a new password.
+func (s *Server) handleResetPassword(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	var req struct{ Token, Password string }
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	if err := s.store.ResetPassword(strings.TrimSpace(req.Token), req.Password); err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "message": "Your password has been updated. Please sign in."})
+}
+
+// handleVerifyEmail consumes an email-verification token.
+func (s *Server) handleVerifyEmail(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	var req struct{ Token string }
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	if _, err := s.store.VerifyEmail(strings.TrimSpace(req.Token)); err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "message": "Email verified."})
+}

api/handlers_cloud.go

@@ -0,0 +1,207 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/agent-matrix/matrix-runtime/internal/store"
+)
+
+// staleAfter marks a runtime offline if it hasn't sent a heartbeat recently.
+const runtimeStaleAfter = 90 * time.Second
+
+// handleCloudListRuntimes returns the calling workspace's registered runtimes.
+func (s *Server) handleCloudListRuntimes(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	list, err := s.store.ListRuntimes(u.WorkspaceID, runtimeStaleAfter)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not list runtimes")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"runtimes": list})
+}
+
+// handleCloudRegisterRuntime is called by a remote sandbox (e.g. a duplicated
+// HF Space) presenting a workspace join token. It registers the runtime and
+// returns a long-lived runtime token used for subsequent heartbeats.
+func (s *Server) handleCloudRegisterRuntime(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	var req struct {
+		JoinToken string   `json:"join_token"`
+		Name      string   `json:"name"`
+		Kind      string   `json:"kind"`
+		Mode      string   `json:"mode"`
+		URL       string   `json:"url"`
+		HFSpace   string   `json:"hf_space"`
+		Region    string   `json:"region"`
+		Version   string   `json:"version"`
+		Caps      []string `json:"caps"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	workspaceID, err := s.store.RedeemJoinToken(req.JoinToken)
+	if err != nil {
+		writeError(w, http.StatusUnauthorized, err.Error())
+		return
+	}
+	if req.Name == "" {
+		req.Name = req.HFSpace
+	}
+	if req.Kind == "" {
+		req.Kind = "hf-space"
+	}
+	rt, token, err := s.store.RegisterRuntime(store.Runtime{
+		WorkspaceID: workspaceID,
+		Name:        req.Name,
+		Mode:        req.Mode,
+		Kind:        req.Kind,
+		URL:         req.URL,
+		HFSpace:     req.HFSpace,
+		Region:      req.Region,
+		Version:     req.Version,
+		Caps:        req.Caps,
+	})
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not register runtime")
+		return
+	}
+	s.audit(r, workspaceID, rt.ID, "runtime.registered", rt.Name, "success", map[string]any{"kind": rt.Kind, "hf_space": rt.HFSpace})
+	writeJSON(w, http.StatusCreated, map[string]any{"runtime": rt, "runtime_token": token})
+}
+
+// handleCloudHeartbeat updates a runtime's status using its runtime token
+// (Authorization: Bearer <runtime_token>).
+func (s *Server) handleCloudHeartbeat(w http.ResponseWriter, r *http.Request) {
+	if !s.requireStore(w) {
+		return
+	}
+	var req struct {
+		Status string   `json:"status"`
+		Caps   []string `json:"caps"`
+	}
+	_ = json.NewDecoder(r.Body).Decode(&req)
+	rt, err := s.store.HeartbeatRuntime(bearer(r), req.Status, req.Caps)
+	if err != nil {
+		if errors.Is(err, store.ErrNotFound) {
+			writeError(w, http.StatusUnauthorized, "invalid runtime token")
+			return
+		}
+		writeError(w, http.StatusInternalServerError, "could not record heartbeat")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"runtime": rt})
+}
+
+// handleCloudListJoinTokens lists the workspace's active join tokens.
+func (s *Server) handleCloudListJoinTokens(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	list, err := s.store.ListJoinTokens(u.WorkspaceID)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not list join tokens")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"join_tokens": list})
+}
+
+// handleCloudMintJoinToken mints a new join token for the workspace. The secret
+// is returned exactly once.
+func (s *Server) handleCloudMintJoinToken(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	var req struct {
+		Label      string `json:"label"`
+		MaxUses    int    `json:"max_uses"`
+		TTLMinutes int    `json:"ttl_minutes"`
+	}
+	_ = json.NewDecoder(r.Body).Decode(&req)
+	ttl := time.Duration(req.TTLMinutes) * time.Minute
+	if req.TTLMinutes == 0 {
+		ttl = 24 * time.Hour
+	}
+	jt, secret, err := s.store.MintJoinToken(u.WorkspaceID, u.ID, req.Label, req.MaxUses, ttl)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not mint join token")
+		return
+	}
+	s.audit(r, u.WorkspaceID, u.ID, "runtime.join_token.created", jt.ID, "success", map[string]any{"label": jt.Label, "max_uses": jt.MaxUses})
+	writeJSON(w, http.StatusCreated, map[string]any{"join_token": jt, "secret": secret})
+}
+
+// handleCloudListProviders lists BYO provider credentials (hints only).
+func (s *Server) handleCloudListProviders(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	list, err := s.store.ListProviderCredentials(u.WorkspaceID)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not list providers")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"providers": list})
+}
+
+// handleCloudSetProvider stores (encrypted) a BYO provider token — e.g. a user
+// plugging in their own Hugging Face account to use HF LLMs inside MatrixCloud.
+func (s *Server) handleCloudSetProvider(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	var req struct {
+		Provider string         `json:"provider"`
+		Label    string         `json:"label"`
+		Secret   string         `json:"secret"`
+		Meta     map[string]any `json:"meta"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	if req.Provider == "" || req.Secret == "" {
+		writeError(w, http.StatusBadRequest, "provider and secret are required")
+		return
+	}
+	pc, err := s.store.SetProviderCredential(u.WorkspaceID, u.ID, req.Provider, req.Label, req.Secret, req.Meta)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not save credential")
+		return
+	}
+	s.audit(r, u.WorkspaceID, u.ID, "provider.credential.added", req.Provider, "success", map[string]any{"label": pc.Label, "hint": pc.Hint})
+	writeJSON(w, http.StatusCreated, map[string]any{"provider": pc})
+}
+
+// handleCloudUsage returns the workspace's usage in the trailing 30 days.
+func (s *Server) handleCloudUsage(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	since := time.Now().Add(-30 * 24 * time.Hour)
+	used, err := s.store.UsageSince(u.WorkspaceID, since)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not load usage")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"since": since.UTC().Format(time.RFC3339), "usage": used})
+}

api/handlers_health.go

@@ -0,0 +1,110 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/agent-matrix/matrix-runtime/internal/config"
+	"github.com/agent-matrix/matrix-runtime/internal/runtime"
+)
+
+func (s *Server) handleHealth(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]any{
+		"status":     "ok",
+		"runtime_id": s.cfg.EffectiveRuntimeID(),
+		"mode":       string(s.cfg.Mode),
+		"version":    config.Version,
+	})
+}
+
+func (s *Server) handleCapabilities(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, runtime.BuildCapabilities(s.cfg))
+}
+
+// handleVersion returns build/version metadata for monitoring and support.
+func (s *Server) handleVersion(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]any{
+		"name":       "matrix-runtime",
+		"version":    config.Version,
+		"commit":     config.Commit,
+		"build_time": config.Date,
+		"mode":       string(s.cfg.Mode),
+	})
+}
+
+// handleReady is the readiness probe: it verifies core dependencies (database
+// reachable, data directory writable, job manager running, mode valid) and
+// reports non-fatal misconfiguration as warnings. It returns 200 when ready and
+// 503 when a core check fails, so Kubernetes can gate traffic.
+func (s *Server) handleReady(w http.ResponseWriter, r *http.Request) {
+	checks := map[string]bool{}
+	warnings := []map[string]string{}
+	warn := func(code, msg string) { warnings = append(warnings, map[string]string{"code": code, "message": msg}) }
+
+	// Mode valid.
+	checks["mode_valid"] = s.cfg.Mode.Valid()
+
+	// Job manager running.
+	checks["job_manager"] = s.manager != nil
+
+	// Data directory writable.
+	checks["data_dir_writable"] = dirWritable(s.cfg.DataDir)
+
+	// Database reachable (only when a store is configured).
+	if s.store != nil {
+		ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
+		defer cancel()
+		checks["database"] = s.store.Ping(ctx) == nil
+	} else {
+		checks["database"] = false
+		warn("store_unavailable", "User store is not available; auth endpoints return 503.")
+	}
+
+	// Non-fatal security warnings.
+	if s.cfg.IsProduction() && s.cfg.APIToken == "" {
+		warn("api_token_missing", "MATRIX_RUNTIME_API_TOKEN is not set; the API is unauthenticated for non-session callers.")
+	}
+	if s.cfg.MatrixShellEnabled {
+		warn("matrixshell_enabled", "MatrixShell is enabled; it executes commands in a local sandbox.")
+	}
+	if s.cfg.IsProduction() && s.cfg.DatabaseURL == "" {
+		warn("sqlite_in_use", "Using SQLite; configure MATRIX_RUNTIME_DATABASE_URL (Postgres) for multi-user/HA deployments.")
+	}
+	if s.cfg.Mode == config.ModeLocalDev {
+		warn("local_dev_mode", "Runtime is in local-dev mode; not hardened for production.")
+	}
+
+	ready := true
+	for _, ok := range checks {
+		if !ok {
+			ready = false
+		}
+	}
+	status := http.StatusOK
+	if !ready {
+		status = http.StatusServiceUnavailable
+	}
+	writeJSON(w, status, map[string]any{"ready": ready, "checks": checks, "warnings": warnings})
+}
+
+// dirWritable reports whether dir exists (creating it if needed) and accepts a
+// temporary file write.
+func dirWritable(dir string) bool {
+	if dir == "" {
+		return false
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return false
+	}
+	f, err := os.CreateTemp(dir, ".ready-*")
+	if err != nil {
+		return false
+	}
+	name := f.Name()
+	_ = f.Close()
+	_ = os.Remove(filepath.Join(dir, filepath.Base(name)))
+	return true
+}

api/handlers_jobs.go

@@ -0,0 +1,103 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+	"github.com/agent-matrix/matrix-runtime/internal/logs"
+)
+
+func (s *Server) handleCreateJob(w http.ResponseWriter, r *http.Request) {
+	var req jobs.CreateRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body: "+err.Error())
+		return
+	}
+	j, err := s.manager.Create(req)
+	if err != nil {
+		if errors.Is(err, jobs.ErrUnknownType) {
+			writeError(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		writeError(w, http.StatusUnprocessableEntity, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]any{
+		"job_id":     j.ID,
+		"status":     j.Status(),
+		"events_url": "/v1/jobs/" + j.ID + "/events",
+	})
+}
+
+func (s *Server) handleListJobs(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]any{"jobs": s.manager.List()})
+}
+
+func (s *Server) handleGetJob(w http.ResponseWriter, r *http.Request) {
+	j, ok := s.manager.Get(r.PathValue("job_id"))
+	if !ok {
+		writeError(w, http.StatusNotFound, "job not found")
+		return
+	}
+	writeJSON(w, http.StatusOK, j.Snapshot())
+}
+
+func (s *Server) handleDeleteJob(w http.ResponseWriter, r *http.Request) {
+	status, ok := s.manager.Cancel(r.PathValue("job_id"))
+	if !ok {
+		writeError(w, http.StatusNotFound, "job not found")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "status": status})
+}
+
+func (s *Server) handleJobEvents(w http.ResponseWriter, r *http.Request) {
+	j, ok := s.manager.Get(r.PathValue("job_id"))
+	if !ok {
+		writeError(w, http.StatusNotFound, "job not found")
+		return
+	}
+	streamEvents(w, r, j.Bus())
+}
+
+// streamEvents writes a job's event history and live updates as Server-Sent
+// Events until the bus closes or the client disconnects.
+func streamEvents(w http.ResponseWriter, r *http.Request, bus *logs.Bus) {
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		writeError(w, http.StatusInternalServerError, "streaming unsupported")
+		return
+	}
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.WriteHeader(http.StatusOK)
+
+	history, ch, cancel := bus.Subscribe()
+	defer cancel()
+
+	send := func(e logs.Event) {
+		b, _ := json.Marshal(e)
+		_, _ = w.Write([]byte("data: "))
+		_, _ = w.Write(b)
+		_, _ = w.Write([]byte("\n\n"))
+		flusher.Flush()
+	}
+
+	for _, e := range history {
+		send(e)
+	}
+	for {
+		select {
+		case <-r.Context().Done():
+			return
+		case e, open := <-ch:
+			if !open {
+				return
+			}
+			send(e)
+		}
+	}
+}

api/handlers_matrixshell.go

@@ -0,0 +1,85 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+	"github.com/agent-matrix/matrix-runtime/internal/matrixshell"
+)
+
+// requireMatrixShell rejects requests when MatrixShell is disabled. It executes
+// commands in a local sandbox, so it is off by default in production modes.
+func (s *Server) requireMatrixShell(w http.ResponseWriter) bool {
+	if !s.cfg.MatrixShellEnabled {
+		writeError(w, http.StatusForbidden, "MatrixShell is disabled (set MATRIX_SHELL_ENABLED=true to enable)")
+		return false
+	}
+	return true
+}
+
+// handleMatrixShellStatus reports whether MatrixShell is installed in the local
+// Python sandbox, with its version and paths.
+func (s *Server) handleMatrixShellStatus(w http.ResponseWriter, r *http.Request) {
+	if !s.requireMatrixShell(w) {
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 8*time.Second)
+	defer cancel()
+	writeJSON(w, http.StatusOK, matrixshell.GetStatus(ctx, s.cfg.DataDir))
+}
+
+// handleMatrixShellInstall starts a job that creates the sandbox venv and
+// installs MatrixShell from git, streaming real output over SSE.
+func (s *Server) handleMatrixShellInstall(w http.ResponseWriter, _ *http.Request) {
+	if !s.requireMatrixShell(w) {
+		return
+	}
+	job, err := s.manager.Create(jobs.CreateRequest{Type: jobs.TypeMatrixShellInstall, TTLSeconds: 600})
+	if err != nil {
+		writeError(w, http.StatusUnprocessableEntity, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]any{
+		"job_id":     job.ID,
+		"events_url": "/v1/jobs/" + job.ID + "/events",
+	})
+}
+
+// handleMatrixShellExec runs a command inside the local MatrixShell sandbox
+// (real execution with the venv on PATH) and returns stdout/stderr/exit.
+func (s *Server) handleMatrixShellExec(w http.ResponseWriter, r *http.Request) {
+	if !s.requireMatrixShell(w) {
+		return
+	}
+	var req struct {
+		Command string `json:"command"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	wsID, actor := "", "operator"
+	if u, ok := s.currentUser(r); ok {
+		wsID, actor = u.WorkspaceID, u.ID
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 60*time.Second)
+	defer cancel()
+	res, err := matrixshell.Exec(ctx, s.cfg.DataDir, req.Command)
+	if err != nil {
+		if errors.Is(err, matrixshell.ErrBlocked) {
+			s.audit(r, wsID, actor, "matrixshell.exec", truncate(req.Command, 200), "failure", map[string]any{"reason": "denylist"})
+			writeError(w, http.StatusForbidden, "refused by safety denylist")
+			return
+		}
+		writeError(w, http.StatusUnprocessableEntity, err.Error())
+		return
+	}
+	s.audit(r, wsID, actor, "matrixshell.exec", truncate(req.Command, 200), "success", map[string]any{"exit_code": res.ExitCode})
+	writeJSON(w, http.StatusOK, map[string]any{
+		"command": req.Command, "stdout": res.Stdout, "stderr": res.Stderr, "exit_code": res.ExitCode,
+	})
+}

api/handlers_models.go

@@ -0,0 +1,271 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/agent-matrix/matrix-runtime/internal/hf"
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+	"github.com/agent-matrix/matrix-runtime/internal/models"
+	"github.com/agent-matrix/matrix-runtime/internal/store"
+)
+
+// currentUser resolves the session bearer token to a user, or returns false.
+func (s *Server) currentUser(r *http.Request) (*store.User, bool) {
+	if s.store == nil {
+		return nil, false
+	}
+	u, err := s.store.UserBySession(bearer(r))
+	if err != nil {
+		return nil, false
+	}
+	return u, true
+}
+
+// handleHFSearch proxies the Hugging Face model search server-side (avoiding
+// browser CORS) for the console's generic Import Model flow. On any failure it
+// returns 200 with live=false and an empty list so the UI can fall back to
+// sample data gracefully.
+func (s *Server) handleHFSearch(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query().Get("q")
+	task := r.URL.Query().Get("task")
+	limit := 16
+	if v := r.URL.Query().Get("limit"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			limit = n
+		}
+	}
+	items, err := hf.NewClient(s.cfg.HFToken).Search(r.Context(), q, task, limit)
+	if err != nil {
+		writeJSON(w, http.StatusOK, map[string]any{"items": []any{}, "live": false, "error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items, "live": true})
+}
+
+// resolveReq describes a generic model source to resolve into a profile preview.
+type resolveReq struct {
+	SourceType string `json:"sourceType"`
+	SourceURI  string `json:"sourceUri"`
+	Provider   string `json:"provider"`
+	ExternalID string `json:"externalId"` // e.g. HF model id
+	Model      string `json:"model"`      // e.g. hf:owner/name
+	Path       string `json:"path"`
+	Branch     string `json:"branch"`
+	Private    bool   `json:"private"`
+}
+
+// handleResolveSource resolves a source into a model-profile preview. Hugging
+// Face is resolved for real via model.inspect; other sources are constructed
+// from the supplied location.
+func (s *Server) handleResolveSource(w http.ResponseWriter, r *http.Request) {
+	var req resolveReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	isHF := req.SourceType == "huggingface" || strings.HasPrefix(req.Model, "hf:") || (req.Provider == "Hugging Face")
+	if isHF {
+		id := req.ExternalID
+		if id == "" {
+			id = strings.TrimPrefix(req.Model, "hf:")
+		}
+		meta, err := models.Inspect(r.Context(), "hf:"+id, "main", s.cfg.HFToken)
+		if err != nil {
+			writeError(w, http.StatusBadGateway, "could not resolve model: "+err.Error())
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]any{
+			"source_type": "huggingface", "provider": "Hugging Face", "external_id": id,
+			"display_name": id, "source_uri": "hf:" + id,
+			"task": meta.PipelineTag, "library": meta.LibraryName, "license": meta.License,
+			"requires_gpu": meta.RequiresGPU, "recommended_runtime": meta.RecommendedRuntime,
+			"estimated_parameters": meta.EstimatedParameters, "tags": meta.Tags, "private": req.Private,
+		})
+		return
+	}
+	// Generic (GitHub/GitLab/S3/R2/Ollama/URL): construct a profile from the form.
+	uri := req.SourceURI
+	if req.Path != "" {
+		uri = strings.TrimRight(uri, "/") + "/" + strings.TrimLeft(req.Path, "/")
+	}
+	name := req.ExternalID
+	if name == "" {
+		name = uri
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"source_type": req.SourceType, "provider": req.Provider, "external_id": name,
+		"display_name": name, "source_uri": uri, "task": "text-generation",
+		"library": "custom", "license": "review required", "private": req.Private,
+		"recommended_runtime": "vLLM / SGLang",
+	})
+}
+
+// profileJSON shapes a stored profile for the API.
+func profileJSON(p store.ModelProfile) map[string]any {
+	return map[string]any{
+		"id": p.ID, "source_type": p.SourceType, "source_uri": p.SourceURI,
+		"provider": p.Provider, "external_id": p.ExternalID, "display_name": p.DisplayName,
+		"task": p.Task, "library": p.Library, "license": p.License, "tags": p.Tags,
+		"status": p.Status, "created_at": p.CreatedAt, "metadata": p.Metadata,
+	}
+}
+
+// handleListProfiles lists model profiles for the caller's workspace.
+func (s *Server) handleListProfiles(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	list, err := s.store.ListProfiles(u.WorkspaceID)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	out := make([]map[string]any, 0, len(list))
+	for _, p := range list {
+		out = append(out, profileJSON(p))
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"profiles": out})
+}
+
+type importReq struct {
+	SourceType  string         `json:"source_type"`
+	SourceURI   string         `json:"source_uri"`
+	Provider    string         `json:"provider"`
+	ExternalID  string         `json:"external_id"`
+	DisplayName string         `json:"display_name"`
+	Task        string         `json:"task"`
+	Library     string         `json:"library"`
+	License     string         `json:"license"`
+	Tags        []string       `json:"tags"`
+	Metadata    map[string]any `json:"metadata"`
+}
+
+// handleImportProfile creates a model profile (status profile_only).
+func (s *Server) handleImportProfile(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	var req importReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	if req.DisplayName == "" {
+		req.DisplayName = req.ExternalID
+	}
+	p, err := s.store.CreateProfile(store.ModelProfile{
+		WorkspaceID: u.WorkspaceID, SourceType: req.SourceType, SourceURI: req.SourceURI,
+		Provider: req.Provider, ExternalID: req.ExternalID, DisplayName: req.DisplayName,
+		Task: req.Task, Library: req.Library, License: req.License, Tags: req.Tags,
+		Metadata: req.Metadata, Status: "profile_only",
+	})
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	s.audit(r, u.WorkspaceID, u.ID, "model.imported", p.DisplayName, "success", map[string]any{"provider": p.Provider, "external_id": p.ExternalID})
+	writeJSON(w, http.StatusCreated, map[string]any{"profile": profileJSON(*p)})
+}
+
+type attachReq struct {
+	RuntimeID     string `json:"runtimeId"`
+	InstallMode   string `json:"installMode"`
+	ServingEngine string `json:"servingEngine"`
+}
+
+// handleAttachProfile creates an installation row and a model.attach job that
+// streams real progress and persists it.
+func (s *Server) handleAttachProfile(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	pid := r.PathValue("id")
+	p, err := s.store.GetProfile(u.WorkspaceID, pid)
+	if err != nil {
+		writeError(w, http.StatusNotFound, "model profile not found")
+		return
+	}
+	var req attachReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body")
+		return
+	}
+	if req.RuntimeID == "" {
+		writeError(w, http.StatusBadRequest, "runtimeId is required")
+		return
+	}
+	if req.InstallMode == "" {
+		req.InstallMode = "pull_from_source"
+	}
+	inst, err := s.store.CreateInstallation(store.ModelInstallation{
+		WorkspaceID: u.WorkspaceID, ModelProfileID: p.ID, RuntimeID: req.RuntimeID,
+		InstallMode: req.InstallMode, ServingEngine: req.ServingEngine, Status: "queued",
+	})
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	_ = s.store.SetProfileStatus(p.ID, "queued")
+
+	model := p.SourceURI
+	if p.Provider == "Hugging Face" {
+		model = "hf:" + p.ExternalID
+	}
+	payload, _ := json.Marshal(map[string]any{
+		"installation_id": inst.ID, "profile_id": p.ID, "model": model, "provider": p.Provider,
+		"runtime_id": req.RuntimeID, "install_mode": req.InstallMode, "serving_engine": req.ServingEngine,
+	})
+	job, err := s.manager.Create(jobs.CreateRequest{Type: jobs.TypeModelAttach, TTLSeconds: 180, Payload: payload})
+	if err != nil {
+		writeError(w, http.StatusUnprocessableEntity, err.Error())
+		return
+	}
+	_ = s.store.SetInstallationJob(inst.ID, job.ID)
+	s.audit(r, u.WorkspaceID, u.ID, "model.attached", p.DisplayName, "success", map[string]any{"runtime_id": req.RuntimeID, "job_id": job.ID})
+
+	writeJSON(w, http.StatusAccepted, map[string]any{
+		"installation_id": inst.ID,
+		"profile_id":      p.ID,
+		"job_id":          job.ID,
+		"events_url":      "/v1/jobs/" + job.ID + "/events",
+	})
+}
+
+// installationJSON shapes a stored installation for the API.
+func installationJSON(in store.ModelInstallation) map[string]any {
+	return map[string]any{
+		"id": in.ID, "model_profile_id": in.ModelProfileID, "runtime_id": in.RuntimeID,
+		"install_mode": in.InstallMode, "serving_engine": in.ServingEngine,
+		"status": in.Status, "progress": in.Progress, "local_path": in.LocalPath,
+		"endpoint_url": in.EndpointURL, "job_id": in.JobID,
+		"model_name": in.ModelName, "provider": in.Provider, "updated_at": in.UpdatedAt,
+	}
+}
+
+// handleListInstallations lists runtime-cache installations for the workspace.
+func (s *Server) handleListInstallations(w http.ResponseWriter, r *http.Request) {
+	u, ok := s.currentUser(r)
+	if !ok {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+	list, err := s.store.ListInstallations(u.WorkspaceID)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	out := make([]map[string]any, 0, len(list))
+	for _, in := range list {
+		out = append(out, installationJSON(in))
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"installations": out})
+}

api/handlers_platform.go

@@ -0,0 +1,84 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/agent-matrix/matrix-runtime/internal/catalog"
+	"github.com/agent-matrix/matrix-runtime/internal/config"
+	"github.com/agent-matrix/matrix-runtime/internal/runtime"
+	"github.com/agent-matrix/matrix-runtime/internal/security"
+)
+
+// handleListRuntimes returns the real runtimes known to this control surface.
+// Today that is this node (derived from live health + capabilities); joined
+// remote runtimes will appear here once the control-channel lands.
+func (s *Server) handleListRuntimes(w http.ResponseWriter, _ *http.Request) {
+	caps := runtime.BuildCapabilities(s.cfg)
+	running := 0
+	for _, j := range s.manager.List() {
+		if j.Status == "running" || j.Status == "queued" {
+			running++
+		}
+	}
+	self := map[string]any{
+		"id":          s.cfg.EffectiveRuntimeID(),
+		"name":        s.cfg.EffectiveRuntimeID(),
+		"status":      "Online",
+		"statusClass": "green",
+		"mode":        string(s.cfg.Mode),
+		"region":      "local",
+		"caps":        caps.Capabilities,
+		"runtimes":    caps.Runtimes,
+		"jobs":        running,
+		"version":     config.Version,
+		"heartbeat":   "just now",
+		"live":        true,
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"runtimes": []any{self}})
+}
+
+// handleCatalog returns the curated component catalog (real reference data).
+func (s *Server) handleCatalog(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]any{"items": catalog.Items})
+}
+
+// handlePolicies returns the runtime's actual enforced policy — derived from
+// config limits and the security allow/deny lists (not hand-written demo JSON).
+func (s *Server) handlePolicies(w http.ResponseWriter, _ *http.Request) {
+	c := s.cfg
+	policies := []map[string]any{
+		{
+			"name": "Sandbox Policy", "active": true,
+			"body": map[string]any{
+				"max_ttl_seconds":         c.MaxTTLSeconds,
+				"max_concurrent_jobs":     c.MaxConcurrentJobs,
+				"startup_timeout_seconds": c.StartupTimeoutSeconds,
+				"rpc_timeout_seconds":     c.RPCTimeoutSeconds,
+				"max_log_bytes":           c.MaxLogBytes,
+				"allowed_programs":        security.AllowedPrograms(),
+				"allowed_transports":      []string{"stdio"},
+				"reject_raw_secrets":      true,
+			},
+		},
+		{
+			"name": "Command Policy", "active": true,
+			"body": map[string]any{
+				"blocked_tokens":          security.BlockedTokens(),
+				"blocked_shell_operators": []string{"&", "|", ";", "<", ">", "`", "$()", "newline"},
+			},
+		},
+		{
+			"name": "Runtime Policy", "active": true,
+			"body": map[string]any{
+				"mode":                string(c.Mode),
+				"api_token_set":       c.APIToken != "",
+				"matrixshell_enabled": c.MatrixShellEnabled,
+				"rate_limit_rpm":      c.RateLimitRPM,
+				"cloud_url":           c.CloudURL,
+				"outbound_only":       true,
+				"data_dir":            c.DataDir,
+			},
+		},
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"policies": policies})
+}

api/handlers_sandbox.go

@@ -0,0 +1,94 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+)
+
+func (s *Server) handleCreateSandbox(w http.ResponseWriter, r *http.Request) {
+	var req jobs.SandboxRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body: "+err.Error())
+		return
+	}
+	sessionID, j, err := s.manager.CreateSandbox(req)
+	if err != nil {
+		writeError(w, http.StatusUnprocessableEntity, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]any{
+		"session_id": sessionID,
+		"job_id":     j.ID,
+		"status":     "starting",
+		"expires_at": j.Snapshot().ExpiresAt,
+		"events_url": "/v1/sandbox/sessions/" + sessionID + "/events",
+	})
+}
+
+func (s *Server) handleGetSandbox(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("session_id")
+	j, ok := s.manager.SandboxJob(sessionID)
+	if !ok {
+		writeError(w, http.StatusNotFound, "sandbox session not found")
+		return
+	}
+	snap := j.Snapshot()
+	writeJSON(w, http.StatusOK, map[string]any{
+		"session_id": sessionID,
+		"job_id":     j.ID,
+		"status":     snap.Status,
+		"expires_at": snap.ExpiresAt,
+		"result":     snap.Result,
+	})
+}
+
+func (s *Server) handleSandboxEvents(w http.ResponseWriter, r *http.Request) {
+	j, ok := s.manager.SandboxJob(r.PathValue("session_id"))
+	if !ok {
+		writeError(w, http.StatusNotFound, "sandbox session not found")
+		return
+	}
+	streamEvents(w, r, j.Bus())
+}
+
+func (s *Server) handleSandboxTools(w http.ResponseWriter, r *http.Request) {
+	tools, err := s.manager.SandboxTools(r.PathValue("session_id"))
+	if err != nil {
+		writeError(w, http.StatusConflict, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"tools": tools})
+}
+
+func (s *Server) handleSandboxToolCall(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		Name      string         `json:"name"`
+		Arguments map[string]any `json:"arguments"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid JSON body: "+err.Error())
+		return
+	}
+	if req.Name == "" {
+		writeError(w, http.StatusBadRequest, "tool name is required")
+		return
+	}
+	result, err := s.manager.CallSandboxTool(r.Context(), r.PathValue("session_id"), req.Name, req.Arguments)
+	if err != nil {
+		writeError(w, http.StatusConflict, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "result": json.RawMessage(result)})
+}
+
+func (s *Server) handleDeleteSandbox(w http.ResponseWriter, r *http.Request) {
+	j, ok := s.manager.SandboxJob(r.PathValue("session_id"))
+	if !ok {
+		writeError(w, http.StatusNotFound, "sandbox session not found")
+		return
+	}
+	status, _ := s.manager.Cancel(j.ID)
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true, "status": status})
+}

api/handlers_system.go

@@ -0,0 +1,68 @@
+package api
+
+import (
+	"io/fs"
+	"net/http"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+// dirSize sums the size of all regular files under dir (0 when missing).
+func dirSize(dir string) int64 {
+	var total int64
+	_ = filepath.WalkDir(dir, func(_ string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil
+		}
+		if info, err := d.Info(); err == nil {
+			total += info.Size()
+		}
+		return nil
+	})
+	return total
+}
+
+func fileSize(path string) int64 {
+	if info, err := os.Stat(path); err == nil {
+		return info.Size()
+	}
+	return 0
+}
+
+// handleStorage reports disk usage for the runtime's data directory: per-area
+// sizes, the database file, job count, and free space on the filesystem.
+func (s *Server) handleStorage(w http.ResponseWriter, _ *http.Request) {
+	l := s.manager.Layout()
+	areas := map[string]int64{
+		"models":   dirSize(l.HuggingFace()),
+		"mcp":      dirSize(l.MCP()),
+		"agents":   dirSize(l.Agents()),
+		"jobs":     dirSize(l.Jobs()),
+		"logs":     dirSize(l.Logs()),
+		"database": fileSize(s.cfg.DBPath),
+	}
+	var total int64
+	for _, v := range areas {
+		total += v
+	}
+
+	jobsCount := 0
+	if entries, err := os.ReadDir(l.Jobs()); err == nil {
+		jobsCount = len(entries)
+	}
+
+	var freeBytes uint64
+	var fsStat syscall.Statfs_t
+	if err := syscall.Statfs(s.cfg.DataDir, &fsStat); err == nil {
+		freeBytes = fsStat.Bavail * uint64(fsStat.Bsize)
+	}
+
+	writeJSON(w, http.StatusOK, map[string]any{
+		"data_dir":    s.cfg.DataDir,
+		"areas":       areas,
+		"total_bytes": total,
+		"free_bytes":  freeBytes,
+		"jobs_count":  jobsCount,
+	})
+}

api/middleware_auth.go

@@ -0,0 +1,71 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+)
+
+// alwaysOpen is the set of endpoints reachable without any credentials:
+// liveness/readiness/version probes and the capabilities advert.
+func alwaysOpen(path string) bool {
+	switch path {
+	case "/v1/health", "/v1/ready", "/v1/version", "/v1/capabilities":
+		return true
+	}
+	return false
+}
+
+// withAuth authenticates API requests. Two credential types are accepted and
+// either is sufficient:
+//
+//   - a valid user session bearer token (multitenant console), or
+//   - the operator API token (self-hosted single-tenant runtime), when one is
+//     configured via MATRIX_RUNTIME_API_TOKEN.
+//
+// Public probes, the user-auth endpoints, runtime onboarding (which carries its
+// own join/runtime-token auth), and static console assets are always allowed.
+// In production modes a request with no valid credential is rejected
+// (fail-closed); in local-dev it is permitted for convenience.
+func (s *Server) withAuth(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		path := r.URL.Path
+
+		// Public probes + non-API (console assets).
+		if alwaysOpen(path) || !strings.HasPrefix(path, "/v1/") {
+			next.ServeHTTP(w, r)
+			return
+		}
+		// User auth endpoints (login/signup/forgot/reset/verify) and runtime
+		// onboarding (own-token auth) are always reachable.
+		if strings.HasPrefix(path, "/v1/auth/") ||
+			path == "/v1/cloud/runtimes/register" || path == "/v1/cloud/runtimes/heartbeat" {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		token := bearer(r)
+
+		// 1) Valid user session → allow (multitenant console).
+		if s.store != nil && token != "" {
+			if _, err := s.store.UserBySession(token); err == nil {
+				next.ServeHTTP(w, r)
+				return
+			}
+		}
+		// 2) Operator API token configured → require an exact match.
+		if s.cfg.APIToken != "" {
+			if token == s.cfg.APIToken {
+				next.ServeHTTP(w, r)
+				return
+			}
+			writeError(w, http.StatusUnauthorized, "missing or invalid bearer token")
+			return
+		}
+		// 3) No operator token configured: fail-closed in production, allow in dev.
+		if s.cfg.IsProduction() {
+			writeError(w, http.StatusUnauthorized, "authentication required")
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}

api/middleware_ratelimit.go

@@ -0,0 +1,86 @@
+package api
+
+import (
+	"net/http"
+	"strconv"
+	"sync"
+	"time"
+)
+
+// rateLimiter is a tiny per-key fixed-window counter. It is intentionally
+// simple (no external deps): each key gets `limit` requests per 60s window.
+type rateLimiter struct {
+	mu     sync.Mutex
+	limit  int
+	window time.Duration
+	hits   map[string]*window
+}
+
+type window struct {
+	count int
+	reset time.Time
+}
+
+func newRateLimiter(rpm int) *rateLimiter {
+	return &rateLimiter{limit: rpm, window: time.Minute, hits: make(map[string]*window)}
+}
+
+// allow reports whether a request for key is permitted and, if not, how long
+// until the window resets.
+func (rl *rateLimiter) allow(key string) (bool, time.Duration) {
+	now := time.Now()
+	rl.mu.Lock()
+	defer rl.mu.Unlock()
+	w := rl.hits[key]
+	if w == nil || now.After(w.reset) {
+		rl.hits[key] = &window{count: 1, reset: now.Add(rl.window)}
+		// Opportunistically evict stale entries to bound memory.
+		if len(rl.hits) > 4096 {
+			for k, v := range rl.hits {
+				if now.After(v.reset) {
+					delete(rl.hits, k)
+				}
+			}
+		}
+		return true, 0
+	}
+	if w.count >= rl.limit {
+		return false, time.Until(w.reset)
+	}
+	w.count++
+	return true, 0
+}
+
+// rateLimited reports whether a path should be rate limited: state-changing
+// methods on /v1, plus auth endpoints (to slow brute force). Read-only probes
+// and asset fetches are never limited.
+func rateLimited(r *http.Request) bool {
+	if !pathHasPrefix(r.URL.Path, "/v1/") {
+		return false
+	}
+	if r.Method != http.MethodGet && r.Method != http.MethodHead {
+		return true
+	}
+	return false
+}
+
+func pathHasPrefix(p, prefix string) bool {
+	return len(p) >= len(prefix) && p[:len(prefix)] == prefix
+}
+
+// withRateLimit wraps next with per-IP rate limiting on write/auth endpoints.
+func (s *Server) withRateLimit(next http.Handler) http.Handler {
+	if s.cfg.RateLimitRPM <= 0 || s.limiter == nil {
+		return next
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if rateLimited(r) {
+			if ok, retry := s.limiter.allow(clientIP(r)); !ok {
+				w.Header().Set("Retry-After", strconv.Itoa(int(retry.Seconds())+1))
+				writeError(w, http.StatusTooManyRequests, "rate limit exceeded — slow down and retry")
+				return
+			}
+		}
+		next.ServeHTTP(w, r)
+	})
+}

api/models_test.go

@@ -0,0 +1,79 @@
+package api
+
+import (
+	"net/http"
+	"testing"
+)
+
+// authedToken signs up a user on the given server and returns its session token.
+func authedToken(t *testing.T, srv *Server) string {
+	t.Helper()
+	rec, body := do(t, srv, http.MethodPost, "/v1/auth/signup", "", `{"name":"Mo","email":"mo@acme.io","password":"hunter2x"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("signup %d", rec.Code)
+	}
+	return body["token"].(string)
+}
+
+func TestModelProfilesRequireAuth(t *testing.T) {
+	srv := authServer(t)
+	rec, _ := do(t, srv, http.MethodGet, "/v1/model-profiles", "", "")
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 without auth, got %d", rec.Code)
+	}
+}
+
+func TestImportListAttachProfile(t *testing.T) {
+	srv := authServer(t)
+	tok := authedToken(t, srv)
+
+	// import a profile
+	rec, body := do(t, srv, http.MethodPost, "/v1/model-profiles", tok,
+		`{"source_type":"huggingface","provider":"Hugging Face","external_id":"deepseek-ai/DeepSeek-V3","display_name":"deepseek-ai/DeepSeek-V3","task":"text-generation"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("import status %d: %v", rec.Code, body)
+	}
+	prof := body["profile"].(map[string]any)
+	if prof["status"] != "profile_only" {
+		t.Errorf("status = %v", prof["status"])
+	}
+	pid := prof["id"].(string)
+
+	// list profiles
+	rec, body = do(t, srv, http.MethodGet, "/v1/model-profiles", tok, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("list status %d", rec.Code)
+	}
+	if len(body["profiles"].([]any)) != 1 {
+		t.Fatalf("expected 1 profile, got %v", body["profiles"])
+	}
+
+	// attach -> creates installation + a job
+	rec, body = do(t, srv, http.MethodPost, "/v1/model-profiles/"+pid+"/attach", tok,
+		`{"runtimeId":"acme-prod-runtime","installMode":"pull_from_source","servingEngine":"vLLM"}`)
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("attach status %d: %v", rec.Code, body)
+	}
+	if body["job_id"] == nil || body["installation_id"] == nil {
+		t.Fatalf("attach missing ids: %v", body)
+	}
+
+	// installation should now appear in the runtime cache
+	rec, body = do(t, srv, http.MethodGet, "/v1/model-installations", tok, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("installations status %d", rec.Code)
+	}
+	ins := body["installations"].([]any)
+	if len(ins) != 1 {
+		t.Fatalf("expected 1 installation, got %d", len(ins))
+	}
+	got := ins[0].(map[string]any)
+	if got["runtime_id"] != "acme-prod-runtime" || got["serving_engine"] != "vLLM" {
+		t.Errorf("installation fields: %v", got)
+	}
+
+	// cancel the background job so it doesn't linger past the test
+	if id, _ := got["job_id"].(string); id != "" {
+		_, _ = do(t, srv, http.MethodDelete, "/v1/jobs/"+id, tok, "")
+	}
+}

api/openapi.go

@@ -0,0 +1,83 @@
+package api
+
+import (
+	_ "embed"
+	"net/http"
+)
+
+//go:embed openapi.yaml
+var openAPISpec []byte
+
+// handleOpenAPISpec serves the raw OpenAPI document.
+func (s *Server) handleOpenAPISpec(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/yaml")
+	_, _ = w.Write(openAPISpec)
+}
+
+// docsHTML is a self-contained API docs viewer. It loads Redoc from a CDN when
+// online, but falls back to a readable, dependency-free rendering of
+// /openapi.yaml so the page works air-gapped too.
+const docsHTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <title>Matrix Runtime API — Docs</title>
+  <style>
+    body{margin:0;font-family:ui-sans-serif,system-ui,Segoe UI,Roboto,Arial;background:#0b0f14;color:#e6edf3}
+    header{padding:18px 24px;border-bottom:1px solid #1b2430;display:flex;align-items:center;gap:12px}
+    header h1{font-size:16px;margin:0;font-weight:700}
+    header .v{font-family:ui-monospace,monospace;font-size:11px;color:#7d8da1;border:1px solid #1b2430;border-radius:6px;padding:2px 8px}
+    a{color:#5ad19a;text-decoration:none}
+    #fallback{max-width:900px;margin:0 auto;padding:24px}
+    .op{border:1px solid #1b2430;border-radius:10px;margin:10px 0;overflow:hidden}
+    .op .h{display:flex;align-items:center;gap:10px;padding:11px 14px;background:#0f1620}
+    .m{font-family:ui-monospace,monospace;font-size:11px;font-weight:700;padding:2px 8px;border-radius:5px;text-transform:uppercase}
+    .get{background:#10331f;color:#5ad19a}.post{background:#102a44;color:#6db3f2}
+    .put{background:#3a2f10;color:#e8c468}.delete{background:#3a1414;color:#f2796d}
+    .path{font-family:ui-monospace,monospace;font-size:13px}
+    .sum{color:#9fb0c3;font-size:12.5px;padding:8px 14px}
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Matrix Runtime API</h1><span class="v" id="ver">openapi</span>
+    <span style="flex:1"></span><a href="/openapi.yaml">openapi.yaml ↗</a>
+  </header>
+  <redoc spec-url="/openapi.yaml"></redoc>
+  <div id="fallback"><p style="color:#7d8da1">Rendering API reference…</p></div>
+  <script src="https://cdn.redocly.com/redoc/latest/bundles/redoc.standalone.js"
+          onload="document.getElementById('fallback').style.display='none'"
+          onerror="renderFallback()"></script>
+  <script>
+    function renderFallback(){
+      var rd=document.querySelector('redoc'); if(rd) rd.remove();
+      fetch('/openapi.yaml').then(function(r){return r.text()}).then(function(t){
+        // Minimal YAML-ish scan: list "  /path:" then "    get:" with summary.
+        var lines=t.split('\n'), out=[], path=null, method=null, mLine=-1;
+        var box=document.getElementById('fallback'); box.innerHTML='';
+        var verEl=document.getElementById('ver');
+        for(var i=0;i<lines.length;i++){
+          var ln=lines[i];
+          var pm=ln.match(/^  (\/[^:]+):\s*$/); if(pm){path=pm[1];continue;}
+          var mm=ln.match(/^    (get|post|put|delete|patch):\s*$/);
+          if(mm&&path){method=mm[1];
+            var sum=''; for(var j=i+1;j<Math.min(i+6,lines.length);j++){var sm=lines[j].match(/^      summary:\s*(.+)$/); if(sm){sum=sm[1];break;}}
+            var div=document.createElement('div'); div.className='op';
+            div.innerHTML='<div class="h"><span class="m '+method+'">'+method+'</span><span class="path">'+path+'</span></div>'+(sum?'<div class="sum">'+sum+'</div>':'');
+            box.appendChild(div);
+          }
+          var vm=ln.match(/^  version:\s*(.+)$/); if(vm&&verEl) verEl.textContent='v'+vm[1].trim();
+        }
+        if(!box.children.length) box.innerHTML='<p>See <a href="/openapi.yaml">/openapi.yaml</a>.</p>';
+      });
+    }
+  </script>
+</body>
+</html>`
+
+// handleDocs serves the API docs viewer.
+func (s *Server) handleDocs(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	_, _ = w.Write([]byte(docsHTML))
+}

api/openapi.yaml

@@ -0,0 +1,651 @@
+openapi: 3.0.3
+info:
+  title: Matrix Runtime API
+  description: |
+    Execution plane for Matrix Cloud. Runs MCP sandboxes, inspects Hugging Face
+    models and (in future) agents/tools. Sandboxes are a thin alias over jobs of
+    type mcp.test.
+  version: 0.2.0
+servers:
+  - url: http://localhost:8080
+    description: Local
+security:
+  - bearerAuth: []
+  - {}
+paths:
+  /v1/health:
+    get:
+      summary: Liveness and identity
+      security: []
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status: { type: string, example: ok }
+                  runtime_id: { type: string, example: rt_local }
+                  mode: { type: string, example: local-dev }
+                  version: { type: string, example: 0.1.0 }
+  /v1/capabilities:
+    get:
+      summary: Runtime capabilities and limits
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Capabilities"
+  /v1/ready:
+    get:
+      summary: Readiness probe (checks + warnings)
+      security: []
+      responses:
+        "200": { description: Ready }
+        "503": { description: Not ready (a core check failed) }
+  /v1/version:
+    get:
+      summary: Build and version metadata
+      security: []
+      responses:
+        "200": { description: OK }
+  /v1/system/storage:
+    get:
+      summary: Data-directory storage usage and free disk
+      responses:
+        "200": { description: OK }
+  /v1/policies:
+    get:
+      summary: Enforced guardrails (limits + command allow/deny lists)
+      responses:
+        "200": { description: OK }
+  /v1/runtimes:
+    get:
+      summary: Runtimes connected to this control surface
+      responses:
+        "200": { description: OK }
+  /v1/catalog:
+    get:
+      summary: Curated catalog of MCP servers and models
+      responses:
+        "200": { description: OK }
+  /v1/auth/forgot:
+    post:
+      summary: Request a password-reset email (always 200)
+      security: []
+      responses:
+        "200": { description: OK }
+  /v1/auth/reset:
+    post:
+      summary: Set a new password from a reset token
+      security: []
+      responses:
+        "200": { description: OK }
+        "400": { description: Invalid or expired token }
+  /v1/auth/verify:
+    post:
+      summary: Confirm an email-verification token
+      security: []
+      responses:
+        "200": { description: OK }
+  /v1/matrixshell/status:
+    get:
+      summary: MatrixShell install status (403 when disabled)
+      responses:
+        "200": { description: OK }
+        "403": { description: MatrixShell disabled }
+  /v1/matrixshell/install:
+    post:
+      summary: Install MatrixShell into the local sandbox (job)
+      responses:
+        "202": { description: Job accepted }
+        "403": { description: MatrixShell disabled }
+  /v1/matrixshell/exec:
+    post:
+      summary: Run a command in the MatrixShell sandbox (denylisted)
+      responses:
+        "200": { description: OK }
+        "403": { description: Disabled or blocked by denylist }
+  /v1/cloud/runtimes:
+    get:
+      summary: List the workspace's registered runtimes
+      responses:
+        "200": { description: OK }
+  /v1/cloud/runtimes/register:
+    post:
+      summary: Register a runtime using a workspace join token
+      security: []
+      responses:
+        "201": { description: Registered (returns a runtime token) }
+        "401": { description: Invalid join token }
+  /v1/cloud/runtimes/heartbeat:
+    post:
+      summary: Runtime liveness heartbeat (runtime-token auth)
+      security: []
+      responses:
+        "200": { description: OK }
+        "401": { description: Invalid runtime token }
+  /v1/cloud/join-tokens:
+    get:
+      summary: List active join tokens
+      responses:
+        "200": { description: OK }
+    post:
+      summary: Mint a single/limited-use join token
+      responses:
+        "201": { description: Created (secret shown once) }
+  /v1/cloud/providers:
+    get:
+      summary: List BYO provider credentials (hints only)
+      responses:
+        "200": { description: OK }
+    post:
+      summary: Store a BYO provider token (encrypted at rest)
+      responses:
+        "201": { description: Created }
+  /v1/cloud/usage:
+    get:
+      summary: 30-day usage metering by kind
+      responses:
+        "200": { description: OK }
+  /v1/cloud/audit:
+    get:
+      summary: Recent audit events for the workspace
+      responses:
+        "200": { description: OK }
+  /v1/auth/signup:
+    post:
+      summary: Create a workspace + owner account (multitenant)
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name, email, password]
+              properties:
+                name: { type: string }
+                email: { type: string, format: email }
+                password: { type: string, minLength: 6 }
+                workspace: { type: string }
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AuthResult" }
+        "409": { $ref: "#/components/responses/Error" }
+  /v1/auth/login:
+    post:
+      summary: Authenticate and start a session
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, password]
+              properties:
+                email: { type: string, format: email }
+                password: { type: string }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AuthResult" }
+        "401": { $ref: "#/components/responses/Error" }
+  /v1/auth/me:
+    get:
+      summary: Current authenticated user
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user: { $ref: "#/components/schemas/AuthUser" }
+        "401": { $ref: "#/components/responses/Error" }
+  /v1/auth/logout:
+    post:
+      summary: End the current session (?all=true ends every session)
+      responses:
+        "200": { description: OK }
+  /v1/model-sources/huggingface/search:
+    get:
+      summary: Search Hugging Face models (server-side proxy, sorted by downloads)
+      security: []
+      parameters:
+        - { name: q, in: query, schema: { type: string } }
+        - { name: task, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer } }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  live: { type: boolean }
+                  items: { type: array, items: { type: object } }
+  /v1/model-sources/resolve:
+    post:
+      summary: Resolve a source into a model-profile preview (HF resolved live)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sourceType: { type: string, example: huggingface }
+                externalId: { type: string }
+                model: { type: string }
+                sourceUri: { type: string }
+                provider: { type: string }
+                path: { type: string }
+                branch: { type: string }
+                private: { type: boolean }
+      responses:
+        "200": { description: Profile preview }
+        "502": { $ref: "#/components/responses/Error" }
+  /v1/model-profiles:
+    get:
+      summary: List model profiles for the workspace
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  profiles: { type: array, items: { $ref: "#/components/schemas/ModelProfile" } }
+        "401": { $ref: "#/components/responses/Error" }
+    post:
+      summary: Import (create) a model profile
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ModelProfileImport" }
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  profile: { $ref: "#/components/schemas/ModelProfile" }
+        "401": { $ref: "#/components/responses/Error" }
+  /v1/model-profiles/{id}/attach:
+    post:
+      summary: Attach/install a profile onto a runtime (creates a model.attach job)
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [runtimeId]
+              properties:
+                runtimeId: { type: string }
+                installMode: { type: string, enum: [pull_from_source, mount_volume, external_endpoint] }
+                servingEngine: { type: string, example: vLLM }
+      responses:
+        "202":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  installation_id: { type: string }
+                  profile_id: { type: string }
+                  job_id: { type: string }
+                  events_url: { type: string }
+        "404": { $ref: "#/components/responses/Error" }
+  /v1/model-installations:
+    get:
+      summary: List runtime-cache installations for the workspace (with progress)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  installations: { type: array, items: { $ref: "#/components/schemas/ModelInstallation" } }
+        "401": { $ref: "#/components/responses/Error" }
+  /v1/jobs:
+    get:
+      summary: List jobs (newest first)
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  jobs:
+                    type: array
+                    items: { $ref: "#/components/schemas/Job" }
+    post:
+      summary: Create a job
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateJobRequest"
+      responses:
+        "202":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateJobResponse"
+        "400": { $ref: "#/components/responses/Error" }
+        "422": { $ref: "#/components/responses/Error" }
+  /v1/jobs/{job_id}:
+    parameters:
+      - $ref: "#/components/parameters/JobID"
+    get:
+      summary: Read a job
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "404": { $ref: "#/components/responses/Error" }
+    delete:
+      summary: Cancel/delete a job
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok: { type: boolean }
+                  status: { type: string }
+        "404": { $ref: "#/components/responses/Error" }
+  /v1/jobs/{job_id}/events:
+    parameters:
+      - $ref: "#/components/parameters/JobID"
+    get:
+      summary: Stream job events (SSE)
+      responses:
+        "200":
+          description: text/event-stream of Event objects
+          content:
+            text/event-stream:
+              schema:
+                $ref: "#/components/schemas/Event"
+  /v1/sandbox/sessions:
+    post:
+      summary: Create a sandbox session (alias over mcp.test)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SandboxRequest"
+      responses:
+        "202":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SandboxResponse"
+  /v1/sandbox/sessions/{session_id}:
+    parameters:
+      - $ref: "#/components/parameters/SessionID"
+    get:
+      summary: Read a sandbox session
+      responses:
+        "200": { description: OK }
+        "404": { $ref: "#/components/responses/Error" }
+    delete:
+      summary: Delete a sandbox session
+      responses:
+        "200": { description: OK }
+        "404": { $ref: "#/components/responses/Error" }
+  /v1/sandbox/sessions/{session_id}/events:
+    parameters:
+      - $ref: "#/components/parameters/SessionID"
+    get:
+      summary: Stream sandbox events (SSE)
+      responses:
+        "200":
+          description: text/event-stream of Event objects
+  /v1/sandbox/sessions/{session_id}/tools:
+    parameters:
+      - $ref: "#/components/parameters/SessionID"
+    get:
+      summary: List tools advertised by the sandbox's MCP server
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tools:
+                    type: array
+                    items: { $ref: "#/components/schemas/Tool" }
+        "409": { $ref: "#/components/responses/Error" }
+  /v1/sandbox/sessions/{session_id}/tools/call:
+    parameters:
+      - $ref: "#/components/parameters/SessionID"
+    post:
+      summary: Call a tool in the sandbox
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name]
+              properties:
+                name: { type: string }
+                arguments: { type: object, additionalProperties: true }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok: { type: boolean }
+                  result: { type: object, additionalProperties: true }
+        "409": { $ref: "#/components/responses/Error" }
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    JobID:
+      name: job_id
+      in: path
+      required: true
+      schema: { type: string }
+    SessionID:
+      name: session_id
+      in: path
+      required: true
+      schema: { type: string }
+  responses:
+    Error:
+      description: Error
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error: { type: string }
+              status: { type: integer }
+  schemas:
+    ModelProfile:
+      type: object
+      properties:
+        id: { type: string }
+        source_type: { type: string }
+        source_uri: { type: string }
+        provider: { type: string }
+        external_id: { type: string }
+        display_name: { type: string }
+        task: { type: string }
+        library: { type: string }
+        license: { type: string }
+        tags: { type: array, items: { type: string } }
+        status:
+          type: string
+          enum: [profile_only, queued, downloading, installed, attached, ready, failed, gated, incompatible]
+    ModelProfileImport:
+      type: object
+      properties:
+        source_type: { type: string }
+        source_uri: { type: string }
+        provider: { type: string }
+        external_id: { type: string }
+        display_name: { type: string }
+        task: { type: string }
+        library: { type: string }
+        license: { type: string }
+        tags: { type: array, items: { type: string } }
+        metadata: { type: object, additionalProperties: true }
+    ModelInstallation:
+      type: object
+      properties:
+        id: { type: string }
+        model_profile_id: { type: string }
+        runtime_id: { type: string }
+        install_mode: { type: string }
+        serving_engine: { type: string }
+        status:
+          type: string
+          enum: [queued, checking, downloading, verifying, attached, ready, failed]
+        progress: { type: integer }
+        local_path: { type: string }
+        model_name: { type: string }
+        provider: { type: string }
+        job_id: { type: string }
+    AuthUser:
+      type: object
+      properties:
+        id: { type: string }
+        name: { type: string }
+        email: { type: string }
+        role: { type: string, example: Owner }
+        workspace: { type: string }
+        workspace_slug: { type: string }
+        workspace_id: { type: string }
+    AuthResult:
+      type: object
+      properties:
+        token: { type: string, description: Session bearer token }
+        user: { $ref: "#/components/schemas/AuthUser" }
+    Capabilities:
+      type: object
+      properties:
+        capabilities:
+          type: array
+          items: { type: string }
+          example: [mcp.test, mcp.run, model.inspect, model.pull, agent.run, tool.run]
+        runtimes:
+          type: object
+          properties:
+            node: { type: boolean }
+            python: { type: boolean }
+            ollama: { type: boolean }
+            vllm: { type: boolean }
+            sglang: { type: boolean }
+        limits:
+          type: object
+          properties:
+            max_ttl_seconds: { type: integer }
+            max_concurrent_jobs: { type: integer }
+    CreateJobRequest:
+      type: object
+      required: [type]
+      properties:
+        type:
+          type: string
+          enum: [mcp.test, mcp.run, model.inspect, model.pull, model.preload, agent.run, tool.run]
+        ttl_seconds: { type: integer, example: 600 }
+        payload:
+          type: object
+          additionalProperties: true
+    CreateJobResponse:
+      type: object
+      properties:
+        job_id: { type: string }
+        status: { type: string }
+        events_url: { type: string }
+    Job:
+      type: object
+      properties:
+        job_id: { type: string }
+        type: { type: string }
+        status:
+          type: string
+          enum: [queued, running, complete, error, expired, cancelled]
+        created_at: { type: string, format: date-time }
+        expires_at: { type: string, format: date-time }
+        result: { nullable: true }
+        error: { type: string }
+    Event:
+      type: object
+      properties:
+        step: { type: string }
+        status:
+          type: string
+          enum: [queued, start, ok, error, running, expired, cancelled, complete]
+        message: { type: string }
+        data: { type: object, additionalProperties: true }
+    SandboxRequest:
+      type: object
+      required: [start_command]
+      properties:
+        entity_id: { type: string }
+        ttl_seconds: { type: integer }
+        runtime: { type: string, example: node }
+        transport: { type: string, example: stdio }
+        start_command: { type: string }
+        env:
+          type: object
+          additionalProperties: { type: string }
+    SandboxResponse:
+      type: object
+      properties:
+        session_id: { type: string }
+        job_id: { type: string }
+        status: { type: string }
+        expires_at: { type: string, format: date-time }
+        events_url: { type: string }
+    Tool:
+      type: object
+      properties:
+        name: { type: string }
+        description: { type: string }
+        input_schema: { type: object, additionalProperties: true }

api/production_test.go

@@ -0,0 +1,160 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/agent-matrix/matrix-runtime/internal/config"
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+)
+
+func get(t *testing.T, srv *Server, path, token string) (*httptest.ResponseRecorder, map[string]any) {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	rec := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(rec, req)
+	var out map[string]any
+	_ = json.Unmarshal(rec.Body.Bytes(), &out)
+	return rec, out
+}
+
+func TestVersionAndReady(t *testing.T) {
+	srv := testServer(t)
+	rec, body := get(t, srv, "/v1/version", "")
+	if rec.Code != http.StatusOK || body["name"] != "matrix-runtime" {
+		t.Fatalf("version = %d %v", rec.Code, body)
+	}
+	rec, body = get(t, srv, "/v1/ready", "")
+	// No store in testServer → not ready, with a store_unavailable warning.
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("ready status = %d, want 503 (no store)", rec.Code)
+	}
+	if _, ok := body["checks"].(map[string]any); !ok {
+		t.Fatalf("ready missing checks: %v", body)
+	}
+	if body["ready"] != false {
+		t.Errorf("ready = %v, want false", body["ready"])
+	}
+}
+
+func TestReadyHealthyWithStore(t *testing.T) {
+	srv := authServer(t) // has a store + temp data dir, local-dev
+	rec, body := get(t, srv, "/v1/ready", "")
+	if rec.Code != http.StatusOK || body["ready"] != true {
+		t.Fatalf("ready = %d %v", rec.Code, body)
+	}
+	// local-dev should surface a local_dev_mode warning.
+	ws, _ := body["warnings"].([]any)
+	found := false
+	for _, w := range ws {
+		if m, ok := w.(map[string]any); ok && m["code"] == "local_dev_mode" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected local_dev_mode warning, got %v", ws)
+	}
+}
+
+func TestProductionFailsClosedWithoutCreds(t *testing.T) {
+	cfg := config.Defaults(config.ModeCustomerAgent) // production mode
+	cfg.DataDir = t.TempDir()
+	srv := NewServer(cfg, jobs.NewManager(cfg), nil)
+
+	// Probes stay public.
+	if rec, _ := get(t, srv, "/v1/health", ""); rec.Code != http.StatusOK {
+		t.Fatalf("health should be public, got %d", rec.Code)
+	}
+	if rec, _ := get(t, srv, "/v1/version", ""); rec.Code != http.StatusOK {
+		t.Fatalf("version should be public, got %d", rec.Code)
+	}
+	// A protected endpoint with no creds is rejected (fail-closed).
+	if rec, _ := get(t, srv, "/v1/jobs", ""); rec.Code != http.StatusUnauthorized {
+		t.Fatalf("protected endpoint = %d, want 401", rec.Code)
+	}
+}
+
+func TestOperatorAPITokenGate(t *testing.T) {
+	cfg := config.Defaults(config.ModeCustomerAgent)
+	cfg.DataDir = t.TempDir()
+	cfg.APIToken = "s3cret-operator-token"
+	srv := NewServer(cfg, jobs.NewManager(cfg), nil)
+
+	if rec, _ := get(t, srv, "/v1/jobs", ""); rec.Code != http.StatusUnauthorized {
+		t.Fatalf("no token = %d, want 401", rec.Code)
+	}
+	if rec, _ := get(t, srv, "/v1/jobs", "wrong"); rec.Code != http.StatusUnauthorized {
+		t.Fatalf("wrong token = %d, want 401", rec.Code)
+	}
+	if rec, _ := get(t, srv, "/v1/jobs", "s3cret-operator-token"); rec.Code == http.StatusUnauthorized {
+		t.Fatalf("correct operator token should pass the auth gate, got 401")
+	}
+}
+
+func TestMatrixShellGate(t *testing.T) {
+	// Production mode → MatrixShell disabled by default → 403.
+	cfg := config.Defaults(config.ModeCustomerAgent)
+	cfg.DataDir = t.TempDir()
+	cfg.APIToken = "tok"
+	srv := NewServer(cfg, jobs.NewManager(cfg), nil)
+	if rec, _ := get(t, srv, "/v1/matrixshell/status", "tok"); rec.Code != http.StatusForbidden {
+		t.Fatalf("matrixshell (prod, disabled) = %d, want 403", rec.Code)
+	}
+
+	// Explicitly enabled → reachable (200).
+	cfg2 := config.Defaults(config.ModeCustomerAgent)
+	cfg2.DataDir = t.TempDir()
+	cfg2.APIToken = "tok"
+	cfg2.MatrixShellEnabled = true
+	srv2 := NewServer(cfg2, jobs.NewManager(cfg2), nil)
+	if rec, _ := get(t, srv2, "/v1/matrixshell/status", "tok"); rec.Code == http.StatusForbidden {
+		t.Fatalf("matrixshell (enabled) should not be 403")
+	}
+}
+
+func TestStorageEndpoint(t *testing.T) {
+	srv := authServer(t) // has store + temp data dir, local-dev (no auth required)
+	rec, body := get(t, srv, "/v1/system/storage", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("storage = %d", rec.Code)
+	}
+	if _, ok := body["areas"].(map[string]any); !ok {
+		t.Fatalf("missing areas: %v", body)
+	}
+	if _, ok := body["total_bytes"]; !ok {
+		t.Errorf("missing total_bytes")
+	}
+}
+
+func TestRateLimit(t *testing.T) {
+	cfg := config.Defaults(config.ModeLocalDev)
+	cfg.DataDir = t.TempDir()
+	cfg.RateLimitRPM = 3
+	srv := NewServer(cfg, jobs.NewManager(cfg), nil)
+
+	// GET probes are never limited.
+	for i := 0; i < 10; i++ {
+		if rec, _ := get(t, srv, "/v1/health", ""); rec.Code == http.StatusTooManyRequests {
+			t.Fatalf("GET health should never be rate limited")
+		}
+	}
+	// POSTs are limited after RateLimitRPM within the window.
+	limited := false
+	for i := 0; i < 6; i++ {
+		req := httptest.NewRequest(http.MethodPost, "/v1/auth/login", jsonBody(`{"email":"a@b.io","password":"x"}`))
+		rec := httptest.NewRecorder()
+		srv.Handler().ServeHTTP(rec, req)
+		if rec.Code == http.StatusTooManyRequests {
+			limited = true
+			break
+		}
+	}
+	if !limited {
+		t.Errorf("expected a 429 after exceeding the rate limit")
+	}
+}

api/server.go

@@ -0,0 +1,180 @@
+// Package api exposes the matrix-runtime HTTP API: health, capabilities, jobs
+// and the sandbox compatibility aliases used by MatrixHub.
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/agent-matrix/matrix-runtime/internal/config"
+	"github.com/agent-matrix/matrix-runtime/internal/email"
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+	"github.com/agent-matrix/matrix-runtime/internal/store"
+	"github.com/agent-matrix/matrix-runtime/web"
+)
+
+// Server wires the job manager, user store, email sender and config to routes.
+type Server struct {
+	cfg     *config.Config
+	manager *jobs.Manager
+	store   *store.Store
+	email   *email.Sender
+	limiter *rateLimiter
+}
+
+// NewServer builds a Server. store may be nil if the user database could not be
+// opened; auth endpoints then return 503.
+func NewServer(cfg *config.Config, mgr *jobs.Manager, st *store.Store) *Server {
+	s := &Server{cfg: cfg, manager: mgr, store: st, email: email.NewFromEnv()}
+	if cfg.RateLimitRPM > 0 {
+		s.limiter = newRateLimiter(cfg.RateLimitRPM)
+	}
+	return s
+}
+
+// Handler returns the configured HTTP handler with all routes registered.
+func (s *Server) Handler() http.Handler {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("GET /v1/health", s.handleHealth)
+	mux.HandleFunc("GET /v1/ready", s.handleReady)
+	mux.HandleFunc("GET /v1/version", s.handleVersion)
+	mux.HandleFunc("GET /v1/capabilities", s.handleCapabilities)
+	mux.HandleFunc("GET /v1/runtimes", s.handleListRuntimes)
+	mux.HandleFunc("GET /v1/catalog", s.handleCatalog)
+	mux.HandleFunc("GET /v1/policies", s.handlePolicies)
+
+	// Multitenant auth (users + sessions, SQLite or Postgres/Neon).
+	mux.HandleFunc("POST /v1/auth/signup", s.handleSignup)
+	mux.HandleFunc("POST /v1/auth/login", s.handleLogin)
+	mux.HandleFunc("GET /v1/auth/me", s.handleMe)
+	mux.HandleFunc("POST /v1/auth/logout", s.handleLogout)
+	// Password recovery + email verification (delivered via Resend).
+	mux.HandleFunc("POST /v1/auth/forgot", s.handleForgotPassword)
+	mux.HandleFunc("POST /v1/auth/reset", s.handleResetPassword)
+	mux.HandleFunc("POST /v1/auth/verify", s.handleVerifyEmail)
+
+	// Hosted control plane: runtimes, join tokens, BYO provider creds, usage.
+	mux.HandleFunc("GET /v1/cloud/runtimes", s.handleCloudListRuntimes)
+	mux.HandleFunc("POST /v1/cloud/runtimes/register", s.handleCloudRegisterRuntime)
+	mux.HandleFunc("POST /v1/cloud/runtimes/heartbeat", s.handleCloudHeartbeat)
+	mux.HandleFunc("GET /v1/cloud/join-tokens", s.handleCloudListJoinTokens)
+	mux.HandleFunc("POST /v1/cloud/join-tokens", s.handleCloudMintJoinToken)
+	mux.HandleFunc("GET /v1/cloud/providers", s.handleCloudListProviders)
+	mux.HandleFunc("POST /v1/cloud/providers", s.handleCloudSetProvider)
+	mux.HandleFunc("GET /v1/cloud/usage", s.handleCloudUsage)
+	mux.HandleFunc("GET /v1/cloud/audit", s.handleCloudAudit)
+
+	mux.HandleFunc("GET /v1/model-sources/huggingface/search", s.handleHFSearch)
+	mux.HandleFunc("POST /v1/model-sources/resolve", s.handleResolveSource)
+	mux.HandleFunc("GET /v1/model-profiles", s.handleListProfiles)
+	mux.HandleFunc("POST /v1/model-profiles", s.handleImportProfile)
+	mux.HandleFunc("POST /v1/model-profiles/{id}/attach", s.handleAttachProfile)
+	mux.HandleFunc("GET /v1/model-installations", s.handleListInstallations)
+
+	// MatrixShell — real local Python sandbox (install / status / exec).
+	mux.HandleFunc("GET /v1/matrixshell/status", s.handleMatrixShellStatus)
+	mux.HandleFunc("POST /v1/matrixshell/install", s.handleMatrixShellInstall)
+	mux.HandleFunc("POST /v1/matrixshell/exec", s.handleMatrixShellExec)
+
+	mux.HandleFunc("POST /v1/jobs", s.handleCreateJob)
+	mux.HandleFunc("GET /v1/jobs", s.handleListJobs)
+	mux.HandleFunc("GET /v1/jobs/{job_id}", s.handleGetJob)
+	mux.HandleFunc("GET /v1/jobs/{job_id}/events", s.handleJobEvents)
+	mux.HandleFunc("DELETE /v1/jobs/{job_id}", s.handleDeleteJob)
+
+	mux.HandleFunc("POST /v1/sandbox/sessions", s.handleCreateSandbox)
+	mux.HandleFunc("GET /v1/sandbox/sessions/{session_id}", s.handleGetSandbox)
+	mux.HandleFunc("GET /v1/sandbox/sessions/{session_id}/events", s.handleSandboxEvents)
+	mux.HandleFunc("GET /v1/sandbox/sessions/{session_id}/tools", s.handleSandboxTools)
+	mux.HandleFunc("POST /v1/sandbox/sessions/{session_id}/tools/call", s.handleSandboxToolCall)
+	mux.HandleFunc("DELETE /v1/sandbox/sessions/{session_id}", s.handleDeleteSandbox)
+
+	// API docs (OpenAPI spec + a self-contained viewer), public.
+	mux.HandleFunc("GET /openapi.yaml", s.handleOpenAPISpec)
+	mux.HandleFunc("GET /docs", s.handleDocs)
+
+	// System: storage usage.
+	mux.HandleFunc("GET /v1/system/storage", s.handleStorage)
+
+	// Enterprise console (static SPA) served from the embedded web assets.
+	mux.Handle("/", s.consoleHandler())
+
+	// Outermost: rate limiting (protects auth + writes); then auth.
+	return s.withRateLimit(s.withAuth(mux))
+}
+
+// consoleHandler serves the embedded console, falling back to index.html for
+// client-side routes (single-page app).
+func (s *Server) consoleHandler() http.Handler {
+	assets := web.Static()
+	fileServer := http.FileServer(http.FS(assets))
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Never let the SPA shadow the API namespace.
+		if strings.HasPrefix(r.URL.Path, "/v1/") {
+			http.NotFound(w, r)
+			return
+		}
+		// Serve the asset when it exists; otherwise hand back the app shell.
+		p := strings.TrimPrefix(r.URL.Path, "/")
+		if p == "" {
+			p = "index.html"
+		}
+		if f, err := assets.Open(p); err == nil {
+			_ = f.Close()
+			fileServer.ServeHTTP(w, r)
+			return
+		}
+		r2 := r.Clone(r.Context())
+		r2.URL.Path = "/"
+		fileServer.ServeHTTP(w, r2)
+	})
+}
+
+// Run starts the HTTP server and blocks until ctx is cancelled, then performs
+// a graceful shutdown.
+// Run binds addr and serves until ctx is cancelled. Kept for compatibility;
+// prefer Serve with a pre-bound listener (e.g. from a port-fallback search).
+func (s *Server) Run(ctx context.Context, addr string) error {
+	ln, err := net.Listen("tcp", addr)
+	if err != nil {
+		return err
+	}
+	return s.Serve(ctx, ln)
+}
+
+// Serve serves HTTP on the given listener until ctx is cancelled, then performs
+// a graceful shutdown.
+func (s *Server) Serve(ctx context.Context, ln net.Listener) error {
+	srv := &http.Server{
+		Handler:           s.Handler(),
+		ReadHeaderTimeout: 10 * time.Second,
+	}
+	errCh := make(chan error, 1)
+	go func() { errCh <- srv.Serve(ln) }()
+
+	select {
+	case err := <-errCh:
+		return err
+	case <-ctx.Done():
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		return srv.Shutdown(shutdownCtx)
+	}
+}
+
+// writeJSON serialises v as JSON with the given status code.
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+// writeError writes a structured JSON error.
+func writeError(w http.ResponseWriter, status int, msg string) {
+	writeJSON(w, status, map[string]any{"error": msg, "status": status})
+}

api/server_test.go

@@ -0,0 +1,88 @@
+package api
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/agent-matrix/matrix-runtime/internal/config"
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+)
+
+func jsonBody(s string) io.Reader { return strings.NewReader(s) }
+
+func testServer(t *testing.T) *Server {
+	t.Helper()
+	cfg := config.Defaults(config.ModeLocalDev)
+	cfg.DataDir = t.TempDir()
+	return NewServer(cfg, jobs.NewManager(cfg), nil)
+}
+
+func TestHealth(t *testing.T) {
+	srv := testServer(t)
+	req := httptest.NewRequest(http.MethodGet, "/v1/health", nil)
+	rec := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status %d", rec.Code)
+	}
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatal(err)
+	}
+	if body["status"] != "ok" {
+		t.Errorf("status = %v", body["status"])
+	}
+}
+
+func TestCapabilities(t *testing.T) {
+	srv := testServer(t)
+	req := httptest.NewRequest(http.MethodGet, "/v1/capabilities", nil)
+	rec := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status %d", rec.Code)
+	}
+	var body struct {
+		Capabilities []string `json:"capabilities"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]bool{"mcp.test": false, "model.inspect": false}
+	for _, c := range body.Capabilities {
+		if _, ok := want[c]; ok {
+			want[c] = true
+		}
+	}
+	for c, seen := range want {
+		if !seen {
+			t.Errorf("capability %q missing", c)
+		}
+	}
+}
+
+func TestCreateJob_BadType(t *testing.T) {
+	srv := testServer(t)
+	req := httptest.NewRequest(http.MethodPost, "/v1/jobs", jsonBody(`{"type":"nope"}`))
+	rec := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status %d, want 400", rec.Code)
+	}
+}
+
+func TestGetJob_NotFound(t *testing.T) {
+	srv := testServer(t)
+	req := httptest.NewRequest(http.MethodGet, "/v1/jobs/job_missing", nil)
+	rec := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(rec, req)
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status %d, want 404", rec.Code)
+	}
+}

app/main.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Launcher for the MatrixCloud Hugging Face Space.
+
+HF runs this as the container entrypoint. It normalises the environment for a
+Space (writable data dir, listening port that matches `app_port`) and then
+hands off to the real `matrix-runtime` binary via exec, so the Go process
+becomes PID 1's child with no extra layer.
+"""
+import os
+import sys
+
+# HF maps external traffic to the container's app_port (7860 by default). Honor
+# $PORT if the platform provides one, else fall back to 7860.
+port = os.environ.get("PORT") or os.environ.get("MATRIX_RUNTIME_PORT") or "7860"
+os.environ["MATRIX_RUNTIME_PORT"] = port
+
+# The Space filesystem is largely read-only; /tmp is writable. Durable data
+# (accounts, sessions) should be in Postgres via MATRIXCLOUD_DATABASE_URL.
+data_dir = os.environ.setdefault("MATRIX_RUNTIME_DATA_DIR", "/tmp/matrixcloud")
+try:
+    os.makedirs(data_dir, exist_ok=True)
+except OSError as exc:  # pragma: no cover - defensive
+    print(f"warning: could not create data dir {data_dir}: {exc}", file=sys.stderr)
+
+mode = os.environ.get("MATRIX_RUNTIME_MODE", "cloud-worker")
+print(f"MatrixCloud Space launching: mode={mode} port={port} data_dir={data_dir}", flush=True)
+
+# Replace this process with the runtime binary.
+os.execvp("matrix-runtime", ["matrix-runtime", "--mode", mode])

clients/python/README.md

@@ -0,0 +1,63 @@
+# matrixcloud — Python client & CLI
+
+Official Python SDK and command-line interface for **Matrix Cloud / Matrix
+Runtime**. Talk to the `/v1` API: authenticate, run jobs, inspect models, and
+drive MCP sandboxes.
+
+## Install (with [uv](https://docs.astral.sh/uv/) — fast)
+
+```bash
+cd clients/python
+uv sync --extra dev      # creates .venv and installs the package + dev tools
+uv run mxc status        # or: source .venv/bin/activate && mxc status
+```
+
+From the repo root you can also run `make venv` (uv) and `make py-test`.
+
+Plain pip works too:
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## CLI
+
+```bash
+mxc signup                       # create a workspace + owner
+mxc login                        # sign in (token stored in ~/.config/matrixcloud)
+mxc status                       # runtime health + capabilities
+mxc jobs                         # list jobs
+mxc inspect hf:Qwen/Qwen2.5-7B-Instruct
+mxc sandbox start mcp_server:filesystem \
+    --cmd 'npx -y @modelcontextprotocol/server-filesystem /tmp'
+mxc sandbox tools <session_id>
+mxc sandbox call  <session_id> list_directory --args '{"path":"/tmp"}'
+mxc sandbox stop  <session_id>
+```
+
+Point at a remote runtime with `--url` or `MATRIXCLOUD_URL`; use
+`MATRIXCLOUD_TOKEN` to pass a session token in CI.
+
+## Library
+
+```python
+from matrixcloud import MatrixCloud
+
+with MatrixCloud("http://localhost:8080") as mc:
+    mc.login("you@acme.io", "secret123")
+    print(mc.capabilities()["capabilities"])
+    meta = mc.inspect_model("hf:Qwen/Qwen2.5-7B-Instruct")
+    print(meta["recommended_runtime"], meta["estimated_parameters"])
+
+    s = mc.create_sandbox("mcp_server:filesystem",
+                          "npx -y @modelcontextprotocol/server-filesystem /tmp")
+    for ev in mc.stream_sandbox_events(s["session_id"]):
+        print(ev["step"], ev["message"])
+        if ev["step"] == "ready":
+            break
+    print([t["name"] for t in mc.sandbox_tools(s["session_id"])])
+    mc.delete_sandbox(s["session_id"])
+```
+
+Licensed under Apache-2.0.

clients/python/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matrixcloud"
+version = "0.1.0"
+description = "Official Python client and CLI for Matrix Cloud / Matrix Runtime."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "agent-matrix" }]
+keywords = ["matrix", "matrixcloud", "mcp", "ai", "agents", "runtime", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "httpx>=0.27",
+  "typer>=0.12",
+  "rich>=13.7",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.6",
+  "mypy>=1.11",
+]
+
+[project.scripts]
+matrixcloud = "matrixcloud.cli:app"
+mxc = "matrixcloud.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/agent-matrix/matrix-runtime"
+Repository = "https://github.com/agent-matrix/matrix-runtime"
+Documentation = "https://github.com/agent-matrix/matrix-runtime/blob/main/docs/console.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matrixcloud"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+# Keep typing compatible with Python 3.9 + Typer's runtime hint resolution
+# (X | None / list[...] break Typer on 3.9), so skip the pyupgrade typing rules.
+ignore = ["E501", "UP006", "UP007", "UP035", "UP037", "UP045"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = false
+ignore_missing_imports = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

clients/python/src/matrixcloud/__init__.py

@@ -0,0 +1,18 @@
+"""Matrix Cloud — official Python client and CLI.
+
+Talk to a Matrix Runtime control surface (the /v1 API): authenticate, run jobs,
+inspect models, and drive MCP sandboxes.
+
+    from matrixcloud import MatrixCloud
+
+    with MatrixCloud("http://localhost:8080") as mc:
+        mc.login("you@acme.io", "secret123")
+        print(mc.capabilities()["capabilities"])
+        print(mc.inspect_model("hf:Qwen/Qwen2.5-7B-Instruct")["recommended_runtime"])
+"""
+
+from .client import MatrixCloud
+from .errors import AuthError, MatrixCloudError
+
+__all__ = ["MatrixCloud", "MatrixCloudError", "AuthError", "__version__"]
+__version__ = "0.1.0"

clients/python/src/matrixcloud/cli.py

@@ -0,0 +1,211 @@
+"""Matrix Cloud command-line interface (``matrixcloud`` / ``mxc``)."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import config as cfg
+from .client import DEFAULT_BASE_URL, MatrixCloud
+from .errors import MatrixCloudError
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="Matrix Cloud — control your runtime from the terminal.")
+sandbox_app = typer.Typer(no_args_is_help=True, help="Drive MCP sandboxes.")
+app.add_typer(sandbox_app, name="sandbox")
+console = Console()
+
+
+def _base(url: Optional[str]) -> str:
+    return url or os.environ.get("MATRIXCLOUD_URL") or cfg.load().get("base_url") or DEFAULT_BASE_URL
+
+
+def _client(url: Optional[str] = None) -> MatrixCloud:
+    token = os.environ.get("MATRIXCLOUD_TOKEN") or cfg.load().get("token")
+    return MatrixCloud(base_url=_base(url), token=token)
+
+
+def _fail(msg: str) -> None:
+    console.print(f"[bold red]✗[/] {msg}")
+    raise typer.Exit(1)
+
+
+@app.command()
+def login(
+    email: str = typer.Option(..., prompt=True),
+    password: str = typer.Option(..., prompt=True, hide_input=True),
+    url: Optional[str] = typer.Option(None, help="Runtime base URL"),
+) -> None:
+    """Sign in and store a session token."""
+    c = _client(url)
+    try:
+        out = c.login(email, password)
+    except MatrixCloudError as e:
+        _fail(f"login failed: {e}")
+    cfg.save(c.base_url, c.token, email)
+    u = out["user"]
+    console.print(f"[bold green]✓[/] signed in as [b]{u['email']}[/] · {u['role']} · {u['workspace']}")
+
+
+@app.command()
+def signup(
+    name: str = typer.Option(..., prompt=True),
+    email: str = typer.Option(..., prompt=True),
+    password: str = typer.Option(..., prompt=True, hide_input=True, confirmation_prompt=True),
+    workspace: Optional[str] = typer.Option(None, help="Workspace (tenant) name"),
+    url: Optional[str] = typer.Option(None),
+) -> None:
+    """Create a workspace + owner account."""
+    c = _client(url)
+    try:
+        out = c.signup(name, email, password, workspace)
+    except MatrixCloudError as e:
+        _fail(f"signup failed: {e}")
+    cfg.save(c.base_url, c.token, email)
+    u = out["user"]
+    console.print(f"[bold green]✓[/] workspace [b]{u['workspace']}[/] created — signed in as {u['email']}")
+
+
+@app.command()
+def logout(all_sessions: bool = typer.Option(False, "--all", help="Sign out of every session")) -> None:
+    """Sign out and clear stored credentials."""
+    try:
+        _client().logout(all_sessions)
+    except MatrixCloudError:
+        pass
+    cfg.clear()
+    console.print("[green]✓[/] signed out")
+
+
+@app.command()
+def me() -> None:
+    """Show the authenticated user."""
+    try:
+        u = _client().me()
+    except MatrixCloudError as e:
+        _fail(str(e))
+    console.print(f"[b]{u['name']}[/] <{u['email']}> · {u['role']} · workspace [b]{u['workspace']}[/]")
+
+
+@app.command()
+def status(url: Optional[str] = typer.Option(None)) -> None:
+    """Runtime health + capabilities (live)."""
+    c = _client(url)
+    try:
+        h = c.health()
+        caps = c.capabilities()
+    except MatrixCloudError as e:
+        _fail(f"runtime unreachable at {c.base_url}: {e}")
+    console.print(f"[bold green]●[/] [b]{h['runtime_id']}[/] · mode [b]{h['mode']}[/] · v{h['version']}  ([dim]{c.base_url}[/])")
+    console.print("  capabilities: " + ", ".join(caps.get("capabilities", [])))
+    limits = caps.get("limits", {})
+    console.print(f"  limits: max_ttl={limits.get('max_ttl_seconds')}s · max_jobs={limits.get('max_concurrent_jobs')}")
+
+
+@app.command()
+def jobs(url: Optional[str] = typer.Option(None)) -> None:
+    """List jobs (newest first)."""
+    try:
+        rows = _client(url).list_jobs()
+    except MatrixCloudError as e:
+        _fail(str(e))
+    if not rows:
+        console.print("[dim]no jobs yet[/]")
+        return
+    t = Table("Job", "Type", "Status", "Created", box=None, header_style="bold")
+    colour = {"complete": "green", "running": "cyan", "error": "red", "expired": "yellow", "queued": "dim", "cancelled": "yellow"}
+    for j in rows:
+        st = j.get("status", "")
+        t.add_row(j.get("job_id", ""), j.get("type", ""), f"[{colour.get(st, 'white')}]{st}[/]", (j.get("created_at") or "").replace("T", " ").replace("Z", ""))
+    console.print(t)
+
+
+@app.command()
+def inspect(model: str, revision: str = typer.Option("main"), url: Optional[str] = typer.Option(None)) -> None:
+    """Resolve a model's metadata via model.inspect (live)."""
+    try:
+        meta = _client(url).inspect_model(model, revision)
+    except MatrixCloudError as e:
+        _fail(str(e))
+    t = Table(show_header=False, box=None)
+    for k in ("model", "pipeline_tag", "library_name", "model_type", "license", "estimated_parameters", "recommended_runtime", "requires_gpu"):
+        if k in meta:
+            t.add_row(f"[dim]{k}[/]", str(meta[k]))
+    console.print(t)
+
+
+@sandbox_app.command("start")
+def sandbox_start(
+    entity_id: str = typer.Argument(..., help="e.g. mcp_server:filesystem"),
+    command: str = typer.Option(..., "--cmd", help="start command, e.g. 'npx -y @modelcontextprotocol/server-filesystem /tmp'"),
+    ttl: int = typer.Option(600),
+    url: Optional[str] = typer.Option(None),
+) -> None:
+    """Start a sandbox session and stream its lifecycle until ready."""
+    c = _client(url)
+    try:
+        s = c.create_sandbox(entity_id, command, ttl_seconds=ttl)
+    except MatrixCloudError as e:
+        _fail(str(e))
+    sid = s["session_id"]
+    console.print(f"[green]✓[/] sandbox [b]{sid}[/] starting (job {s.get('job_id')})")
+    try:
+        for ev in c.stream_sandbox_events(sid):
+            console.print(f"  [dim]{ev.get('step','')}[/] {ev.get('message','')}")
+            if ev.get("step") == "ready":
+                break
+            if ev.get("status") in ("error", "expired"):
+                break
+    except MatrixCloudError:
+        pass
+    console.print(f"tools: mxc sandbox tools {sid}")
+
+
+@sandbox_app.command("tools")
+def sandbox_tools(session_id: str, url: Optional[str] = typer.Option(None)) -> None:
+    """List the tools exposed by a sandbox."""
+    try:
+        tools = _client(url).sandbox_tools(session_id)
+    except MatrixCloudError as e:
+        _fail(str(e))
+    t = Table("Tool", "Description", box=None, header_style="bold")
+    for tool in tools:
+        t.add_row(tool.get("name", ""), (tool.get("description", "") or "")[:80])
+    console.print(t)
+
+
+@sandbox_app.command("call")
+def sandbox_call(
+    session_id: str,
+    name: str,
+    args: str = typer.Option("{}", "--args", help="JSON arguments"),
+    url: Optional[str] = typer.Option(None),
+) -> None:
+    """Call a tool in a sandbox."""
+    try:
+        arguments = json.loads(args)
+    except ValueError:
+        _fail("--args must be valid JSON")
+    try:
+        out = _client(url).call_sandbox_tool(session_id, name, arguments)
+    except MatrixCloudError as e:
+        _fail(str(e))
+    console.print_json(data=out)
+
+
+@sandbox_app.command("stop")
+def sandbox_stop(session_id: str, url: Optional[str] = typer.Option(None)) -> None:
+    """Delete a sandbox session."""
+    try:
+        _client(url).delete_sandbox(session_id)
+    except MatrixCloudError as e:
+        _fail(str(e))
+    console.print(f"[green]✓[/] stopped {session_id}")
+
+
+if __name__ == "__main__":
+    app()

clients/python/src/matrixcloud/client.py

@@ -0,0 +1,180 @@
+"""Synchronous HTTP client for the Matrix Runtime /v1 API."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict, Iterator, List, Optional
+
+import httpx
+
+from .errors import AuthError, MatrixCloudError
+
+DEFAULT_BASE_URL = "http://localhost:8080"
+_TERMINAL = {"complete", "error", "expired", "cancelled"}
+
+
+class MatrixCloud:
+    """A thin, typed client over the runtime's REST API.
+
+    Pass ``transport`` (an ``httpx.BaseTransport``) to inject a mock in tests.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        token: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout, transport=transport)
+
+    # -- lifecycle -------------------------------------------------------
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "MatrixCloud":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def _headers(self) -> Dict[str, str]:
+        h = {"Accept": "application/json"}
+        if self.token:
+            h["Authorization"] = "Bearer " + self.token
+        return h
+
+    def _request(self, method: str, path: str, body: Any = None) -> Any:
+        try:
+            r = self._http.request(method, path, headers=self._headers(), json=body)
+        except httpx.HTTPError as e:  # network / connection error
+            raise MatrixCloudError(f"request to {path} failed: {e}") from e
+        data: Any = None
+        if r.content:
+            try:
+                data = r.json()
+            except ValueError:
+                data = r.text
+        if r.status_code >= 400:
+            msg = data.get("error") if isinstance(data, dict) else (data or f"HTTP {r.status_code}")
+            if r.status_code in (401, 403):
+                raise AuthError(str(msg), status=r.status_code, data=data)
+            raise MatrixCloudError(str(msg), status=r.status_code, data=data)
+        return data
+
+    # -- auth ------------------------------------------------------------
+    def signup(self, name: str, email: str, password: str, workspace: Optional[str] = None) -> Dict[str, Any]:
+        out = self._request("POST", "/v1/auth/signup", {"name": name, "email": email, "password": password, "workspace": workspace})
+        self.token = out.get("token")
+        return out
+
+    def login(self, email: str, password: str) -> Dict[str, Any]:
+        out = self._request("POST", "/v1/auth/login", {"email": email, "password": password})
+        self.token = out.get("token")
+        return out
+
+    def me(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/auth/me")["user"]
+
+    def logout(self, all_sessions: bool = False) -> None:
+        self._request("POST", "/v1/auth/logout" + ("?all=true" if all_sessions else ""), {})
+        self.token = None
+
+    # -- platform --------------------------------------------------------
+    def health(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/health")
+
+    def capabilities(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/capabilities")
+
+    # -- jobs ------------------------------------------------------------
+    def create_job(self, type: str, payload: Optional[Dict[str, Any]] = None, ttl_seconds: Optional[int] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"type": type}
+        if payload is not None:
+            body["payload"] = payload
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
+        return self._request("POST", "/v1/jobs", body)
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        return self._request("GET", "/v1/jobs/" + job_id)
+
+    def list_jobs(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/jobs").get("jobs", [])
+
+    def cancel_job(self, job_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", "/v1/jobs/" + job_id)
+
+    def run_job(
+        self,
+        type: str,
+        payload: Optional[Dict[str, Any]] = None,
+        ttl_seconds: Optional[int] = None,
+        timeout: float = 60.0,
+        poll: float = 0.5,
+    ) -> Any:
+        """Create a job and block until it reaches a terminal state."""
+        job = self.create_job(type, payload, ttl_seconds)
+        job_id = job["job_id"]
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            snap = self.get_job(job_id)
+            if snap["status"] in _TERMINAL:
+                if snap["status"] != "complete":
+                    raise MatrixCloudError(snap.get("error") or snap["status"], data=snap)
+                return snap.get("result")
+            time.sleep(poll)
+        raise MatrixCloudError(f"job {job_id} timed out after {timeout}s")
+
+    def inspect_model(self, model: str, revision: str = "main") -> Dict[str, Any]:
+        return self.run_job("model.inspect", {"model": model, "revision": revision})
+
+    def stream_job_events(self, job_id: str) -> Iterator[Dict[str, Any]]:
+        yield from self._sse("/v1/jobs/" + job_id + "/events")
+
+    # -- sandboxes -------------------------------------------------------
+    def create_sandbox(
+        self,
+        entity_id: str,
+        start_command: str,
+        runtime: str = "node",
+        transport: str = "stdio",
+        ttl_seconds: int = 600,
+    ) -> Dict[str, Any]:
+        return self._request("POST", "/v1/sandbox/sessions", {
+            "entity_id": entity_id,
+            "start_command": start_command,
+            "runtime": runtime,
+            "transport": transport,
+            "ttl_seconds": ttl_seconds,
+        })
+
+    def get_sandbox(self, session_id: str) -> Dict[str, Any]:
+        return self._request("GET", "/v1/sandbox/sessions/" + session_id)
+
+    def sandbox_tools(self, session_id: str) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/sandbox/sessions/" + session_id + "/tools").get("tools", [])
+
+    def call_sandbox_tool(self, session_id: str, name: str, arguments: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._request("POST", "/v1/sandbox/sessions/" + session_id + "/tools/call", {"name": name, "arguments": arguments or {}})
+
+    def delete_sandbox(self, session_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", "/v1/sandbox/sessions/" + session_id)
+
+    def stream_sandbox_events(self, session_id: str) -> Iterator[Dict[str, Any]]:
+        yield from self._sse("/v1/sandbox/sessions/" + session_id + "/events")
+
+    # -- internals -------------------------------------------------------
+    def _sse(self, path: str) -> Iterator[Dict[str, Any]]:
+        with self._http.stream("GET", path, headers=self._headers()) as r:
+            if r.status_code >= 400:
+                raise MatrixCloudError(f"stream {path}: HTTP {r.status_code}", status=r.status_code)
+            for line in r.iter_lines():
+                if line.startswith("data: "):
+                    try:
+                        yield json.loads(line[6:])
+                    except ValueError:
+                        continue

clients/python/src/matrixcloud/config.py

@@ -0,0 +1,44 @@
+"""Tiny credential store for the CLI (~/.config/matrixcloud/credentials.json)."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+def _config_dir() -> Path:
+    override = os.environ.get("MATRIXCLOUD_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return Path.home() / ".config" / "matrixcloud"
+
+
+def _cred_path() -> Path:
+    return _config_dir() / "credentials.json"
+
+
+def save(base_url: str, token: Optional[str], email: Optional[str] = None) -> None:
+    d = _config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    path = _cred_path()
+    path.write_text(json.dumps({"base_url": base_url, "token": token, "email": email}, indent=2))
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+
+
+def load() -> Dict[str, Any]:
+    try:
+        return json.loads(_cred_path().read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def clear() -> None:
+    try:
+        _cred_path().unlink()
+    except OSError:
+        pass

clients/python/src/matrixcloud/errors.py

@@ -0,0 +1,18 @@
+"""Exception types for the Matrix Cloud client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MatrixCloudError(Exception):
+    """Base error for all client failures."""
+
+    def __init__(self, message: str, status: Optional[int] = None, data: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.data = data
+
+
+class AuthError(MatrixCloudError):
+    """Raised on 401/403 — missing or invalid credentials."""

clients/python/tests/test_client.py

@@ -0,0 +1,92 @@
+"""Unit tests for the Matrix Cloud client using an in-memory httpx transport."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from matrixcloud import AuthError, MatrixCloud, MatrixCloudError
+
+
+def make_handler():
+    """A fake runtime: routes a handful of /v1 endpoints."""
+    jobs: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        method = request.method
+        body = json.loads(request.content) if request.content else {}
+
+        if path == "/v1/health":
+            return httpx.Response(200, json={"status": "ok", "runtime_id": "rt_test", "mode": "local-dev", "version": "0.1.0"})
+        if path == "/v1/capabilities":
+            return httpx.Response(200, json={"capabilities": ["mcp.test", "model.inspect"], "limits": {"max_ttl_seconds": 600, "max_concurrent_jobs": 2}})
+        if path == "/v1/auth/login" and method == "POST":
+            if body.get("password") == "secret123":
+                return httpx.Response(200, json={"token": "tok_abc", "user": {"email": body["email"], "role": "Owner", "workspace": "Acme", "name": "Neo"}})
+            return httpx.Response(401, json={"error": "invalid email or password"})
+        if path == "/v1/auth/me":
+            if request.headers.get("Authorization") == "Bearer tok_abc":
+                return httpx.Response(200, json={"user": {"email": "neo@acme.io", "role": "Owner", "workspace": "Acme", "name": "Neo"}})
+            return httpx.Response(401, json={"error": "not authenticated"})
+        if path == "/v1/jobs" and method == "POST":
+            jid = "job_" + str(len(jobs) + 1)
+            jobs[jid] = {"job_id": jid, "type": body["type"], "status": "complete",
+                         "result": {"model": body.get("payload", {}).get("model"), "recommended_runtime": "vllm"}}
+            return httpx.Response(202, json={"job_id": jid, "status": "queued"})
+        if path == "/v1/jobs" and method == "GET":
+            return httpx.Response(200, json={"jobs": list(jobs.values())})
+        if path.startswith("/v1/jobs/") and method == "GET":
+            jid = path.rsplit("/", 1)[-1]
+            if jid in jobs:
+                return httpx.Response(200, json=jobs[jid])
+            return httpx.Response(404, json={"error": "job not found"})
+
+        return httpx.Response(404, json={"error": "not found: " + path})
+
+    return handler
+
+
+def client() -> MatrixCloud:
+    return MatrixCloud(base_url="http://rt.test", transport=httpx.MockTransport(make_handler()))
+
+
+def test_health_and_capabilities():
+    with client() as c:
+        assert c.health()["status"] == "ok"
+        assert "model.inspect" in c.capabilities()["capabilities"]
+
+
+def test_login_sets_token_and_me():
+    with client() as c:
+        out = c.login("neo@acme.io", "secret123")
+        assert out["token"] == "tok_abc"
+        assert c.token == "tok_abc"
+        assert c.me()["workspace"] == "Acme"
+
+
+def test_login_wrong_password_raises_auth_error():
+    with client() as c:
+        with pytest.raises(AuthError):
+            c.login("neo@acme.io", "nope")
+
+
+def test_me_without_token_raises():
+    with client() as c:
+        with pytest.raises(AuthError):
+            c.me()
+
+
+def test_run_job_and_inspect_model():
+    with client() as c:
+        meta = c.inspect_model("hf:Qwen/Qwen2.5-7B-Instruct")
+        assert meta["recommended_runtime"] == "vllm"
+        assert len(c.list_jobs()) == 1
+
+
+def test_unknown_path_raises():
+    with client() as c:
+        with pytest.raises(MatrixCloudError):
+            c.get_job("missing")

cmd/matrix-runtime/main.go

@@ -0,0 +1,169 @@
+// Command matrix-runtime is the execution plane for Matrix Cloud. It serves an
+// HTTP API for running MCP sandboxes, inspecting models and (in future)
+// agents/tools, and can join a MatrixHub Cloud control plane.
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"net"
+	"os"
+	"os/signal"
+	"strconv"
+	"syscall"
+
+	"github.com/agent-matrix/matrix-runtime/api"
+	"github.com/agent-matrix/matrix-runtime/internal/config"
+	"github.com/agent-matrix/matrix-runtime/internal/controlplane"
+	"github.com/agent-matrix/matrix-runtime/internal/jobs"
+	"github.com/agent-matrix/matrix-runtime/internal/store"
+)
+
+func main() {
+	if len(os.Args) > 1 && os.Args[1] == "join" {
+		if err := runJoin(os.Args[2:]); err != nil {
+			log.Fatalf("join: %v", err)
+		}
+		return
+	}
+	if err := runServe(os.Args[1:]); err != nil {
+		log.Fatalf("matrix-runtime: %v", err)
+	}
+}
+
+func runServe(args []string) error {
+	fs := flag.NewFlagSet("matrix-runtime", flag.ExitOnError)
+	mode := fs.String("mode", "", "runtime mode: cloud-worker|customer-agent|hf-space|local-dev")
+	port := fs.Int("port", 0, "HTTP port (overrides MATRIX_RUNTIME_PORT)")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+
+	cfg := config.FromEnv(*mode)
+	if *port != 0 {
+		cfg.Port = *port
+	}
+	if err := cfg.Validate(); err != nil {
+		return err
+	}
+
+	// Loud, actionable warnings for unsafe production configuration. These do not
+	// abort startup (the readiness probe also reports them) but they should be
+	// impossible to miss in logs.
+	if cfg.IsProduction() {
+		if cfg.APIToken == "" {
+			log.Printf("WARNING: MATRIX_RUNTIME_API_TOKEN is not set in %s mode — the API is unauthenticated for non-session callers", cfg.Mode)
+		}
+		if cfg.DatabaseURL == "" {
+			log.Printf("WARNING: using SQLite in %s mode — set MATRIX_RUNTIME_DATABASE_URL (Postgres) for multi-user/HA deployments", cfg.Mode)
+		}
+	}
+	if cfg.MatrixShellEnabled {
+		log.Printf("WARNING: MatrixShell is ENABLED — it executes commands in a local sandbox (disable with MATRIX_SHELL_ENABLED=false)")
+	}
+
+	mgr := jobs.NewManager(cfg)
+	defer mgr.Shutdown()
+
+	if err := mgr.Layout().EnsureDirs(); err != nil {
+		log.Printf("warning: could not create data dirs under %s: %v", cfg.DataDir, err)
+	}
+
+	// Open the multitenant user store. When a PostgreSQL/Neon URL is configured
+	// (hosted control plane, e.g. cloud.matrixhub.io) use it and isolate all
+	// objects in cfg.DBSchema; otherwise fall back to a local SQLite file. A
+	// failure here is non-fatal: the console loads but auth endpoints return 503.
+	var (
+		st     *store.Store
+		err    error
+		dbDesc string
+	)
+	if cfg.DatabaseURL != "" {
+		st, err = store.OpenPostgres(cfg.DatabaseURL, cfg.DBSchema, cfg.DataDir)
+		dbDesc = fmt.Sprintf("postgres (schema %q)", cfg.DBSchema)
+	} else {
+		st, err = store.Open(cfg.DBPath)
+		dbDesc = cfg.DBPath
+	}
+	if err != nil {
+		log.Printf("warning: could not open user store (%s): %v", dbDesc, err)
+	} else {
+		defer func() { _ = st.Close() }()
+		mgr.SetInstallStore(st)
+		log.Printf("user store ready: %s", dbDesc)
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	// Background retention: purge old terminal jobs, scratch dirs and logs.
+	mgr.StartJanitor(ctx)
+
+	// Bind the configured port; if it's busy, walk forward to the next free one.
+	ln, boundPort, err := listenWithFallback(cfg.Port, 50)
+	if err != nil {
+		return err
+	}
+	if boundPort != cfg.Port {
+		log.Printf("port %d is in use — using %d instead", cfg.Port, boundPort)
+	}
+	cfg.Port = boundPort
+
+	log.Printf("matrix-runtime %s (commit %s, built %s) starting: mode=%s runtime_id=%s addr=:%d data_dir=%s",
+		config.Version, config.Commit, config.Date, cfg.Mode, cfg.EffectiveRuntimeID(), boundPort, cfg.DataDir)
+	log.Printf("console + API ready: http://localhost:%d", boundPort)
+
+	srv := api.NewServer(cfg, mgr, st)
+	if err := srv.Serve(ctx, ln); err != nil && err.Error() != "http: Server closed" {
+		return err
+	}
+	log.Printf("matrix-runtime stopped")
+	return nil
+}
+
+// listenWithFallback binds the first free TCP port in [start, start+maxTries),
+// returning the listener and the port it bound. A port already in use is
+// skipped; other errors (e.g. permission) are returned.
+func listenWithFallback(start, maxTries int) (net.Listener, int, error) {
+	var lastErr error
+	for p := start; p < start+maxTries && p <= 65535; p++ {
+		ln, err := net.Listen("tcp", ":"+strconv.Itoa(p))
+		if err == nil {
+			return ln, p, nil
+		}
+		lastErr = err
+		if errors.Is(err, syscall.EADDRINUSE) {
+			continue
+		}
+		// Non "in use" error on the very first try is fatal; otherwise keep trying.
+		if p == start {
+			return nil, 0, err
+		}
+	}
+	return nil, 0, fmt.Errorf("no free port in range %d-%d: %w", start, start+maxTries-1, lastErr)
+}
+
+func runJoin(args []string) error {
+	fs := flag.NewFlagSet("join", flag.ExitOnError)
+	cloudURL := fs.String("cloud-url", "", "MatrixHub Cloud URL")
+	token := fs.String("token", "", "runtime join token")
+	runtimeID := fs.String("runtime-id", "", "optional runtime id")
+	workspace := fs.String("workspace", "", "optional workspace")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	path, err := controlplane.WriteJoinConfig(controlplane.JoinConfig{
+		CloudURL:  *cloudURL,
+		JoinToken: *token,
+		RuntimeID: *runtimeID,
+		Workspace: *workspace,
+	})
+	if err != nil {
+		return err
+	}
+	fmt.Printf("Wrote join configuration to %s\n", path)
+	return nil
+}

cmd/matrix-runtime/main_test.go

@@ -0,0 +1,51 @@
+package main
+
+import (
+	"net"
+	"testing"
+)
+
+func TestListenWithFallback_SkipsBusyPort(t *testing.T) {
+	// Occupy a port, then ask listenWithFallback to start there.
+	occ, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = occ.Close() }()
+	busy := occ.Addr().(*net.TCPAddr).Port
+
+	ln, got, err := listenWithFallback(busy, 20)
+	if err != nil {
+		t.Fatalf("listenWithFallback: %v", err)
+	}
+	defer func() { _ = ln.Close() }()
+
+	if got == busy {
+		t.Fatalf("expected fallback to a different port, got the busy one %d", busy)
+	}
+	if got <= busy {
+		t.Errorf("expected a higher port than %d, got %d", busy, got)
+	}
+	if ln.Addr().(*net.TCPAddr).Port != got {
+		t.Errorf("listener port %d != reported %d", ln.Addr().(*net.TCPAddr).Port, got)
+	}
+}
+
+func TestListenWithFallback_FreePort(t *testing.T) {
+	// Find a free port, release it, then bind it via the helper.
+	probe, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	free := probe.Addr().(*net.TCPAddr).Port
+	_ = probe.Close()
+
+	ln, got, err := listenWithFallback(free, 20)
+	if err != nil {
+		t.Fatalf("listenWithFallback: %v", err)
+	}
+	defer func() { _ = ln.Close() }()
+	if got != free {
+		t.Errorf("expected to bind the free port %d, got %d", free, got)
+	}
+}

deploy/docker-compose/.env.example

@@ -0,0 +1,11 @@
+# Copy to .env and adjust. All values are optional; defaults are shown.
+MATRIX_RUNTIME_MODE=local-dev
+MATRIX_RUNTIME_MAX_TTL_SECONDS=600
+MATRIX_RUNTIME_MAX_CONCURRENT_JOBS=2
+
+# Hybrid cloud (customer-agent mode)
+MATRIX_CLOUD_URL=https://cloud.matrixhub.io
+MATRIX_RUNTIME_JOIN_TOKEN=
+
+# Hugging Face token for gated/private models
+HF_TOKEN=

deploy/docker-compose/docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  matrix-runtime:
+    build:
+      context: ../..
+      dockerfile: Dockerfile
+    image: matrix-runtime:local
+    ports:
+      - "8080:8080"
+    environment:
+      MATRIX_RUNTIME_MODE: ${MATRIX_RUNTIME_MODE:-local-dev}
+      MATRIX_RUNTIME_DATA_DIR: /var/lib/matrix-runtime
+      MATRIX_RUNTIME_MAX_TTL_SECONDS: ${MATRIX_RUNTIME_MAX_TTL_SECONDS:-600}
+      MATRIX_RUNTIME_MAX_CONCURRENT_JOBS: ${MATRIX_RUNTIME_MAX_CONCURRENT_JOBS:-2}
+      MATRIX_CLOUD_URL: ${MATRIX_CLOUD_URL:-https://cloud.matrixhub.io}
+      MATRIX_RUNTIME_JOIN_TOKEN: ${MATRIX_RUNTIME_JOIN_TOKEN:-}
+      HF_TOKEN: ${HF_TOKEN:-}
+    volumes:
+      - matrix-runtime-data:/var/lib/matrix-runtime
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/v1/health"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  matrix-runtime-data:

deploy/helm/matrix-runtime/Chart.yaml

@@ -0,0 +1,16 @@
+apiVersion: v2
+name: matrix-runtime
+description: Matrix Runtime — the execution plane for Matrix Cloud (MCP sandboxes, agents, tools, model jobs).
+type: application
+version: 0.1.0
+appVersion: "0.1.0"
+keywords:
+  - matrix
+  - mcp
+  - runtime
+  - execution-plane
+home: https://github.com/agent-matrix/matrix-runtime
+sources:
+  - https://github.com/agent-matrix/matrix-runtime
+maintainers:
+  - name: agent-matrix

deploy/helm/matrix-runtime/templates/_helpers.tpl

@@ -0,0 +1,32 @@
+{{- define "matrix-runtime.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "matrix-runtime.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name (include "matrix-runtime.name" .) | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "matrix-runtime.labels" -}}
+app.kubernetes.io/name: {{ include "matrix-runtime.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
+{{- end -}}
+
+{{- define "matrix-runtime.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "matrix-runtime.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{- define "matrix-runtime.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create -}}
+{{- default (include "matrix-runtime.fullname" .) .Values.serviceAccount.name -}}
+{{- else -}}
+{{- default "default" .Values.serviceAccount.name -}}
+{{- end -}}
+{{- end -}}

deploy/helm/matrix-runtime/templates/configmap.yaml

@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "matrix-runtime.fullname" . }}
+  labels:
+    {{- include "matrix-runtime.labels" . | nindent 4 }}
+data:
+  MATRIX_RUNTIME_MODE: {{ .Values.runtime.mode | quote }}
+  MATRIX_RUNTIME_PORT: {{ .Values.service.port | quote }}
+  MATRIX_RUNTIME_DATA_DIR: {{ .Values.runtime.dataDir | quote }}
+  MATRIX_RUNTIME_MAX_TTL_SECONDS: {{ .Values.runtime.maxTTLSeconds | quote }}
+  MATRIX_RUNTIME_MAX_CONCURRENT_JOBS: {{ .Values.runtime.maxConcurrentJobs | quote }}
+  MATRIX_CLOUD_URL: {{ .Values.cloud.url | quote }}
+  {{- with .Values.runtime.id }}
+  MATRIX_RUNTIME_ID: {{ . | quote }}
+  {{- end }}
+  {{- with .Values.runtime.workspace }}
+  MATRIX_RUNTIME_WORKSPACE: {{ . | quote }}
+  {{- end }}

deploy/helm/matrix-runtime/templates/deployment.yaml

@@ -0,0 +1,73 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "matrix-runtime.fullname" . }}
+  labels:
+    {{- include "matrix-runtime.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "matrix-runtime.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "matrix-runtime.selectorLabels" . | nindent 8 }}
+    spec:
+      serviceAccountName: {{ include "matrix-runtime.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        - name: matrix-runtime
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          args: ["--mode", "{{ .Values.runtime.mode }}"]
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.service.port }}
+          envFrom:
+            - configMapRef:
+                name: {{ include "matrix-runtime.fullname" . }}
+            {{- if or .Values.runtime.joinToken .Values.runtime.apiToken .Values.runtime.hfToken }}
+            - secretRef:
+                name: {{ include "matrix-runtime.fullname" . }}
+            {{- end }}
+          livenessProbe:
+            httpGet:
+              path: /v1/health
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 20
+          readinessProbe:
+            httpGet:
+              path: /v1/ready
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: data
+              mountPath: {{ .Values.runtime.dataDir }}
+      volumes:
+        - name: data
+          {{- if .Values.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ include "matrix-runtime.fullname" . }}-data
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

deploy/helm/matrix-runtime/templates/pvc.yaml

@@ -0,0 +1,17 @@
+{{- if .Values.persistence.enabled }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "matrix-runtime.fullname" . }}-data
+  labels:
+    {{- include "matrix-runtime.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    {{- toYaml .Values.persistence.accessModes | nindent 4 }}
+  resources:
+    requests:
+      storage: {{ .Values.persistence.size | quote }}
+  {{- with .Values.persistence.storageClass }}
+  storageClassName: {{ . | quote }}
+  {{- end }}
+{{- end }}

deploy/helm/matrix-runtime/templates/secret.yaml

@@ -0,0 +1,19 @@
+{{- if or .Values.runtime.joinToken .Values.runtime.apiToken .Values.runtime.hfToken }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "matrix-runtime.fullname" . }}
+  labels:
+    {{- include "matrix-runtime.labels" . | nindent 4 }}
+type: Opaque
+stringData:
+  {{- with .Values.runtime.joinToken }}
+  MATRIX_RUNTIME_JOIN_TOKEN: {{ . | quote }}
+  {{- end }}
+  {{- with .Values.runtime.apiToken }}
+  MATRIX_RUNTIME_API_TOKEN: {{ . | quote }}
+  {{- end }}
+  {{- with .Values.runtime.hfToken }}
+  HF_TOKEN: {{ . | quote }}
+  {{- end }}
+{{- end }}

deploy/helm/matrix-runtime/templates/service.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "matrix-runtime.fullname" . }}
+  labels:
+    {{- include "matrix-runtime.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  selector:
+    {{- include "matrix-runtime.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: http
+      port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP