R1 Hardware Engine

Documentation · v0.5.1

How the authority engine decides.

R1 Hardware Engine sits in front of local model execution and evaluates every requested configuration against your live hardware. This page covers the quickstart, the three verdicts it can return, and the boundary it will not cross.

01

Quickstart

  1. STEP 01

    Install the extension

    Install from the Open VSX Registry — compatible with VS Code, VSCodium, Cursor and Windsurf.

  2. STEP 02

    Scan your hardware

    Open the R1 Hardware Dashboard from the Activity Bar to analyse your VRAM and system memory. All 21 models are unlocked immediately — no account, no license key.

  3. STEP 03

    Validate and run

    Press Ctrl+Shift+P and run R1 Hardware: Validate & Run Local Model. Select a configuration and the engine pre-calculates stability before anything executes.

  4. STEP 04

    Review the decision

    Every request returns one of three verdicts, each with explicit reasoning. Nothing runs until the engine has answered.

02

The three verdicts

ALLOW

Safe to run. The configuration fits inside real headroom and executes untouched.

DOWNGRADED

Parameters were modified to prevent a crash — KV cache quantised, context reduced, CPU offload engaged — and the run proceeds in the recovered configuration.

DENY

A crash was predicted and execution is blocked. The reason is always stated.

03

Authority mode and the Hard Wall

Authority mode

The engine always runs in its strictest mode: it strictly blocks any execution predicted to destabilise the OS or GPU driver, and applies stabilisation strategies — KV cache compression, context reduction, CPU offload — to try to safely recover a request before denying it.

The Hard Wall

The Hard Wall is a safety boundary enforced when a requested configuration is predicted to destabilise the system. This includes conditions such as:

  • VRAM pressure exceeding safe thresholds
  • High likelihood of GPU out-of-memory errors
  • OS-level swapping that would freeze or hang the system

Some DENY outcomes represent crash-risk conditions, not absolute physical impossibility. In these cases, stabilisation strategies may safely convert the request into a DOWNGRADED configuration.

True physical limits — where a model cannot fit even under maximum compression and reduction — remain non-negotiable and are always denied.

04

Wiring the gate into an agent

The same authority engine is exposed over MCP, so a coding agent can ask before it starts a model. The server is a stdio binary — any MCP client that can spawn a subprocess can use it.

The two tools

  • check_hardware_fit — returns the verdict for a model and context without launching anything.
  • run_local_model — asks for the verdict, then launches only if it passes. There is no code path from DENY to the launcher.

An agent that would otherwise start a model too large for the machine gets a refusal with a stated reason, instead of an out-of-memory crash halfway through loading.

Configuration

Add the server to your MCP client's config. In Claude Code that is .mcp.json; Cursor and others use an equivalent file:

{
  "mcpServers": {
    "r1-hardware": {
      "command": "node",
      "args": ["<extension-path>/out/mcp-server.js"]
    }
  }
}

<extension-path> is where your editor installed the extension, or a clone of the repository after npm run compile. Server diagnostics are written to stderr so they never corrupt the JSON-RPC stream on stdout.

Architecture, formulas and configuration.

The full prediction model, the memory formulas behind each verdict, and advanced configuration are documented in the repository.

Read the architecture docs Report an issue