Matrix Scroll — Documentation

This is the practical guide: how to get Digital Rain running, connect it to your editor, sign and verify a release, and reach for the right knob when something misbehaves. If you want the why — the threat model and the cryptography — read the Whitepaper.

1. Installation

Ensure you have Python 3.11+ installed. We recommend setting up a virtual environment inside your project directory to keep dependencies isolated:

python -m venv .venv
.\.venv\Scripts\activate          # Windows
# source .venv/bin/activate       # macOS / Linux
pip install -r requirements.txt

This pulls in all required modules, including cryptography, which the identity layer uses to perform Ed25519 cryptographic signatures.

2. Running the Local Stack

Digital Rain runs entirely on localhost. The default backend port is 59712.

Web Dashboard

Launches on a random free port and automatically opens in your browser:

python app.py

Desktop Companion

Pins the backend specifically to port 59712, suppresses browser focus, and launches the interactive desktop mascot widget:

.\run_desktop_companion.bat

The companion floats always-on-top. Left-click and drag to move it, right-click to open the quick-actions console, and double-click to access the full web dashboard. On startup, it performs a project scan and alerts you to files needing attention (e.g. Jupyter notebooks executed out-of-order).

To run the backend headlessly on the pinned port without opening a browser window:

$env:PORT=59712; $env:OPEN_BROWSER=0; python app.py

3. IDE Integration

Digital Rain implements the Model Context Protocol (MCP). The server ID is cursor-copilot (retained for backward compatibility).

VS Code (Native Agent Mode, v1.102+)

Commit a .vscode/mcp.json file to your workspace:

{
  "servers": {
    "cursor-copilot": {
      "type": "stdio",
      "command": "C:/path/to/.venv/Scripts/python.exe",
      "args": ["C:/path/to/mcp_server.py"],
      "env": { "COPILOT_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

Open the file and click Start on the server. The 13 tools will instantly become available in your agent tools picker.

Cursor

Create a .cursor/mcp.json configuration (there is a ready-to-use template in the workspace root named .cursor/mcp.json.example) and register it in Cursor Settings → MCP.

Cline / Roo-Code / Windsurf

Append the cursor-copilot configuration block directly to the extension's global mcpServers config file.

A great initial prompt in any IDE is: "Use cursor-copilot to scan this project, then show the device_identity."

4. The 13 MCP Tools

5. Local REST API

Useful for deployment scripts, CI/CD pipes, and simple terminal querying:

Invoke-RestMethod "http://127.0.0.1:59712/api/health"
Invoke-RestMethod "http://127.0.0.1:59712/api/diagnostics"
Invoke-RestMethod "http://127.0.0.1:59712/api/project/status"
Invoke-RestMethod "http://127.0.0.1:59712/api/identity"
Invoke-RestMethod "http://127.0.0.1:59712/api/brainstorm?limit=3&async=1"

• /api/health: Reports active LLM backend configuration, loaded files, and database chunk sizes.
• /api/diagnostics: Returns comprehensive local machine diagnostics with credentials and secrets redacted.

6. Root of Trust: Identity, Signing & Verification

This is where software and physical hardware boundaries meet.

Identify this workstation:

Invoke-RestMethod "http://127.0.0.1:59712/api/identity"

Returns a stable device_id (e.g. MS-4319-20D5), the algorithm (ed25519), the public_key (base64 encoded), and the provider mode (emulated or hardware). The private key is never returned or logged.

Signing a Release

The helper script qa/release_evidence.py scans output folders, serializes build files, and writes a signed manifest.json alongside a summary log. The signature covers a recursive canonical JSON representation.

Verifying Signatures

To verify a build manifest, strip the signature block, serialize the remaining keys canonically, and verify the resulting bytes against the base64-encoded public key from /api/identity. Python teams can use the built-in identity.verify_manifest function.

Emulated vs. Hardware Mode

Toggle between software emulation and physical chip custody using an environment variable:

$env:MATRIXSCROLL_MODE = "emulated"   # Default, key stored on disk
# $env:MATRIXSCROLL_MODE = "hardware" # Target mode for physical secure element keys

In emulated mode, keys reside under MATRIXSCROLL_HOME (defaults to ~/.matrixscroll) with strict owner-only permissions. Keep this directory out of version control and off shared drives.

7. Configuration Reference

8. Troubleshooting

9. FAQ

Do I need the hardware to use any of this?

No. The software, BM25 indexing, MCP tools, and cryptographic signing/verification work completely in emulated mode using an on-disk key. The physical hardware (Scroll Key or Scroll Token) is required only if you need to secure the private key in tamper-proof silicon.

Does my code ever leave my machine?

Only if you use cloud-based backends (Anthropic/Gemini) to process prompts. Everything else, including indexing, metadata extraction, key generation, and signing is done entirely on localhost. To operate in a 100% air-gapped, zero-data-sharing configuration, choose the ollama backend.

Is the emulated key as secure as the device?

No. An on-disk key, even with restricted filesystem permissions, is susceptible to extraction if the host operating system is compromised by root-level malware. The physical hardware devices (Scroll Key or Scroll Token) seal keys behind a physical secure element boundary that cannot be read back by the host. That isolation is the core security value.

Questions or deployment snags: operations@matrixscroll.com · Digital Rain · Matrix Scroll