Vraxis Read

Vraxis Read is a local-first reading environment for engineers and technical researchers. It separates finishing a page from being able to explain or implement what it taught.

Marketing site · npm package · agent-v · osx Components

Get started

Install Vraxis Read, then open it:

npm install -g @vraxis/reader
vraxis-read

Vraxis Read starts its local service and opens in your default browser. Choose a folder containing PDFs, EPUBs, Markdown files, or plain text files to build your library.

The desktop app uses the system folder chooser on macOS, Windows, and Linux. The browser version uses Finder on macOS, the Windows folder dialog, or Zenity or KDialog on Linux.

Each launch creates a private local session. Vraxis Read rejects requests without its session token. It also blocks foreign browser origins and non-local hostnames.

Save a blog post or article from the app, or add it from the terminal:

vraxis-read add https://example.com/article

Vraxis Read keeps the readable article, source details, and images in the Web folder inside your library. The result is plain Markdown that ArchNode and other local tools can use.

Vraxis Read requires Node.js 22.12 through 22.x. Use vraxis-read --no-open to start without opening a browser, or vraxis-read --port 4400 to choose another port. Run vraxis-read again to open an existing protected session. Press Ctrl+C to stop it.

This first product slice includes:

• A three-pane reading workspace built with Vue and @vraxis/osx-components.
• Four clear reading modes: Ask, Study, Research, and Challenge.
• Explicit page-cited, structurally inferred, and model-asserted trust labels.
• Confidence capture, review-state feedback, a proof-oriented code interaction, and import reporting.
• Recursive local-folder observation.
• Faithful in-app PDF page viewing, with extracted text available for search and agent context.
• Real PDF page extraction and EPUB chapter extraction.
• Markdown and text ingestion.
• Web capture for blog posts and articles, with source metadata and local images.
• agent-v orchestration for every reading-agent turn, with mandatory local execution scope and provenance.
• Hosted model support for OpenAI, Anthropic, Google, OpenRouter, Groq, DeepSeek, Ollama, and compatible endpoints.
• Local runtime discovery and bounded execution for Codex CLI, Claude Code, and OpenCode. Vraxis Read finds Cursor but leaves it unavailable because its adapter cannot guarantee structured output yet.

Work on Vraxis Read locally

npm install
npm run dev

Open http://localhost:4313/app. The deterministic local preview works without a configured model. The marketing site is available at http://localhost:4313/.

Build and open your local checkout with one command:

npm run open

The reader route is local-only because it needs filesystem access and the Node service. On a hosted domain, /app falls back to the marketing site instead of showing a disconnected reader.

Configure a model

Open Preferences, find Models and runtimes, then choose Set up beside a provider. Enter its model and API key. Vraxis Read saves provider settings in ~/.vraxis/read/providers.json with owner-only file permissions. Secret values stay in the local Node service and are never returned to the browser.

Environment variables remain available for unattended setups. For example:

export FOLIO_AI_PROVIDER=openai
export FOLIO_AI_MODEL=gpt-5-mini
export OPENAI_API_KEY=your-key
npm run dev

The browser sees only provider readiness, model identity, runtime provenance, and safe errors.

Verify

npm run check

The check runs the unit and HTTP integration suites. It also validates the Vue, server, and test TypeScript. The final steps compile the Node service and create the production Vite bundle.

Integration tests start the real service on an ephemeral localhost port. They verify authenticated sessions, Host checks, Origin checks, and the public JSON API.

The release gate covers:

• Reading-mode contracts and preview-agent behavior.
• Trust-label schema validation.
• Provider and local-runtime discovery without credential leakage.
• In-app provider setup without credential leakage.
• Original PDF streaming with byte-range support.
• A complete preview turn through agent-v, including citation and provenance.
• Invalid-request handling without invoking a model or local runtime.
• Safe URL validation, article extraction, image storage, Markdown output, and live library indexing.

Current boundary

Vraxis Read does not ship with a sample book or placeholder library metrics. It shows an honest empty state until you select a folder. The observer reads supported files where they already live. It updates the in-memory index when the folder changes. Vraxis Read stores its local data in ~/.vraxis/read/. This includes the observed folder, provider settings, annotations, and reviews.

On the first launch after upgrading, Vraxis Read copies existing data from the project's .folio/ folder into ~/.vraxis/read/. It keeps files already stored in the new location and leaves the old .folio/ folder as a recovery copy.

PDFs open in their original layout by default. Vraxis Read also extracts page text for search, citations, and agent context. Scanned or image-only files still require OCR before their text can ground an agent response. EPUBs are read in spine order and rendered as reflowable chapter text. Durable search indexes, annotation migration, OCR, richer EPUB styling, and isolated executable sandboxes remain the next backend milestones. Product-specific pedagogy and citation policy stay in Vraxis Read, while provider and runtime execution remain behind agent-v.