Explanation

Architecture

Nawa is one Windows application made of four parts that are deliberately kept apart: a desktop shell, an engine, a renderer, and a sandboxed runtime for everything it executes. The shape follows the agentic-loop tools it grew up beside — real files, Git as the safety net, the transcript as memory — and the engineering rulebook (AGENTS.md in the source tree) that governs its development.

The parts

The desktop shell (electron/) is an Electron application. It starts the engine, opens the main window on the engine's local address, owns the title bar, the updater and the Windows integration (the Start-menu shortcut, the Ask Nawa Explorer command, the taskbar completion count), and brokers a few things a web page cannot do on its own: opening a file in its native application, revealing it in Explorer, opening an address in the system browser, reading the device's location with consent. It never touches the model or the tools.

The engine (server.js and server/) is a Node.js process listening on 127.0.0.1 on a port it chooses at start. It owns every deterministic guarantee: the accounts and their encrypted settings, the chats and their turns, the tool registry and its security manifest, permissions, the workspaces, the artifacts, the plugins and connectors, the memory, and the trace of everything it did. It talks to language models through provider adapters (OpenAI-compatible, Anthropic, and the local servers) and to decision models through one client. A turn is a request to /api/chat/stream; the answer streams back as run events.

The renderer (public/) is the page in the main window: plain HTML, CSS and JavaScript with no framework and no build step, which is why a fix can be deployed by replacing the application archive alone. It holds the transcript, the composer, the sidebar, the drawer, Settings, and the artifact runtime that hosts apps in the drawer. It keeps the user's settings and sends them with every turn; credentials it holds only as references to the engine's encrypted storage.

The sandboxed runtime is what runs when Nawa runs something. Commands, builds, tests and browser processes are launched by nawa-exec.exe (native/windows-sandbox) under a low-integrity restricted token, on a private desktop, inside a Job Object that ends every descendant with the command, in the chat's workspace under the profile. Beside it sits a bundled toolchain (vendor/toolchain-win: Node.js, Git, ripgrep, a headless Chromium) and, in a full installation, Python and the language servers, so nothing has to be installed on the machine.

What passes between them

• The renderer and the engine speak HTTP and server-sent events over the loopback address; the shell adds a session token so only the window it opened is signed in.
• The engine and the model speak the provider's own protocol; the engine materialises every request and counts its tokens itself, so the budget it keeps is the budget the provider sees.
• The engine and the sandbox speak through process lifecycle frames: start, exit code or signal, timeout, cancellation, cleanup — reported as independent facts, never interpreted.
• The engine and a plugin speak the Model Context Protocol, over stdio for a local server or streamable HTTP for a remote one; the plugin's tools are classified per turn from what the user granted.

Where things live

	Path
The application	%LOCALAPPDATA%\Programs\Nawa — replaced by an update
The retained runtime	%LOCALAPPDATA%\Programs\Nawa-runtime — the executable runtime an update does not repackage
The profile	%APPDATA%\Nawa — settings, the database with chats and accounts, workspaces under data\jobs, artifacts, plugins, skills, memory, logs; untouched by an update
The engine log and trace	%APPDATA%\Nawa\data\server.log and data\runtime\trace-index.jsonl

Why it is shaped this way

• Everything deterministic in one place. Permissions, persistence, identity, validation and process lifecycle are the engine's, so the model can be replaced without moving a guarantee, and a guarantee can be tested without a model. See Harness and model.
• A renderer with no build. A page that is served as written can be patched, diffed and verified byte for byte against a commit — which is how fixes are deployed to an installed Nawa and checked.
• A sandbox instead of trust. A command the model writes runs with less authority than the user, in a place of its own, and cannot outlive its turn; the user's own files are reachable only through a project folder given to the chat.
• Bundled runtimes. A first install works without prerequisites, and an update replaces only the application code, keeping the large runtime beside it.

The dated notes under docs/ in the source tree record the decisions in detail; WINDOWS-UPDATE-RELEASE.md and WINDOWS-SANDBOX-COMPATIBILITY.md are the authoritative descriptions of the update and sandbox boundaries.