HT Studio turns a workstation into a governed local model operating layer: model library, native runtime, OpenAI-compatible API, routing, MoA, evals, traces, lifecycle proof, SDK, CLI, and Studio UI in one repo.
One app-facing surface for local AI. Backends stay behind HT Studio; consumers use HT Studio APIs.
HT Studio is a standalone local runtime orchestrator for developers, agents, and desktop AI systems. It is not a launcher skin. It owns the operating layer around local inference: model discovery and import, native llama.cpp serving, OpenAI-compatible endpoints, benchmark-aware routing, MoA/council orchestration, eval-fed admission, redacted traces, runtime lifecycle proof, and approval-gated mutations.
HT Studio is local-first, not network-silent. Prompts, completions, local inventory, and model weights stay on the workstation by default. Explicit catalog, model-card, package, and runtime-install actions may call public registries, and optional high-performance backends such as vLLM, SGLang, TensorRT-LLM, and TabbyAPI stay hidden behind HT Studio's adapter and proof contracts.
| For apps | Stable `/v1/*` and `/api/*` contracts instead of direct coupling to Ollama, LM Studio, vLLM, or ad hoc servers. |
| For local models | HT Studio-owned model library, import provenance, admission state, fit planning, warm/unload controls, and health-aware routing. |
| For agents | Approval boundaries, tool-call non-execution, route metadata, traces, MoA confidence, and agent-runtime metadata. |
| For operators | Runtime supervisor, diagnostics bundles, eval suites, lifecycle proof, CLI smoke, package smoke, and release gates. |
HT Studio is intentionally small because this repo is the runtime control plane, not a bundled model-weight payload. Local models, node_modules, build outputs, and generated proof captures are machine-local payloads.
Current captured footprint after the standalone trim:
| Scope | Size |
|---|---|
| Core code/docs/config, excluding media, deps, dist, and output | 1.02 MB |
| Tracked repo payload with docs media and terminal proof assets | 4.84 MB |
| Runtime packages source only: SDK + daemon + CLI | 474.84 KB |
| Studio app source only | 101.01 KB |
| Full local workspace on disk, including deps/build/output | 896.48 MB |
node_modules local dependency payload |
858.10 MB |
dist build outputs |
18.75 MB |
Ignored local output evidence payload |
3.40 MB |
Publishable dry-run tarballs from the latest terminal proof:
| Package | Packed | Unpacked |
|---|---|---|
@ht-studio/sdk |
11.60 KB | 55.50 KB |
@ht-studio/daemon |
132.72 KB | 676.04 KB |
@ht-studio/cli |
8.37 KB | 29.34 KB |
The terminal proof video and screenshots are tracked in this repo under docs/images/terminal-proof. The full proof write-up is in docs/terminal-proof.md.
FDE-oriented proof docs:
docs/fde-case-study.md- customer-style problem, deployed solution, proof surface, and resume-safe claim.docs/demo-script.md- two-minute walkthrough for interviews.docs/deployment-runbook.md- fresh-machine setup, verification, and common failures.docs/security-proof.md- local daemon security checklist and claim boundary.docs/hugging-face-boundary.md- Hugging Face network, license, download, and secret-handling boundary.
|
CLI smoke and package proof 
|
CLI help and runtime profile 
|
|
Live daemon status and readiness endpoint 
|
|
HT Studio is built around one principle: consumer apps should have one stable local AI surface, while HT Studio owns the messy runtime work behind it.
| Capability | What it gives you |
|---|---|
| OpenAI-compatible API | /v1/models, /v1/chat/completions, /v1/responses, and /v1/embeddings for standard client compatibility. |
| Universal runtime contract | /api/status, /api/runtime/contracts, /api/models/catalog, /api/routing/standard, /api/evals/*, /api/traces/*, and /api/runtime/performance/plan. |
| HT Studio model library | Owned/imported GGUF model inventory with provenance, trust level, admission state, route eligibility, MoA eligibility, health, and fit data. |
| Native runtime independence | Managed llama-server/llama.cpp path so HT Studio can run owned/imported GGUFs without requiring a live Ollama or LM Studio server. |
| Proof-gated adapter lanes | vLLM, SGLang, TensorRT-LLM, TabbyAPI, LocalAI, and generic OpenAI-compatible lanes stay behind HT Studio until loopback smoke, evals, and benchmarks prove them. |
| Smart routing | Route modes for fast single-model use, best-quality local routing, long-context, structured output, tool-calling, low-memory, throughput batch, and MoA/council. |
| MoA / council orchestration | Advisor calls, judge/synthesizer metadata, confidence, candidate status, fallback reason, and traceable local orchestration through HT Studio APIs. |
| Runtime supervisor | Managed process state, warm/unload actions, crash/failure metadata, recovery endpoint, and stable degradation reasons. |
| Eval and scorecard loop | Runtime-contract, coding, reasoning, JSON, long-context, tool-call, MoA, latency, concurrency, admission, failure-recovery, and safety eval suites. |
| Observability | Redacted traces, trace bundles, telemetry ids on API responses, queue state, adapter health, GPU diagnostics, and diagnostics export. |
| Install/lifecycle proof | Autostart, config migration, portable backup/restore, rollback/apply, installer package smoke, diagnostics bundle, and clean uninstall guardrails. |
| Approval and privacy boundary | Privileged runtime mutations require x-ht-studio-confirm: privileged-action; HT Studio generates or passes tool calls but never executes tools. |
Launcher-style tools usually help start a model. HT Studio is designed to be the operating layer around local inference.
| Instead of... | HT Studio provides... |
|---|---|
| App-specific model wiring | One canonical runtime surface for any app, agent, CLI, or SDK consumer. |
| Raw backend coupling | Adapter contracts that hide backend-specific ports, commands, and quirks. |
| "Installed means ready" claims | Measured admission, evals, traces, health checks, and live proof before route eligibility. |
| Manual model juggling | Owned/imported model library, fit planning, warm/unload controls, and route explanations. |
| Silent fallback behavior | Deterministic fallback reasons, degraded-state reporting, trace ids, and redacted bundles. |
| Tool execution inside model server | Approval-safe tool-call generation only; the consumer agent decides whether to execute. |
| Surface | Network behavior | Trigger |
|---|---|---|
| Local daemon, CLI, SDK, Studio app | Loopback HTTP only by default | Normal status, chat, inventory, readiness, and local model execution |
| Hugging Face catalog and downloads | Calls huggingface.co APIs and model file URLs |
Search, model-card/license review, dry run, or pull |
| Ollama registry resolution | Calls registry.ollama.ai and ollama.com metadata URLs |
Resolving an Ollama library ref for download |
Managed llama-server installer |
Calls GitHub release APIs and trusted release asset URLs | Explicit engine/server install action |
| npm/package checks | Calls npm registry during install/audit | npm ci, npm install, or audit commands |
No hosted AI provider receives prompts by default. If you configure an OpenAI-compatible upstream, that endpoint is outside the default local boundary and should be treated as an explicit integration.
HT Studio can see useful model files in common local caches, but visibility is not the same thing as automatic trust. External cache discoveries are import sources until they are copied or admitted into HT Studio's model library.
- Ambient discovery: Scans standard workstation locations such as LM Studio, Ollama, Jan, AnythingLLM, Hugging Face Hub, and configured GGUF folders.
- Import-first routing: Ollama and LM Studio cache files can be imported into the HT Studio-owned model library, then routed through HT Studio's native runtime path.
- Stable aliases: Apps can use
ht-studio-standard,ht-studio-fast,ht-studio-coder,ht-studio-reasoning,ht-studio-structured, andht-studio-moainstead of hardcoding backend model paths. - Backend-agnostic execution: Managed llama.cpp is the self-sufficient default. Optional backends can be detected, probed, and benchmarked, but consumers still call HT Studio.
- Live proof command:
npm run smoke:live-backendsreports daemon freshness, optional backend package state, loopback ports, and whether a throughput claim is actually proven. - Custom runtime targets: Home lab, LAN, cloud, and generic OpenAI-compatible endpoints can be configured, but local-only policy blocks unsafe egress from automatic routing.
|
Ambient scanner and source discovery 
|
Custom server hosts and connection tuning 
|
HT Studio is organized as a structured npm monorepo workspaces project:
| Path | Purpose |
|---|---|
apps/studio |
Vite + React SPA HT Studio workbench interface. |
packages/daemon |
HTTP daemon, GGUF parser, VRAM scanner, downloads, hot-pool, and adapters. |
packages/cli |
Lifecycle commands (htstudio), daemon launchers, and environment helpers. |
packages/sdk |
Typed client, resolver, and unified public typescript schemas. |
config/studio.autorun.json |
Discovery policies, auto-pull policies, and auto-warm configurations. |
docs/auto-runtime.md |
App integration specifications and auto-warm protocols. |
docs/runtime-api.md |
Canonical runtime brain, OpenAI-compatible, MoA, telemetry, and approval-gated API contract. |
To launch the HT Studio daemon, React console, and auto-discovered models:
# 1. Install dependencies
npm install
# 2. Dry-run auto-discover & warm local models
npm run studio:auto-runtime
# 3. Spin up concurrent daemon and studio UI
npm run devTo automatically apply configured HT Studio runtime pulls and warmup hooks:
npm run studio:auto-runtime:executeHT Studio stores data and active models under HT_STUDIO_HOME, defaulting to:
C:\Users\Owner\AppData\Local\HT Studio
Customize endpoints and security policies by specifying environment variables before execution:
$env:HT_STUDIO_PORT = "3001"
$env:HT_STUDIO_ALLOWED_ORIGINS = "http://127.0.0.1:3000,http://localhost:3000"
# Optional compatibility discovery only; core routing uses HT Studio's runtime contract.
$env:OLLAMA_HOST = "http://127.0.0.1:11434"
$env:LM_STUDIO_HOST = "http://127.0.0.1:1234"Check the active compatibility scorecard proof via curl or browser:
Invoke-RestMethod http://127.0.0.1:3001/api/compatibility/scorecardCheck the canonical runtime brain contract:
Invoke-RestMethod http://127.0.0.1:3001/api/runtime/brainCheck live optional backend proof without promoting anything:
npm run smoke:live-backendsThis writes output/live-backend-proof.json and reports whether the current daemon is fresh, whether vLLM/SGLang/TensorRT-style lanes are installed and listening on loopback, and whether HT Studio can honestly make any measured throughput claim.
npm run build
node packages/cli/dist/index.js status
node packages/cli/dist/index.js performance
node packages/cli/dist/index.js profile terminal-agent$env:OPENAI_BASE_URL = "http://127.0.0.1:3001/v1"
$env:OPENAI_API_KEY = "local-not-needed"Use model=ht-studio-standard for the current trusted standard route, or model=ht-studio-moa for local MoA/council orchestration.
const response = await fetch("http://127.0.0.1:3001/v1/chat/completions", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
model: "ht-studio-standard",
messages: [{ role: "user", content: "hi" }]
})
});
console.log(await response.json());HT Studio's public claims are backed by repeatable local and CI gates:
# Run the complete compiler, test, build, and package validation checks
npm run release:check
# Probe the actual local machine for optional throughput lanes
npm run smoke:live-backends- Type safety:
tscverification across packages. - Unit and integration tests: 287 Vitest tests on the current main branch.
- API smoke: fresh daemon boot, public HTTP checks, lifecycle proof actions, eval trace lookup, and OpenAI-compatible endpoints.
- Studio smoke: Playwright checks against the runtime control-room UI.
- Package smoke: dry-run and installed tarball import/CLI checks for SDK, daemon, and CLI.
- Live backend proof: local machine check for daemon freshness, WSL/NVIDIA/Docker availability, optional backend packages, and loopback candidate ports.
- Release gate: GitHub Actions runs the release check on Ubuntu and Windows.
Recent live proof on Hassan's workstation shows the managed llama.cpp lane is ready to benchmark, while vLLM, SGLang, TensorRT-LLM, and TabbyAPI remain blocked until installed and exposed through loopback OpenAI-compatible adapters. HT Studio does not claim throughput superiority until those lanes pass smoke, eval, and benchmark proof.