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: bodybridge

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.