# Nelloz

Nelloz is an English-first desktop voice agent for Windows. It combines a
low-latency Deepgram Voice Agent session with integrated computer use,
persistent account memory, secure subscription limits, and encrypted
multi-device pairing.

The package includes the native Windows launcher, the local Nelloz interface,
the realtime voice client, and the orchestration services needed to connect the
voice experience to longer computer, browser, file, coding, and research work.
Model weights, private credentials, `.env` files, development sources, and user
data are never included in the published package.

## Install and open the desktop app

Nelloz requires Node.js 20.11 or newer and currently provides its complete
desktop experience on Windows.

```powershell
npm install -g nelloz
nelloz app
```

The first `nelloz app` command creates or repairs the real `Nelloz.exe` desktop
launcher, applies the bundled Nelloz icon, starts the local services without a
visible terminal, and opens the sign-in window. Future launches work by
double-clicking **Nelloz** on the desktop.

Registration and plan purchases remain on [nelloz.com](https://nelloz.com).
The desktop app is intentionally sign-in only.

The npm installation itself has no `install` or `postinstall` lifecycle script.
It does not execute downloaded code or fetch additional software automatically.
Desktop setup begins only when the user explicitly runs `nelloz app` or
`nelloz start`.

## What is included

- English realtime voice conversation with Deepgram Flux, managed Gemini Flash
  Lite, and Aura-2 speech
- Continuous microphone listening, barge-in, and full-duplex playback control
- Integrated computer use for visible applications, browser work, files, coding,
  and longer tasks
- Native computer-use indication with an Escape stop control
- Account-scoped long-term memory with explicit remember and forget controls
- Supabase authentication and server-authoritative subscription allowances
- Stripe subscription integration for Plus, Pro, and Max plans
- Fast current-web lookup for focused realtime questions
- Encrypted local-network pairing for additional Nelloz computers
- Privacy-conscious diagnostics with credential and private-text redaction

## Start Nelloz as the main computer

```powershell
nelloz start
```

This starts the local interface at
`http://127.0.0.1:4173/static/mobile-omni/`, prepares an already-installed
computer-use runtime, and creates a one-time pairing code valid for ten minutes.
After a device is paired, a new code is generated automatically.

Nelloz never downloads model weights from a normal start command. If an optional
local runtime is unavailable, the voice interface and account experience remain
available.

## Add another computer

Install Nelloz on the additional computer, then enter the pairing code shown by
the main computer:

```powershell
npm install -g nelloz
nelloz join K7M2XP
nelloz start
```

Nelloz discovers the main computer on the local network. If network broadcasts
are blocked, provide its address once:

```powershell
nelloz join K7M2XP --host 192.168.1.20
```

Later connections use only the locally protected device credentials and the
last verified endpoint.

## Voice and computer-use architecture

The primary live path uses Deepgram's native Voice Agent WebSocket:

```text
Microphone -> Flux -> managed Gemini Flash Lite -> Aura-2 -> speakers
```

Flux handles transcription, turn detection, and barge-in. The browser never
receives provider keys; it connects only to Nelloz's local authenticated
WebSocket. The production defaults are English-only and use
`flux-general-en`, `gemini-3.1-flash-lite`, and `aura-2-andromeda-en`.

Longer work remains one continuous Nelloz action. The computer-use runtime is
warmed when Nelloz opens, keeps a stable session per account, and uses native
desktop capabilities for visible actions. Nelloz does not claim that an action
succeeded until its result confirms completion.

## Accounts, plans, and usage

Users sign in with their Nelloz account. Registration and purchases are handled
on [nelloz.com](https://nelloz.com), while the desktop app reads the resulting
Supabase account and plan state.

Usage allowances are calculated and committed server-side. Local files and
browser values are display caches only and cannot grant additional usage. Free
accounts receive the configured trial allowance; Plus, Pro, and Max accounts
use both a rolling five-hour window and a weekly allowance.

Useful account commands:

```powershell
nelloz login
nelloz account --json
nelloz logout
```

## Runtime and diagnostics

The normal desktop experience does not require starting the optional local
model stack. Advanced runtime commands remain available:

```powershell
nelloz init
nelloz doctor
nelloz verify-package --json
nelloz self-test --json
nelloz runtime-start --dry-run
nelloz runtime-start
```

No Nelloz command downloads foundation-model weights automatically.

Technical events are written asynchronously to
`~/.nelloz/logs/events-YYYY-MM-DD.ndjson`. Audio, passwords, API keys, email
addresses, and private message text are omitted, redacted, or represented only
by safe metadata. Logs rotate at 16 MB and are retained for 14 days.

```powershell
nelloz logs --local --lines 200
nelloz logs --local --summary
nelloz speed-test --json
```

## Programmatic API and TypeScript

Nelloz ships declaration files for its public ESM exports:

```ts
import { openBrowser, PORTS, run } from 'nelloz';
import { NellozHub, pairDevice } from 'nelloz/system-link';
```

The package exposes the CLI helpers from `nelloz` and the encrypted pairing API
from `nelloz/system-link`.

## Security notes

- Provider and billing secrets stay server-side.
- The package contains no automatic installer or remote download lifecycle.
- Stripe plan activation is tied to the signed Supabase user ID, never an email
  address supplied by a browser.
- Usage limits are enforced by authenticated server operations.
- Computer use is visibly indicated and can be stopped with Escape.
- Pairing uses one-time codes, signed device credentials, and encrypted sessions.

## License

ISC. Third-party components and notices are listed in
`THIRD_PARTY_NOTICES.md`.