NAAvOS Avatar OS

The no-code desktop setup layer for a personal, user-owned Avatar.

NAAvOS is the Avatar authority. Radoss Agency is the company and maintainer. Hermes is the visible setup and orchestration agent. SQLite + FTS5 is the local canonical memory ledger. ReMe is an optional readable projection; Ollama is deliberately excluded from the public product.

For non-technical users

Use the signed desktop installer when it is released:

1. Install and open NAAvOS Avatar OS.

2. Name your Avatar.

3. Choose a privacy mode.

4. Click Set up my Avatar.

5. Approve the account connection in the browser. Do not copy a code or token.

6. Reopen or refresh the supported AI host when the wizard confirms the local adapter.

The desktop wizard creates encrypted local backups before mutations and exposes retry, rollback, privacy, disconnect, health, and security controls. Personal-agent credential warnings remain local operational warnings; the product does not copy or mutate them during an isolated sample or public source release.

There are three release surfaces. individual_local is one user's local desktop handoff. individual_hosted is one user's online Avatar deployed to that user's chosen Cloudflare, VPS, or other supported account. public is the shared hosted NAAvOS service and its hosted-client integrations; it requires additional multi-user and host-acceptance evidence. These profiles must not be interchanged: a local or single-owner handoff is not proof that the shared hosted service is tenant-safe.

The product has three deliberately different connection paths:

• No-code users: use the desktop wizard and browser OAuth; never copy a code, token, or configuration file.

• Developers: use the universal CLI and local stdio MCP adapters when they want scripted or repository-based control.

• Hosted AI users: use the branded HTTPS MCP gateway, then complete the final ChatGPT or Claude account connection in that host's own UI. Radoss never claims a host account is connected from a local file alone.

Related MCP server: dragon-work

CLI development path

The package is prepared for public npm publication but is not yet published. Publication is deliberately manual and approval-gated. Maintainers can use the Publish NAAvOS CLI GitHub Actions workflow after configuring the npm trusted publisher (or the repository's protected NPM_TOKEN secret) for the npm-publish environment. The workflow runs the full prepublish checks before publishing provenance-attested package metadata.

For a local, authenticated publication, publish the verified tarball with:

cd /path/to/radoss-universal-avatar
npm login
npm publish --access public

The universal CLI is maintained separately from the NAAvOS source mirror. Its public source repository is innosaint-uche/radoss-universal-avatar.

For local development from a checkout:

cd /path/to/radoss-universal-avatar
node bin/radoss.mjs setup
node bin/radoss.mjs setup status
node bin/radoss.mjs doctor
# Validate the deployed HTTPS MCP gateway without exposing a token
node bin/radoss.mjs mcp conformance https://mcp.naavos.radoss.agency/mcp --bearer-env RADOSS_GATEWAY_TOKEN --status-tool avatar_get

The CLI automatically manages the supported local targets:

• Codex: ~/.codex/config.toml

• Antigravity: ~/.gemini/config/mcp_config.json

• Hermes: ~/.hermes/profiles/avatar/config.yaml, isolated avatar profile

Each receives the local radoss_avatar MCP server. Hermes remains the visible orchestrator; the default Hermes profile is not silently replaced.

Connection boundary

Local agents use guarded stdio MCP. An online HTTPS Streamable HTTP gateway is optional; the current NAAvOS operator endpoint is available at https://mcp.naavos.radoss.agency/mcp with OAuth, D1-backed tenant-owner enforcement, and MCP lifecycle checks. Two-independent-live-user tenant acceptance remains a separate public-release gate. The canonical Worker origin remains an implementation detail behind the Hostinger/Coolify branded route. ChatGPT and Claude account connections remain host-managed; a local configuration file cannot prove an online ChatGPT or Claude connection.

The remote boundary and release evidence required for hosted clients are defined in docs/REMOTE_MCP_GATEWAY_CONTRACT.md. The local sidecar must never be exposed directly as a public connector. See docs/BRAND_AND_COMPATIBILITY.md for the canonical product name and retained technical aliases.

The verified local Hugging Face flow completes browser OAuth, verifies the provider account, stores credentials through the macOS Keychain helper, and separately verifies Hermes' OAuth-owned cache. It never prints or stores token values in setup state or agent configuration.

Verification

npm test
npm audit
npm pack --dry-run

See docs/NO_CODE_SETUP.md for the evidence contract and release gates, and desktop-setup/README.md for the Tauri packaging boundary.

See docs/RELEASE_STATUS.md for the current developer, local-validation, and customer-release boundaries.

Universal QA

Reusable browser and live-surface E2E belongs in the central external ~/.radoss-qa harness. Each project contributes only a small adapter describing its real URL and contract; it does not add Playwright, browser binaries, or Rust to the project. Rust is used only by a central Tauri or artifact adapter when process, IPC, filesystem, or signing evidence is needed. See the local harness README after installing the universal development environment.

Local Avatar profile and memory

The current source adds an offline path: choose Set up on this device only, then save your display name, background, communication preferences and operating rules. No provider login is needed for that path.

Your profile is stored in the local SQLite ledger. ~/.naavos/avatar.json is its compiler-compatible export, readable by the main NAAvOS compiler workspace. The editor refuses to overwrite an externally edited source file. Existing files are backed up before an editor save.

Restart a configured agent to load its local MCP tools. avatar_get reads the profile and up to 50 approved memories. avatar_memory_search searches approved memory. avatar_remember and avatar_memory_delete require explicit confirmation. Paused mode blocks private context and memory access. Local notes are never automatically sent to the hosted gateway. Deletion removes active ledger/index entries; earlier backups may retain copies.

The globally installed naavos-cli setup command and the compiler workspace's pnpm exec naavos are currently separate distributions. Use workspace commands from the compiler checkout for init, compile, export and conformance checks; use this runtime for desktop setup and local MCP. They share the Avatar export format. Do not assume that installing one distributes every command from the other.

These additions are source changes. The previously published v0.2.0-beta.1 installers predate them. A new installer must be built and tested from the reviewed revision before distribution.

Reproducible validation

npm ci
npm test
npx playwright install chromium
npx playwright test
node scripts/check-public-package.mjs
npm audit --omit=dev

Desktop packaging requires Node 26 or newer. After building on the target OS, run node scripts/verify-packaged-sidecar.mjs. This checks the actual executable's embedded UI, offline setup, profile persistence, generated agent command and stdio MCP path. Browser CI uses an isolated home with synthetic data. These checks do not certify signing, notarisation, native installation or named-host acceptance.