Vraxis Home

A local-first family dashboard for keeping up with important mail and family events. Run it on any Node 22 machine; open the same responsive interface on a wall display and paired phones.

Day-one capabilities

• Filter Gmail, Microsoft 365, and Yahoo Mail messages by exact sender address, sender domain, or subject keywords.
• Keep matched message summaries locally; raw message bodies are not retained.
• Summarize offline with a deterministic extractive fallback or choose an agent-v-backed OpenAI, Anthropic, or Google model using your own key.
• Add family events with a constrained quick-add sentence such as Soccer practice tomorrow at 5:30pm for 90 minutes.
• See a week calendar, local time, and Open-Meteo weather.
• Open the dashboard immediately on its host machine, then optionally pair a phone remote to control the display, add local calendar items, and update non-secret household settings.

Quick start

npx @vraxis/home

Or install the vraxis-home command globally with npm install --global @vraxis/home.

To run from source instead, clone the repository and use npm ci && npm run build && npm start.

The terminal prints a local dashboard URL and a six-digit pairing code. The dashboard opens without pairing on the host machine. To add an optional phone remote, open Settings → Phone remote, scan the QR code with a phone on the same Wi-Fi, enter the code shown beside the QR code, and use Add to Home Screen. The code is available only from the host machine and remains in the terminal as a fallback. The QR code contains only the LAN URL. If a code expires, the dashboard and terminal show a fresh code. Ten failed attempts pause new pairings for ten minutes.

The phone talks directly to the machine's private LAN address; there is no Vraxis cloud relay, public account, or router port forwarding. A paired phone may select mail for the home display, sync mail, add events to the local calendar, change the household name and weather location, and enable or pause existing mail rules. Mail connections, OAuth credentials, model providers, API keys, event deletion, and device administration remain host-machine-only. See the phone remote guide for the network and permission model.

On first launch, the service creates a private encryption key in its data directory. Set VRAXIS_HOME_MASTER_KEY when your service manager or backup system needs to manage that key.

Development uses npm run dev: the API listens on port 4310 and Vite on port 4311.

Configuration

Yahoo Mail can connect locally with an email address and a Yahoo-generated app password; it does not need HTTPS or a developer application. Never enter your normal Yahoo account password. Gmail and Microsoft 365 use OAuth and require your own app registration. Open Settings → Mail accounts and follow the provider-specific setup. Credentials are encrypted locally and never returned to the browser. See the mail account setup guide.

Open Settings → Summaries → Provider API keys to save an OpenAI, Anthropic, or Google AI key. Keys entered in the dashboard are encrypted locally, never returned by the API, and take precedence over the corresponding OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY service environment variable.

The default storage path is ~/.vraxis-home. For a managed service, use a private directory such as /var/lib/vraxis-home owned by the service account.

See the deployment guide for a persistent service and private phone access.

Product decisions

The phone browser is the first remote: it works on iOS and Android, avoids app-store accounts, and keeps one interface to secure. Calendar additions currently stay in Vraxis Home; any future write to Google Calendar, iCloud, CalDAV, or another external service will require a visible confirmation. WhatsApp intake, shared tasks, meal planning, medication reminders, and emergency contacts are useful follow-ons. They are extension points rather than hidden dependencies in the first release.

See ARCHITECTURE.md for boundaries and SECURITY.md before exposing the service outside a trusted LAN.

License

MIT