How-to guide
Permissions¶
Nawa acts on your behalf — it writes files, runs commands, reads pages, drives a browser, calls plugins. Permissions decide which of those it may do without asking you first. Two things are at work: a mode per chat, and cards that ask when the mode says to.
The modes¶
Every chat has a mode, shown and changed from the permission control in the composer. New chats start in the level chosen under Settings → General → Default permission level for new chats.
| Mode | What runs without asking | What asks |
|---|---|---|
| Manual | Nothing gated | Every gated action |
| Accept edits | Work inside the chat's workspace: reading, writing and editing files, code tools, the built-in browser | Shell commands and imports of outside files |
| Plan | Ungated reads of workspace files, attachments and saved sources, computation and web research | Gated actions are denied, not offered for approval; change modes to execute them. This also blocks external file reads and shell commands. |
| Auto | Everything ordinary | Risky actions: destructive shell commands, mutations through connected services, and anything the rules below mark |
| Bypass permissions | Ordinary gated actions | Durable automation changes still ask; connected services keep their own rules |
Auto is the shipped default. Plan is the mode to use when you want to see the approach before anything is touched; Manual when you want to watch every step.
The mode belongs to the chat. Changing the default in Settings changes new chats, not the one that is open; changing the composer control changes the open chat only.
The cards¶
When a step needs your permission, Nawa pauses and shows a card in the transcript naming the tool, what it wants to do, and — for a command — the exact command. The card offers:
- Allow once — this step runs; the next one like it asks again.
- Always allow — this step runs and remembers its grant for the session. The scope varies: ordinary shell approval covers the shell action class, while destructive commands have narrower command-specific grants. It is not necessarily limited to one tool.
- Deny — the step does not run; Nawa is told, and continues or stops as the task allows.
A card shows how long it has been waiting, and the choice you made stays on the card afterwards with the time it waited, so a chat you return to still reads truthfully. Stopping the turn cancels a pending card.
Plugins and connected services have their own permission per tool, chosen in Settings; see Plugins and connectors. Their cards look the same.
What the sandbox does¶
Normal sandboxed commands run at low integrity, with writes granted to the workspace, the selected project folder and explicitly authorized paths. This is not complete per-chat filesystem isolation: other writable low-integrity locations are shared. Approved host execution instead uses the host account's inherited integrity and filesystem/device access. Read the execution scope on the approval card before allowing it.
Commands have a separate network grant. This is cooperative environment enforcement, not a Windows firewall; do not treat a none grant as an operating-system guarantee that an arbitrary program cannot connect.
The built-in browser is Nawa's headless Chromium. Chrome control is a plugin with a persistent browser profile and its own permissions; sessions signed into that profile are available to it. See Plugins and connectors.
Instruction files (AGENTS.md), web pages and attachments never grant a permission; only your choice on a card or in Settings does.
Turn permissions off entirely¶
The Permissions switch on the General tab exists for a machine where nothing needs guarding. With it off no card is shown for workspace work. Connected services still ask according to their own settings.