All work

Local AI / Case study

Auralis Local

Search private documents on your own machine.

Type
Open-source engineering
Release
v0.3.0
Stack
TypeScript · React 19 · Node.js · Python (MLX/Whisper)
Automated tests
47

System architecture

  1. Hybrid BM25 + Exact-Phrase Knowledge Base
  2. Guarded Workspace File Inspector & Proposal Gate
  3. Local Voice Room & Apple Silicon Dictation
Three layers from the project’s architecture blueprint

01 / Problem

Why it exists

Developers want capable coding, document retrieval, and voice assistants without streaming private source code or notes to external cloud APIs—or giving an LLM unrestricted shell and filesystem write access.

02 / Design

How it works

Bind only to 127.0.0.1, enforce session/CSRF headers on state-changing routes, and require explicit single-use user approval tokens for tool writes.

  1. Hybrid BM25 + Exact-Phrase Knowledge Base

    Chunks local Markdown, text, JSON, and source files with line-number provenance (#Lstart-Lend) and streams grounded citations into chat responses.

  2. Guarded Workspace File Inspector & Proposal Gate

    Validates paths via lstatSync/realpathSync to block symlinks and sensitive files, requiring explicit user approval before indexing.

  3. Local Voice Room & Apple Silicon Dictation

    Integrates sentence-by-sentence speech synthesis with local MLX/Whisper transcription and tap-to-interrupt controls.

Loopback-Only Binding and Explicit Human Approval Proposals
Context
Local AI assistants running on a developer workstation can become local privilege escalation vectors if exposed to the LAN or allowed to write files autonomously.
Decision
Bind only to 127.0.0.1, enforce session/CSRF headers on state-changing routes, and require explicit single-use user approval tokens for tool writes.
Trade-offs
Requires an extra user click to approve a note or document index, but eliminates silent prompt-injected writes.
Verification
Verified across 47 automated tests in tests/security.test.ts, tests/knowledge.test.ts, tests/pdf.test.ts, tests/memory.test.ts, and tests/api.test.ts.
Security and operational constraints
  • Loopback-only binding (127.0.0.1) with Origin validation and session-bound CSRF tokens.
  • Single-use, 5-minute expiring human approval proposals required before saving notes or indexing workspace files.
  • Workspace sandbox blocks "..", symlinks outside root, .env, .git, .ssh, and private key files; audit log redacts sensitive content.
  • Services bind exclusively to 127.0.0.1 and reject cross-origin browser requests.
  • No model-proposed note or workspace index action executes without a valid, unconsumed user approval token.
  • If Ollama is offline, the UI reports honest connection status rather than fabricating responses.

03 / Evidence

How to verify it

Repository-reported / Hybrid BM25 RAG Latency

0.245 ms P50 · 3,110 docs/s

Line-aware local document chunking and hybrid retrieval with deterministic source citations

Reproduce from the command line
git clone https://github.com/codesphere-u/auralis-local.git
cd auralis-local && npm install && npm test
npm run benchmark
View source on GitHub
Next case study · Research tooling ARGUS AI Challenge a proposed trade before it enters the simulation.