Every Wazza OS MCP tool

The tools wazza-os mcp gives an agent that runs outside Wazza OS: each one is a command of the command line. Below: how an agent uses them, then every tool with what it does, its arguments and an example.

WhatThe reference of every tool of wazza-os mcp

WhyTo know what an outside agent can do in Wazza OS, and how to ask

WhoAnyone connecting Claude Code, Codex, Cursor or another agent

WhereSet up on The Wazza OS MCP

Find the tool for a task#

To…	The agent uses
see whether Wazza OS runs, and what this computer lacks	`status`, `check`
open an app in a tab, read the tabs, send to a tab's Chat	`ui` (actions `open_app`, `vm_tabs_read`, `chat_send`)
read a Chat's conversation	`chat_transcript`
list the apps, check whether one is installed, uninstall it, add your own	`app`
put files into a VM, or bring them out	`explorer` (`copy_to_vm`, `upload`)
see and use an app's screen	`drive` (look, act)
start, stop or back up VMs; their memory, disk and graphics	`vm`, `vm_memory`, `vm_disk`, `vm_gpu`, `gpu`
API keys and sign-ins	`provider_keys`, `provider_signin`, `wazza_account`
settings of new Chats and their limits	`chat_model`, `timeouts`, `local_services`
a picture of Wazza OS itself (published build: on a server only; from the next release also on a desktop, its own window)	`screenshot`
a recording of Wazza OS's own screen on a server	`record`

Each tool's table: the verb (what the tool does this time), its arguments, what it does, and an example: the tool's arguments, then → the command it runs. This page is made from the same text that wazza-os mcp --print-docs prints for the next release. The published build (0.2.0, build 44c5d0ea07c1) has 40 of these tools; new in the next release: the start tool; provider_keys' add_from_env and add_from_file; ui's outcome verb and timeout_ms; screenshot and native_input on a desktop, and native_input's scroll. In both builds, explorer's upload without a folder puts the files in Downloads/From the VM (its description below still says Downloads).

How an agent uses them#

Wazza OS runs apps in virtual machines (VMs vm-1 to vm-8) on this computer; each app opens in a tab, and each tab has its own Chat (an AI agent). These tools are Wazza OS's own command line (wazza --gui ...): each one runs that CLI and answers its output and exit status (exit 2: the CLI refused the arguments, its usage text says how; nothing was done).

The typical flow#

status: is the Wazza OS app running? If not: start it with start (unless the user said not to start it); it waits until the app answers and returns its window state (check says what this computer lacks when it cannot start).
vm {verb: "list"}: the VMs; vm {verb: "start", vm: "vm-2"} starts a stopped one (minutes; list again).
ui {verb: "do", action: "open_app", args: {appId: "files", vmId: "vm-1"}}: the app opens in a background tab (the user's screen stays as it is); ui {verb: "do", action: "vm_tabs_read", args: {vm: "vm-1"}} names its tab id. app {verb: "list"} lists the apps, app {verb: "status", app_id} whether one is installed.
Chat: ui {verb: "do", action: "chat_send", args: {vmId, tabId, childId: "", text}} (childId "": the tab's own Chat, always named; a tab's Chat that never started starts behind the view); then chat_transcript {tab, vm, last: 5} reads its answer.
Drive (GUI work in a tab's app): drive {verb: "look", vm, tab} returns an image and a snapshot_id; drive {verb: "act", vm, tab, args: {snapshot_id, action: "left_click", x, y}} runs one action and returns the next view: check it, then the next act.
Files: explorer (a VM's files; this computer's with computer: true; copy_to_vm, upload). Settings: vm_memory, vm_disk, vm_gpu, gpu, chat_model, timeouts, local_services, clipboard. Updates: ui {verb: "do", action: "update_read"} and "update_check" (installing an update is the user's own). Everything else: invoke.
Sign the app's Chats in (the user's own accounts; a token is never copied from one program to another): provider_signin {verb: "status"} lists the providers, their methods and what is signed in. A login: provider_signin {verb: "start", provider, method: "oauth"} answers its attempt and auth ids; {verb: "open", attempt, auth, browser: "external"} opens its page in the user's own browser, where the user approves once; {verb: "poll", attempt, auth} until it is done; {verb: "commit", attempt, auth} keeps it; status then shows it verified (it is signed in only once verified). On a server (no browser here): open answers the link instead; give it to the user, who approves on any device and gives you the code it shows; {verb: "submit", attempt, auth, prompt, secret: <the code>} (sent on stdin). Claude's plan login (Claude Code's own, as setup run's logins): invoke {verb: "modules_call", module: "agent", method: "claude_code_signin", args: {op: "start"}} answers its attemptId; {op: "status", attemptId} names its authUrl: the user opens it, signs in and is shown a code; {op: "submit", attemptId, code}; {op: "status", attemptId} until state done, its account named. An API key: provider_keys {verb: "add_from_env", provider, from_env: <variable>} reads it from your own environment (the user exports it, e.g. OPENROUTER_API_KEY): it never passes through your model; add_from_file reads a 0600 file.
Screens: screenshot answers the Wazza OS window's own picture (its virtual screen, or on a desktop the app's own window); native_input begin, then focus/pointer/click/key/text/scroll, then end, acts in that window only. Look before you click: screenshot, one action, screenshot again.

The rules#

these tools act with the user's own CLI rights: keep the user's screen as it is unless the user asked to see something (no focus, no Settings page opened on its own). A refusal names its code and why (user_only_app: Computer Control opens only by the user's own click); busy or not ready: call again in a few seconds; ui_outcome_pending (a window action still running after the CLI followed it for 5 minutes): read it with ui {verb: "outcome", outcome: <its id>}, never send the action again. Destructive verbs (delete, reset, remove_all, quit...) only when the user asked for exactly that. pro and wazza_tools runs spend Wazza Pro credits.

The 41 tools#

status start check version ui vm vm_memory vm_disk vm_gpu gpu vm_resources data app explorer drive chat_transcript chat_queue chat_model schedule crew_run tool_queue timeouts local_services dev_servers clipboard setup token_stats provider_keys provider_signin wazza_account wazza_llm copilot wazza_tools pro pro_input invoke screenshot record host_app native_input quit

`status`#

Whether the Wazza OS app is running on this computer and its main window's state (visible, focused, its virtual screen). Call it first: an error means the Wazza OS app is not running (start starts it, unless the user said not to).

verb	arguments	what it does	example
-	-	the running app's window state	`{}` → `wazza --gui status`

`start`#

Start the Wazza OS app when it is not running (CLI wazza start): on a desktop as the user's own start (its window on the user's screen), with no display (a server, SSH) on its own virtual screen, the manual's server mode. Already running: it says so and starts nothing. It waits until the app answers (timeout, default 120 s) and answers its window state as status does. Call it when status says the app is not running, unless the user said not to start it.

verb	arguments	what it does	example
-	`timeout` (optional): how long to wait for the app to answer, in seconds (5 to 600; default 120)	start the Wazza OS app (or say it already runs) and answer its window state	`{}` → `wazza start`

`check`#

What this computer gives Wazza OS (KVM, a systemd user session, X11, the Chat sandbox, the GPU) and how to fix what is missing; works with the Wazza OS app stopped. Exit status 1 when something is missing.

verb	arguments	what it does	example
-	`json` (optional): answer in JSON instead of words	the computer check	`{"json":true}` → `wazza --check --json`

`version`#

The installed Wazza OS version (works with the Wazza OS app stopped). The running build and the installed package, side by side: ui {action: "version_read"}.

verb	arguments	what it does	example
-	-	the version	`{}` → `wazza --version`

`ui`#

The Wazza OS app's window actions (the CLI's wazza --gui invoke modules_call ui do): open apps in tabs, read tabs and what the user sees, send to a tab's Chat, read Chats, settings, updates and 200 more. They run as the user's own CLI: keep the user's view as it is unless the user asked to see something (open_app opens in a background tab unless focus: true; focus_tab, open_settings and the like change the screen). Most used actions (args): open_app {appId, vmId?, url?, file?}; app_open_in_vm {appId, vm}; vm_tabs_read {vm}; tabs_read {vmId?}; view_read {}; close_tab {tabId, vmId}; tab_rename {tabId, title}; tab_open_with {vmId, path}; chat_send {vmId, tabId, childId: "", text} (childId is required: "" is the tab's own Chat, a subagent's id comes from chat_subagent_list; a tab whose Chat never started starts it behind the view); chat_stop {vmId, tabId}; chat_set_model {vmId, tabId, modelId}; chat_list_threads {vmId, tabId}; chat_conversation_read {vmId, tabId, last?}; chat_default_read {}; chat_default_set {harnessId, modelId}; vm_list {}; vm_start {vm}; start_sandbox {}; settings_get {}; skills_native_read {}; version_read {}; update_read {}; update_check {}. Every action with its arguments: verb catalog. A refusal names its code (user_only_app: Computer Control opens only by the user's own click). A slow action (open_app while its VM is busy) is followed until the window reports it, up to 5 minutes; an answer that still says ui_outcome_pending names its outcome id: read it with verb outcome {outcome: <that id>} (again until it is no longer pending), never by sending the action again.

verb	arguments	what it does	example
do	`action`: the action's id (verb catalog lists them) `args` (optional): the action's arguments (its catalog schema) `timeout_ms` (optional): how long the window's answer is awaited before it is followed (ms, at most 25000; default the action's own)	run one window action (its answer is followed until the window reports it)	`{"verb":"do","action":"open_app","args":{"appId":"files","vmId":"vm-1"}}` → `wazza --gui invoke modules_call ui do -`
outcome	`outcome`: the outcome id a ui_outcome_pending answer names `timeout_ms` (optional): how long to wait for it now (ms, at most 25000)	what a window action that answered ui_outcome_pending did, once the window reports it	`{"verb":"outcome","outcome":"fc674edf422d2a11937349f7ff8c108d","timeout_ms":20000}` → `wazza --gui invoke modules_call ui outcome -`
catalog	-	every action with its summary, view class and argument schema	`{"verb":"catalog"}` → `wazza --gui invoke modules_call ui catalog -`

`vm`#

Wazza OS's virtual machines by number: vm-1 starts with the Wazza OS app, vm-2 to vm-8 are extra ones (CLI wazza --gui vm). A cold start takes minutes: watch verb list. Use delete, reset and restore with into only when the user asked for exactly that: they remove a disk for good.

verb	arguments	what it does	example
list	-	every VM: running, starting or stopped, its disk	`{"verb":"list"}` → `wazza --gui vm list`
create	-	a new VM, stopped, with the lowest free number	`{"verb":"create"}` → `wazza --gui vm create`
start	`vm`: the VM by number: vm-1 to vm-8	start a stopped VM (vm-2 to vm-8; vm-1 starts with the Wazza OS app, or ui {action: "start_sandbox"})	`{"verb":"start","vm":"vm-2"}` → `wazza --gui vm start vm-2`
stop	`vm`: the VM by number: vm-1 to vm-8	stop a running VM (its apps end; its disk is kept) (removes or ends something)	`{"verb":"stop","vm":"vm-2"}` → `wazza --gui vm stop vm-2`
delete	`vm`: the VM by number: vm-1 to vm-8 `yes`: true: you mean it (the disk goes for good)	remove a stopped VM and its disk for good (removes or ends something)	`{"verb":"delete","vm":"vm-3","yes":true}` → `wazza --gui vm delete vm-3 --yes`
reset	`vm`: the VM by number: vm-1 to vm-8 `yes`: true: you mean it (the disk goes for good)	make a stopped VM new: its disk removed for good, its number kept (removes or ends something)	`{"verb":"reset","vm":"vm-3","yes":true}` → `wazza --gui vm reset vm-3 --yes`
backup	`vm`: the VM by number: vm-1 to vm-8	a backup zip of a VM in Downloads	`{"verb":"backup","vm":"vm-2"}` → `wazza --gui vm backup vm-2`
backups	-	the backups and the backup job that runs	`{"verb":"backups"}` → `wazza --gui vm backups`
restore	`backup`: a backup's id (verb backups) or the path of its .zip `into` (optional): a stopped VM whose disk the backup replaces for good `yes` (optional): true with into: you mean it	a new VM from a backup; with into and yes, replace a stopped VM's disk (removes or ends something)	`{"verb":"restore","backup":"bk-1"}` → `wazza --gui vm restore bk-1`

`vm_memory`#

A VM's RAM (CLI wazza --gui vm-memory): read it, set it, or let Wazza OS scale it automatically.

verb	arguments	what it does	example
status	`vm` (optional): the VM by number: vm-1 (the default) to vm-8	the VM's RAM now, its bounds and the policy	`{"verb":"status"}` → `wazza --gui vm-memory status`
set	`mib`: the RAM in MiB `vm` (optional): the VM by number: vm-1 (the default) to vm-8	give the VM this much RAM now (live)	`{"verb":"set","mib":8192,"vm":"vm-1"}` → `wazza --gui vm-memory set 8192 --vm vm-1`
auto	`percent`: the share of this computer's RAM auto-scale may give (10-100) `min` (optional): the least RAM in MiB	let Wazza OS scale the RAM to what the VM needs	`{"verb":"auto","percent":50}` → `wazza --gui vm-memory auto 50`
min	`mib`: the least RAM in MiB	the least RAM auto-scale keeps	`{"verb":"min","mib":4096}` → `wazza --gui vm-memory min 4096`

`vm_disk`#

A VM's root disk (CLI wazza --gui vm-disk): its size and free room; grow it (it never shrinks back).

verb	arguments	what it does	example
status	`vm` (optional): the VM by number: vm-1 (the default) to vm-8	the disk's size, use and target	`{"verb":"status"}` → `wazza --gui vm-disk status`
set	`gib`: the new size in GiB `vm` (optional): the VM by number: vm-1 (the default) to vm-8	grow the disk to this size (uses this computer's disk; it never shrinks back)	`{"verb":"set","gib":80}` → `wazza --gui vm-disk set 80`

`vm_gpu`#

The GPU memory Wazza OS's VMs may use (CLI wazza --gui vm-gpu).

verb	arguments	what it does	example
status	-	each VM's GPU memory and the bound	`{"verb":"status"}` → `wazza --gui vm-gpu status`
auto	`percent`: the share of the GPU's memory	scale it automatically	`{"verb":"auto","percent":50}` → `wazza --gui vm-gpu auto 50`
set	`mib`: the GPU memory in MiB	a fixed GPU memory	`{"verb":"set","mib":2048}` → `wazza --gui vm-gpu set 2048`

`gpu`#

How the VMs use this computer's graphics cards (CLI wazza --gui gpu; Settings › Graphics): virtualized, a native card lent to a VM, or none.

verb	arguments	what it does	example
status	-	the mode, the cards and each VM's paths	`{"verb":"status"}` → `wazza --gui gpu status`
mode	`mode`: the GPU mode	set the GPU mode	`{"verb":"mode","mode":"virtualized"}` → `wazza --gui gpu mode virtualized`
card	`card`: auto, auto:N[:API], or PCI addresses PCI[,PCI...]	which card native mode lends	`{"verb":"card","card":"auto"}` → `wazza --gui gpu card auto`

`vm_resources`#

What a VM has now and the most auto-scale gives it (vCPUs, RAM, GPU, disk) and this computer's CPUs, load, RAM, GPUs and free disk (CLI wazza --gui vm-resources). Read it before a render, a build or a large install.

verb	arguments	what it does	example
-	`vm` (optional): the VM by number: vm-1 (the default) to vm-8	the resources	`{"vm":"vm-1"}` → `wazza --gui vm-resources --vm vm-1`

`data`#

Wazza OS's own data on this computer (CLI wazza --gui data). remove_all removes ALL of it (VMs, settings, sign-ins, Chats, logs, caches) for good at the next start: only when the user asked for exactly that, with the typed words.

verb	arguments	what it does	example
status	-	Wazza OS's folders, their sizes, a waiting removal	`{"verb":"status"}` → `wazza --gui data status`
remove_all	`confirm`: exactly REMOVE ALL DATA	remove all of Wazza OS's data (the Wazza OS app closes) (removes or ends something)	`{"verb":"remove_all","confirm":"REMOVE ALL DATA"}` → `wazza --gui data remove-all --confirm 'REMOVE ALL DATA'`
cancel	-	cancel a removal still waiting for the next start	`{"verb":"cancel"}` → `wazza --gui data cancel`

`app`#

Apps of Wazza OS's catalog and the user's own (CLI wazza --gui app): list, read and check manifests, install state, save a custom app, uninstall, follow and cancel jobs, an app's MCP, templates. Open an app in a tab: ui {action: "open_app"}. Install a catalog app on the VM shown: ui {action: "open_app"} opens and installs it, or invoke {verb: "modules_call", module: "packages", method: "install_request", args: {appId, vmId}}.

verb	arguments	what it does	example
list	-	the app catalog	`{"verb":"list"}` → `wazza --gui app list`
get	`app_id`: the app's id (app {verb: "list"} lists them: gimp, vscodium...)	an app's manifest	`{"verb":"get","app_id":"gimp"}` → `wazza --gui app get gimp`
validate	`manifest`: the manifest (with its skill files) to check	check a manifest; its errors by cause	`{"verb":"validate","manifest":{"manifest":{"name":"Hello"}}}` → `wazza --gui app validate --stdin`
status	`app_id`: the app's id (app {verb: "list"} lists them: gimp, vscodium...) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `refresh` (optional): check it again in the VM now	whether an app is installed in a VM, installing, or why not	`{"verb":"status","app_id":"gimp","vm":"vm-1"}` → `wazza --gui app status gimp --vm vm-1`
save	`manifest`: {manifest, skills, expectedRevision?} `install` (optional): install it once saved `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `focus` (optional): show it on the user's screen (changes what the user sees: only when the user asked)	save a custom app (new, or a new revision)	`{"verb":"save","manifest":{"manifest":{"name":"Hello"}},"install":true}` → `wazza --gui app save --stdin --install`
uninstall	`app_id`: the app's id (app {verb: "list"} lists them: gimp, vscodium...) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `close_tabs` (optional): close its open tabs first `purge_data` (optional): remove its user data too `focus` (optional): show it on the user's screen (changes what the user sees: only when the user asked) `follow` (optional): wait and print the job's output until it ends (minutes for an install)	uninstall an app from a VM (removes or ends something)	`{"verb":"uninstall","app_id":"gimp","vm":"vm-1"}` → `wazza --gui app uninstall gimp --vm vm-1`
uninstall_plan	`app_id`: the app's id (app {verb: "list"} lists them: gimp, vscodium...) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `close_tabs` (optional): with closing its open tabs `purge_data` (optional): with removing its user data	what an uninstall would remove	`{"verb":"uninstall_plan","app_id":"gimp"}` → `wazza --gui app uninstall-plan gimp`
remove	`app_id`: the app's id (app {verb: "list"} lists them: gimp, vscodium...) `forget_vm` (optional): VMs whose record of it goes too	remove a custom app from Wazza OS (removes or ends something)	`{"verb":"remove","app_id":"custom-0123abcd"}` → `wazza --gui app remove custom-0123abcd`
observe	`job_id`: the job's id an install, uninstall or MCP request answered `since` (optional): the output offset to read from (the last answer's next) `follow` (optional): wait and print the job's output until it ends (minutes for an install)	a job's state and output	`{"verb":"observe","job_id":"job-1","since":0}` → `wazza --gui app observe job-1 --since 0`
cancel	`job_id`: the job's id an install, uninstall or MCP request answered `focus` (optional): show it on the user's screen (changes what the user sees: only when the user asked)	cancel an app job	`{"verb":"cancel","job_id":"job-1"}` → `wazza --gui app cancel job-1`
mcp_install	`app_id`: the app's id (app {verb: "list"} lists them: gimp, vscodium...) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `follow` (optional): wait and print the job's output until it ends (minutes for an install)	install an app's MCP in a VM (its Chats list its tools again)	`{"verb":"mcp_install","app_id":"gimp"}` → `wazza --gui app mcp-install gimp`
mcp_uninstall	`app_id`: the app's id (app {verb: "list"} lists them: gimp, vscodium...) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `follow` (optional): wait and print the job's output until it ends (minutes for an install)	remove an app's MCP from a VM	`{"verb":"mcp_uninstall","app_id":"gimp"}` → `wazza --gui app mcp-uninstall gimp`
template	`kind`: an apt package app or a script app `mcp` (optional): with a headless MCP server `skill` (optional): with a SKILL.md	a manifest template to fill	`{"verb":"template","kind":"apt","skill":true}` → `wazza --gui app template apt --skill`

`explorer`#

Files (CLI wazza --gui explorer): a VM's files (list, rename, move, delete, permissions, stage one for reading on this computer, its default app), this computer's home (list, details, open, search, read with computer: true), and copies between this computer and the VMs. Changes act only on the item a fresh list named (expect); delete is permanent (yes).

verb	arguments	what it does	example
list	`path` (optional): a folder (default the home) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `computer` (optional): this computer's home instead of a VM	a folder's entries with their ids	`{"verb":"list","path":"~/Documents"}` → `wazza --gui explorer list ~/Documents`
rename	`path`: a path in the VM: ~/... (the VM's home), absolute, or relative to the Chat folder; vm-N:/... names the VM `new_name`: the new name `expect` (optional): the item's id from a fresh explorer list: the change acts only on that very item `vm` (optional): the VM by number: vm-1 (the default) to vm-8	rename one item	`{"verb":"rename","path":"~/a.txt","new_name":"b.txt"}` → `wazza --gui explorer rename ~/a.txt b.txt`
move	`path`: a path in the VM: ~/... (the VM's home), absolute, or relative to the Chat folder; vm-N:/... names the VM `target_folder`: the folder it moves into `name` (optional): a new name there `expect` (optional): the item's id from a fresh explorer list: the change acts only on that very item `vm` (optional): the VM by number: vm-1 (the default) to vm-8	move one item	`{"verb":"move","path":"~/a.txt","target_folder":"~/Documents"}` → `wazza --gui explorer move ~/a.txt ~/Documents`
delete	`path`: a path in the VM: ~/... (the VM's home), absolute, or relative to the Chat folder; vm-N:/... names the VM `yes`: true: you mean it (there is no trash) `expect` (optional): the item's id from a fresh explorer list: the change acts only on that very item `vm` (optional): the VM by number: vm-1 (the default) to vm-8	delete one item for good (a folder only when empty) (removes or ends something)	`{"verb":"delete","path":"~/old.txt","yes":true}` → `wazza --gui explorer delete ~/old.txt --yes`
permissions	`path`: a path in the VM: ~/... (the VM's home), absolute, or relative to the Chat folder; vm-N:/... names the VM `mode`: chmod's three octal digits (644, 755) `recursive` (optional): a folder's items too `expect` (optional): the item's id from a fresh explorer list: the change acts only on that very item `vm` (optional): the VM by number: vm-1 (the default) to vm-8	change an item's permissions	`{"verb":"permissions","path":"~/run.sh","mode":"755"}` → `wazza --gui explorer permissions ~/run.sh 755`
stage	`path`: a path in the VM: ~/... (the VM's home), absolute, or relative to the Chat folder; vm-N:/... names the VM `vm` (optional): the VM by number: vm-1 (the default) to vm-8	copy one VM file into Wazza's share and print its path on this computer (to read or preview it)	`{"verb":"stage","path":"~/Pictures/a.png"}` → `wazza --gui explorer stage ~/Pictures/a.png`
default_app	`path`: a path in the VM: ~/... (the VM's home), absolute, or relative to the Chat folder; vm-N:/... names the VM `vm` (optional): the VM by number: vm-1 (the default) to vm-8	the Wazza OS app the VM opens that file with	`{"verb":"default_app","path":"~/a.svg"}` → `wazza --gui explorer default-app ~/a.svg`
details	`path`: a path in this computer's home (~/..., computer:~/...) `computer` (optional): true: this computer's home	one entry of this computer's home	`{"verb":"details","path":"~/a.txt","computer":true}` → `wazza --gui explorer details ~/a.txt --computer`
open	`path`: a path in this computer's home `computer` (optional): true: this computer's home	open a file of this computer with its default app (on the user's screen: only when asked)	`{"verb":"open","path":"~/a.pdf","computer":true}` → `wazza --gui explorer open ~/a.pdf --computer`
import	`path`: a file or folder of this computer's home `vm` (optional): the VM by number: vm-1 (the default) to vm-8	copy a file of this computer into the VM's ~/Downloads (run again to see how far it went)	`{"verb":"import","path":"~/a.pdf"}` → `wazza --gui explorer import ~/a.pdf`
transfer	`from` (optional): host or vm-N (default host) `to` (optional): host or vm-N (default host) `folder` (optional): the folder it pastes into `id` (optional): a transfer's id: its progress (or cancel it) `cancel` (optional): with id: stop that transfer `paths` (optional): the files and folders to copy	copy files between this computer and a VM, or between VMs; with id, its progress	`{"verb":"transfer","to":"vm-1","folder":"~/Downloads","paths":["~/a.pdf"]}` → `wazza --gui explorer transfer --to vm-1 --folder ~/Downloads ~/a.pdf`
clipboard_copy	`from` (optional): host or vm-N (default host) `id` (optional): a copy's id: its state `paths` (optional): the files to put on Wazza OS's file clipboard	copy files onto Wazza OS's file clipboard	`{"verb":"clipboard_copy","paths":["~/a.pdf"]}` → `wazza --gui explorer clipboard-copy ~/a.pdf`
clipboard_paste	`to` (optional): host or vm-N (default host) `folder` (optional): the folder it pastes into `id` (optional): a paste's id: its state	paste the file clipboard into a folder	`{"verb":"clipboard_paste","to":"vm-1","folder":"~/Downloads"}` → `wazza --gui explorer clipboard-paste --to vm-1 --folder ~/Downloads`
search	`words`: the words to find in file names `computer`: true: this computer's home `in` (optional): a folder to search in `limit` (optional): the most results	find files of this computer's home by name	`{"verb":"search","words":["invoice"],"computer":true}` → `wazza --gui explorer search invoice --computer`
read	`path`: a file of this computer's home `computer`: true: this computer's home `offset` (optional): the byte to start at `length` (optional): how many bytes	read a file of this computer's home	`{"verb":"read","path":"~/notes.txt","computer":true}` → `wazza --gui explorer read ~/notes.txt --computer`
copy_to_vm	`paths`: files of this computer `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `folder` (optional): the VM folder (default ~/Downloads)	copy files of this computer into a VM (the user's file copy permission applies)	`{"verb":"copy_to_vm","paths":["~/a.pdf"],"vm":"vm-1"}` → `wazza --gui explorer copy-to-vm ~/a.pdf --vm vm-1`
upload	`vm_paths`: files of the VM `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `folder` (optional): the folder of this computer (default Downloads)	copy VM files to this computer (never overwrites: a new name when taken)	`{"verb":"upload","vm_paths":["~/render.png"]}` → `wazza --gui explorer upload ~/render.png`
replace	`vm_path`: the VM file `target`: the file of this computer it replaces (one Wazza OS made) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	replace a file of this computer that Wazza OS made with a VM file	`{"verb":"replace","vm_path":"~/a.png","target":"~/Downloads/a.png"}` → `wazza --gui explorer replace ~/a.png ~/Downloads/a.png`
copies	`id`: a copy's id (copy_to_vm or upload answered it)	how far a copy went	`{"verb":"copies","id":"cp-1"}` → `wazza --gui explorer copies --id cp-1`

`drive`#

Drive: see and use an app's window in a tab like a person does (CLI wazza --gui drive and wazza --gui invoke modules_call drive). look returns one image of the tab and a snapshot_id; act runs ONE action on it (x, y are pixels of that image) and returns the next view: check it before the next act. Actions (args.action): left_click, double_click, right_click, left_click_drag (x2, y2), scroll, type_text (text, ASCII), paste_utf8 (text), key (keys: ["ctrl+s"]), key_chord, hold_key, wait (until: "changed"). Refusals: stale_snapshot (look again), user_input_active (the user types: wait, look again), input_locked_by_user (ask the user to unlock the tab). context lists what the tab offers; recover restarts a stuck tab's Drive.

verb	arguments	what it does	example
look	`vm`: the tab's VM (vm-1...) `tab`: the tab's id `args` (optional): Drive's look fields: mode ("lean"), zoom [x, y, w, h], ...	one image of the tab and its snapshot_id (single use, 300 s)	`{"verb":"look","vm":"vm-1","tab":"t2","args":{"mode":"lean"}}` → `wazza --gui invoke modules_call drive look - --image-out '<images>'`
act	`vm`: the tab's VM `tab`: the tab's id `args`: Drive's act fields: snapshot_id, action, x, y, text, keys, ...	one action on the last look, then the next view	`{"verb":"act","vm":"vm-1","tab":"t2","args":{"snapshot_id":"s1","action":"left_click","x":40,"y":60}}` → `wazza --gui invoke modules_call drive act - --image-out '<images>'`
context	`vm`: the tab's VM `tab`: the tab's id	what Drive can do on the tab now (its seats, whether it is in view)	`{"verb":"context","vm":"vm-1","tab":"t2"}` → `wazza --gui invoke modules_call drive context -`
record	`vm`: the tab's VM `tab`: the tab's id `args`: op: start \| stop \| status \| release, recording_id	record the tab (start, then stop with its recording_id)	`{"verb":"record","vm":"vm-1","tab":"t2","args":{"op":"start"}}` → `wazza --gui invoke modules_call drive record - --image-out '<images>'`
evidence	`vm`: the tab's VM `tab`: the tab's id `args`: op: status \| export \| keep \| retire	the before/after images Drive kept of a tab's Chat	`{"verb":"evidence","vm":"vm-1","tab":"t2","args":{"op":"status"}}` → `wazza --gui invoke modules_call drive evidence -`
recover	`tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	restart a tab's stuck Drive (no input, no view change)	`{"verb":"recover","tab":"t2"}` → `wazza --gui drive recover --tab t2`

`chat_transcript`#

Read one tab's Chat conversation whole (CLI wazza --gui chat-transcript): the user's messages and each answer's message, thinking, tool and bash entries, oldest first. Send to a Chat with ui {action: "chat_send"}, then read its answer here (last: 5).

verb	arguments	what it does	example
-	`tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `thread` (optional): one of the Chat's threads (default the selected one) `kinds` (optional): comma list of user,message,thinking,tool,bash,error `roles` (optional): comma list of user,assistant `contains` (optional): only entries with this text (any case) `from` (optional): entries from this number on `last` (optional): only the newest N entries	the conversation	`{"tab":"t2","vm":"vm-1","last":5}` → `wazza --gui chat-transcript --tab t2 --vm vm-1 --last 5`

`chat_queue`#

The messages queued while a tab's Chat answers (CLI wazza --gui chat-queue): list, edit, discard.

verb	arguments	what it does	example
list	`tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	the queued messages with their ids	`{"verb":"list","tab":"t2"}` → `wazza --gui chat-queue list --tab t2`
edit	`id`: the item's id from list (key:revision) `text`: the new text `tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	replace a queued message's text	`{"verb":"edit","id":"q1:2","text":"hello","tab":"t2"}` → `wazza --gui chat-queue edit q1:2 --stdin --tab t2`
discard	`id`: the item's id from list `tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	drop a queued message	`{"verb":"discard","id":"q1:2","tab":"t2"}` → `wazza --gui chat-queue discard q1:2 --tab t2`

`chat_model`#

The model every new Chat starts on (CLI wazza --gui chat-model). One tab's own Chat: ui {action: "chat_set_model"}.

verb	arguments	what it does	example
status	-	the model new Chats start on	`{"verb":"status"}` → `wazza --gui chat-model status`
set	`model`: the model's id	set it	`{"verb":"set","model":"xiaomi/mimo-v2-flash"}` → `wazza --gui chat-model set xiaomi/mimo-v2-flash`

`schedule`#

The Chats' scheduled messages (CLI wazza --gui schedule): list them, cancel one.

verb	arguments	what it does	example
list	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `tab` (optional): the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs)	scheduled messages, soonest first	`{"verb":"list"}` → `wazza --gui schedule list`
cancel	`id`: its id (sch-...)	cancel one	`{"verb":"cancel","id":"sch-01ab"}` → `wazza --gui schedule cancel sch-01ab`

`crew_run`#

A tab Chat's crew run record (CLI wazza --gui crew-run): its plan, its agents and their results.

verb	arguments	what it does	example
-	`tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	the record	`{"tab":"t2"}` → `wazza --gui crew-run --tab t2`

`tool_queue`#

The Chats' tool call queues (CLI wazza --gui tool-queue): list, status, graph, move items, cancel.

verb	arguments	what it does	example
list	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `tab` (optional): the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs)	every queue	`{"verb":"list"}` → `wazza --gui tool-queue list`
status	`queue`: the queue's id (q1, q2...: list names them)	one queue's items	`{"verb":"status","queue":"q1"}` → `wazza --gui tool-queue status q1`
graph	`queue`: the queue's id (q1, q2...: list names them)	its items' order and links	`{"verb":"graph","queue":"q1"}` → `wazza --gui tool-queue graph q1`
transfer	`queue`: the queue's id (q1, q2...: list names them) `items`: rest, or item ids a,b,c (status lists them) `to` (optional): the queue they move into	move items to another queue	`{"verb":"transfer","queue":"q1","items":"rest","to":"q2"}` → `wazza --gui tool-queue transfer q1 rest --to q2`
cancel	`queue`: the queue's id (q1, q2...: list names them) `items` (optional): item ids a,b,c (default the whole queue)	cancel a queue or some of its items	`{"verb":"cancel","queue":"q1"}` → `wazza --gui tool-queue cancel q1`

`timeouts`#

How long one tool call and one command of a Chat may run before Wazza OS stops it (CLI wazza --gui timeouts; Settings › Agent).

verb	arguments	what it does	example
status	-	both timeouts	`{"verb":"status"}` → `wazza --gui timeouts status`
set	`tool` (optional): seconds for one tool call (10-1800) `command` (optional): seconds for one command (10-7200)	change them	`{"verb":"set","tool":120}` → `wazza --gui timeouts set --tool 120`

`local_services`#

Whether Chats on this computer may reach its local services (dev servers, databases) (CLI wazza --gui local-services): globally, or one tab's Chat.

verb	arguments	what it does	example
status	`tab` (optional): the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	the choice	`{"verb":"status"}` → `wazza --gui local-services status`
on	`tab` (optional): the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	let them reach local services	`{"verb":"on"}` → `wazza --gui local-services on`
off	`tab` (optional): the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	keep them off	`{"verb":"off"}` → `wazza --gui local-services off`
follow	`tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	a tab's Chat follows the global choice again	`{"verb":"follow","tab":"t2"}` → `wazza --gui local-services follow --tab t2`

`dev_servers`#

The dev servers Chats on this computer started, forwarded to this computer's localhost (CLI wazza --gui dev-servers).

verb	arguments	what it does	example
-	`tab` (optional): the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	their URLs	`{}` → `wazza --gui dev-servers`

`clipboard`#

The VM clipboard and the file copy permissions between this computer and the VMs (CLI wazza --gui clipboard).

verb	arguments	what it does	example
status	`vm` (optional): the VM by number: vm-1 (the default) to vm-8	the clipboard's state	`{"verb":"status"}` → `wazza --gui clipboard status`
copy	`text`: the text to copy `guest_only` (optional): the VM's clipboard only `vm` (optional): the VM by number: vm-1 (the default) to vm-8	put text on the clipboard	`{"verb":"copy","text":"hello"}` → `wazza --gui clipboard copy --stdin`
files	`to_vm` (optional): copies of this computer's files into a VM `to_computer` (optional): copies of VM files onto this computer	read (no argument) or set the file copy permissions	`{"verb":"files"}` → `wazza --gui clipboard files`
files_allow	`request`: the waiting copy's id	allow one copy waiting under ask	`{"verb":"files_allow","request":"r1"}` → `wazza --gui clipboard files allow r1`
files_deny	`request`: the waiting copy's id	deny one copy waiting under ask	`{"verb":"files_deny","request":"r1"}` → `wazza --gui clipboard files deny r1`

`setup`#

Wazza OS's first setup (CLI wazza --gui setup): its state, a whole setup from a file (sign-ins, keys, VM resources...), or the first-run step shown again at the next start.

verb	arguments	what it does	example
status	`json` (optional): answer in JSON instead of words	what is set up	`{"verb":"status","json":true}` → `wazza --gui setup status --json`
run	`file` (optional): a setup file's path `setup_file` (optional): the setup file's text itself `json` (optional): answer in JSON instead of words	run a setup file: file (its path, e.g. ~/wazza-setup.json) or setup_file (its text); its fields: account, logins, keys, whenOneRunsOut, apps, vm, appearance, tabs	`{"verb":"run","setup_file":"{\"appearance\":{\"theme\":\"dark\"}}"}` → `wazza --gui setup run --file -`
reset_first_run	-	show the first-run step again at the next start	`{"verb":"reset_first_run"}` → `wazza --gui setup reset-first-run`

`token_stats`#

The tokens every answer used, by model (CLI wazza --gui token-stats; Sign In's table).

verb	arguments	what it does	example
show	-	the table	`{"verb":"show"}` → `wazza --gui token-stats`
reset	-	start the counts again	`{"verb":"reset"}` → `wazza --gui token-stats reset`

`provider_keys`#

API keys of Wazza OS's providers (CLI wazza --gui provider-keys): list, add (usable in every Chat at once), remove, rename. Add a key with add_from_env (recommended): the CLI reads it from an environment variable of this MCP server (the agent's own environment, e.g. OPENROUTER_API_KEY set by the user), so the key never passes through your model; add_from_file reads it from the user's file of mode 0600. add takes keys you were given as text (they pass through your model: only when the user gave them to you). Keys travel only on stdin or from those sources, never argv, and are never shown back.

verb	arguments	what it does	example
list	`credit` (optional): with each key's credit	the providers and their keys (never the key itself)	`{"verb":"list"}` → `wazza --gui provider-keys list`
add_from_env	`provider`: the provider's id (list names them: openrouter...) `from_env`: the name of the environment variable that holds the key (this MCP server's environment) `name` (optional): the key's name on the Sign in page (0 to 40 characters)	add one key, read by the CLI from an environment variable (recommended: never through your model)	`{"verb":"add_from_env","provider":"openrouter","from_env":"OPENROUTER_API_KEY"}` → `wazza --gui provider-keys add --provider openrouter --from-env OPENROUTER_API_KEY`
add_from_file	`provider`: the provider's id (list names them: openrouter...) `from_file`: the path of the user's file that holds the key: one line, mode 0600, owned by the user `name` (optional): the key's name on the Sign in page (0 to 40 characters)	add one key, read by the CLI from a 0600 file (never through your model)	`{"verb":"add_from_file","provider":"openrouter","from_file":"keys/openrouter.key"}` → `wazza --gui provider-keys add --provider openrouter --from-file keys/openrouter.key`
add	`keys`: {"keys": [{"providerId", "key", "name"?}]}	add keys given as text (they pass through your model: prefer add_from_env)	`{"verb":"add","keys":{"keys":[{"providerId":"openrouter","key":"(the key)"}]}}` → `wazza --gui provider-keys add --stdin`
remove	`providers`: the providers whose keys go	remove every key of these providers (removes or ends something)	`{"verb":"remove","providers":["openrouter"]}` → `wazza --gui provider-keys remove openrouter`
remove_key	`provider`: the provider `key_id`: the key's id from list	remove one key (removes or ends something)	`{"verb":"remove_key","provider":"openrouter","key_id":"k1"}` → `wazza --gui provider-keys remove-key --provider openrouter --key k1`
rename	`provider`: the provider `key_id`: the key's id from list `name`: its new name (0 to 40 characters)	name a key	`{"verb":"rename","provider":"openrouter","key_id":"k1","name":"work"}` → `wazza --gui provider-keys rename --provider openrouter --key k1 --name work`

`provider_signin`#

Sign-ins of Wazza OS's providers and logins (CLI wazza --gui provider-signin): status, start an OAuth or key sign-in, poll it, open its page, submit a code (stdin), commit, cancel, sign out; the order of a provider's keys or a login's accounts and when one runs out (rotation). Every op takes the same optional flags (vm, provider, method, attempt, auth, browser, prompt, validation_model, account); start names provider and method, the next steps the attempt and auth ids start answered.

verb	arguments	what it does	example
status	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login `refresh` (optional): read them again now	every sign-in's state	`{"verb":"status"}` → `wazza --gui provider-signin status`
custom_apis	-	the saved custom APIs	`{"verb":"custom_apis"}` → `wazza --gui provider-signin custom-apis`
start	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login	start a sign-in (provider, method): its attempt and auth ids	`{"verb":"start","provider":"openrouter","method":"oauth"}` → `wazza --gui provider-signin start --provider openrouter --method oauth`
poll	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login	how a sign-in goes (attempt, auth)	`{"verb":"poll","attempt":"a1","auth":"u1"}` → `wazza --gui provider-signin poll --attempt a1 --auth u1`
open	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login `focus` (optional): show it on the user's screen (changes what the user sees: only when the user asked)	open a sign-in's page (attempt, auth; browser external and chrome are on the user's screen)	`{"verb":"open","attempt":"a1","auth":"u1","browser":"in-app"}` → `wazza --gui provider-signin open --attempt a1 --auth u1 --browser in-app`
submit	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login `secret`: the code or key (one line)	answer a sign-in's prompt (attempt, auth, prompt) with a code or key	`{"verb":"submit","attempt":"a1","auth":"u1","prompt":"p1","secret":"(the code)"}` → `wazza --gui provider-signin submit --attempt a1 --auth u1 --prompt p1 --secret-stdin`
commit	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login	keep a finished sign-in (attempt, auth)	`{"verb":"commit","attempt":"a1","auth":"u1"}` → `wazza --gui provider-signin commit --attempt a1 --auth u1`
cancel	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login	cancel a sign-in (attempt, auth)	`{"verb":"cancel","attempt":"a1","auth":"u1"}` → `wazza --gui provider-signin cancel --attempt a1 --auth u1`
sign_out	`vm` (optional): the VM by number: vm-1 (the default) to vm-8 `provider` (optional): the provider's id (openrouter...) `method` (optional): the sign-in method's id (oauth, key...) `attempt` (optional): the attempt id start answered `auth` (optional): the auth id start answered `browser` (optional): where a sign-in page opens (external and chrome are on the user's screen) `prompt` (optional): the prompt id a submit answers `validation_model` (optional): the model a key's check uses `account` (optional): one account of a login	sign a provider out (provider; method or account for one of them) (removes or ends something)	`{"verb":"sign_out","provider":"openrouter"}` → `wazza --gui provider-signin sign-out --provider openrouter`
order	`provider`: a provider, or the login claude or chatgpt `ids`: its keys' or accounts' ids, comma separated, first first	the order its keys or accounts are used in	`{"verb":"order","provider":"openrouter","ids":"k2,k1"}` → `wazza --gui provider-signin order --provider openrouter --ids k2,k1`
rotation	`provider`: a provider, or the login claude or chatgpt `mode`: which key or account is used next	when one runs out, which is next	`{"verb":"rotation","provider":"openrouter","mode":"take_turns"}` → `wazza --gui provider-signin rotation --provider openrouter --mode take_turns`

`wazza_account`#

The user's Wazza account in Wazza OS (CLI wazza --gui wazza-account): its state, sign in and out, the website connection, and the website's MCP. Passwords and URLs travel only on stdin.

verb	arguments	what it does	example
status	-	signed in or not, the account	`{"verb":"status"}` → `wazza --gui wazza-account status`
start	-	start a browser sign-in	`{"verb":"start"}` → `wazza --gui wazza-account start`
logout	-	sign out (removes or ends something)	`{"verb":"logout"}` → `wazza --gui wazza-account logout`
login	`email`: the account's email `password`: the password	sign in with email and password	`{"verb":"login","email":"me@example.com","password":"(the password)"}` → `wazza --gui wazza-account login --email me@example.com --password-stdin`
complete	`url`: the sign-in's return URL	finish a browser sign-in	`{"verb":"complete","url":"(the URL)"}` → `wazza --gui wazza-account complete --url-stdin`
connect_start	-	start the website connection	`{"verb":"connect_start"}` → `wazza --gui wazza-account connect-start`
connect_status	-	the connection's state	`{"verb":"connect_status"}` → `wazza --gui wazza-account connect-status`
connect_logout	-	end the connection (removes or ends something)	`{"verb":"connect_logout"}` → `wazza --gui wazza-account connect-logout`
connect_complete	`url`: the connection's return URL	finish the connection	`{"verb":"connect_complete","url":"(the URL)"}` → `wazza --gui wazza-account connect-complete --url-stdin`
mcp	`method`: the website MCP's method (tools/list, tools/call...) `params` (optional): its params	call the Wazza website's MCP	`{"verb":"mcp","method":"tools/list"}` → `wazza --gui wazza-account mcp tools/list`

`wazza_llm`#

The Wazza website's LLM as Wazza OS's provider in every harness (CLI wazza --gui wazza-llm). Keys travel only on stdin.

verb	arguments	what it does	example
status	-	its state	`{"verb":"status"}` → `wazza --gui wazza-llm status`
check	-	check it again now	`{"verb":"check"}` → `wazza --gui wazza-llm check`
key_set	`key`: the API key	save its API key	`{"verb":"key_set","key":"(the key)"}` → `wazza --gui wazza-llm key-set --key-stdin`
key_clear	-	remove its API key (removes or ends something)	`{"verb":"key_clear"}` → `wazza --gui wazza-llm key-clear`

`copilot`#

GitHub Copilot as a provider (CLI wazza --gui copilot). Tokens travel only on stdin.

verb	arguments	what it does	example
status	-	its state	`{"verb":"status"}` → `wazza --gui copilot status`
check	-	check it again now	`{"verb":"check"}` → `wazza --gui copilot check`
key_set	`key`: the GitHub token	save a GitHub token	`{"verb":"key_set","key":"(the token)"}` → `wazza --gui copilot key-set --key-stdin`
key_from_gh	-	take the token of this computer's gh	`{"verb":"key_from_gh"}` → `wazza --gui copilot key-from-gh`
key_clear	-	remove the token (removes or ends something)	`{"verb":"key_clear"}` → `wazza --gui copilot key-clear`

`wazza_tools`#

The user's Wazza AI tools (images, video, audio, voice, text) from the Wazza website (CLI wazza --gui wazza-tools): catalog, describe, estimate, run, read, runs, cancel, balance. RUN SPENDS WAZZA PRO CREDITS: estimate first and run only what the user asked for. The op's fields (query, model, workflow, inputs, waitSeconds...) go in fields; read and cancel name the run's call id.

verb	arguments	what it does	example
catalog	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	the tools and models (fields: {query?})	`{"verb":"catalog","fields":{"query":"image"}}` → `wazza --gui wazza-tools catalog --args-stdin`
describe	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	one model's inputs (fields: {model})	`{"verb":"describe","fields":{"model":"m1"}}` → `wazza --gui wazza-tools describe --args-stdin`
estimate	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	what a run would cost (fields: {model, inputs})	`{"verb":"estimate","fields":{"model":"m1","inputs":{}}}` → `wazza --gui wazza-tools estimate --args-stdin`
run	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	run a tool: SPENDS WAZZA PRO CREDITS (fields: {model or workflow, inputs, waitSeconds?})	`{"verb":"run","fields":{"model":"m1","inputs":{"prompt":"a cat"}}}` → `wazza --gui wazza-tools run --args-stdin`
read	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	a run's state and files (call)	`{"verb":"read","call":"0123456789abcdef0123456789abcdef"}` → `wazza --gui wazza-tools read --call 0123456789abcdef0123456789abcdef`
runs	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	recent runs	`{"verb":"runs"}` → `wazza --gui wazza-tools runs`
cancel	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	cancel a run (call)	`{"verb":"cancel","call":"0123456789abcdef0123456789abcdef"}` → `wazza --gui wazza-tools cancel --call 0123456789abcdef0123456789abcdef`
balance	`fields` (optional): the op's fields as one object (query, model, workflow, inputs, waitSeconds...) `call` (optional): a run's call id (32 hex), for read and cancel	the credits left	`{"verb":"balance"}` → `wazza --gui wazza-tools balance`

`pro`#

A Wazza Pro tab's own app tools through that tab's Chat (CLI wazza --gui pro). A run that costs SPENDS WAZZA PRO CREDITS and needs confirm_spend: true: use it only when the user asked for that run.

verb	arguments	what it does	example
run	`tool`: the Pro tool's name (verb list) `tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `harness` (optional): the host harness of the Pro tab's Chat that runs it (claude-code, codex...); default its own `confirm_spend` (optional): true: the user agreed to spend credits on this run `arguments` (optional): the tool's arguments	run one Pro tool	`{"verb":"run","tool":"generate_image","tab":"t3","arguments":{"prompt":"a cat"}}` → `wazza --gui pro generate_image --tab t3 --args-stdin`
observe	`request_id`: the run's request id (a pending answer named it) `tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `harness` (optional): the host harness of the Pro tab's Chat that runs it (claude-code, codex...); default its own	a pending run's state	`{"verb":"observe","request_id":"r1","tab":"t3"}` → `wazza --gui pro --observe r1 --tab t3`
list	`tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8 `harness` (optional): the host harness of the Pro tab's Chat that runs it (claude-code, codex...); default its own	the Pro tab's tools	`{"verb":"list","tab":"t3"}` → `wazza --gui pro --list --tab t3`

`pro_input`#

A file of this computer given to a running Wazza Pro tab as a tool's input (CLI wazza --gui pro-input). The Pro tool that uses it spends Wazza Pro credits.

verb	arguments	what it does	example
send	`file`: the file's path `tab`: the tab's id (t1, t2...: ui {action: "vm_tabs_read"} lists a VM's tabs) `vm` (optional): the VM by number: vm-1 (the default) to vm-8	give the file to the Pro tab	`{"verb":"send","file":"~/a.png","tab":"t3"}` → `wazza --gui pro-input ~/a.png --tab t3`
observe	`input_id`: the input's id	how far the file went	`{"verb":"observe","input_id":"i1"}` → `wazza --gui pro-input --observe i1`

`invoke`#

Any control-plane command of the running Wazza OS app (CLI wazza --gui invoke): its modules, their methods and jobs. modules_call reaches every module method (sandbox, packages, agent, ui, drive, updater...): modules_list and modules_status say what each offers. The other tools cover the usual work; use this one for what they do not.

verb	arguments	what it does	example
ping	-	control-plane ping	`{"verb":"ping"}` → `wazza --gui invoke ping`
status	-	the app's status	`{"verb":"status"}` → `wazza --gui invoke status`
app_status	-	the app's own status	`{"verb":"app_status"}` → `wazza --gui invoke app_status`
modules_list	-	the modules	`{"verb":"modules_list"}` → `wazza --gui invoke modules_list`
modules_status	`module`: the module's id	one module's state and methods	`{"verb":"modules_status","module":"sandbox"}` → `wazza --gui invoke modules_status sandbox`
modules_call	`module`: the module's id `method`: the method `args` (optional): the method's arguments	call one module method	`{"verb":"modules_call","module":"sandbox","method":"status","args":{}}` → `wazza --gui invoke modules_call sandbox status -`
jobs_list	-	the jobs	`{"verb":"jobs_list"}` → `wazza --gui invoke jobs_list`
jobs_get	`job_id`: the job's id	one job	`{"verb":"jobs_get","job_id":"job-1"}` → `wazza --gui invoke jobs_get job-1`
jobs_cancel	`job_id`: the job's id	cancel a job	`{"verb":"jobs_cancel","job_id":"job-1"}` → `wazza --gui invoke jobs_cancel job-1`
jobs_output	`job_id`: the job's id `since` (optional): the output offset to read from	a job's output	`{"verb":"jobs_output","job_id":"job-1","since":0}` → `wazza --gui invoke jobs_output job-1 0`
events_poll	`since` (optional): the event number to read from	the app's events	`{"verb":"events_poll","since":0}` → `wazza --gui invoke events_poll 0`
session_get	-	the session	`{"verb":"session_get"}` → `wazza --gui invoke session_get`
claims	-	the claims	`{"verb":"claims"}` → `wazza --gui invoke claims`
claims_report	-	the claims report	`{"verb":"claims_report"}` → `wazza --gui invoke claims_report`
gnome	`words`: help \| stream-status \| frame \| app-launch ID \| app-focus ID \| terminal-open \| terminal-focus \| hermes \| pointer X Y \| click X Y [B] \| key KEY	a GNOME desktop action in the VM shown	`{"verb":"gnome","words":["stream-status"]}` → `wazza --gui invoke gnome stream-status`

`screenshot`#

A PNG of the Wazza OS app's own window (CLI wazza --gui screenshot): on a desktop the window's own picture (never the screen or another window), on a server its virtual screen. A tab's app: drive {verb: "look"}.

verb	arguments	what it does	example
-	`file`: the .png to write (absolute, or relative to the folder the agent runs in)	the screenshot	`{"file":"shot.png"}` → `wazza --gui screenshot shot.png`

`record`#

An MP4 of the Wazza OS app's own virtual screen (CLI wazza --gui record), at most 120 s; only on its virtual screen.

verb	arguments	what it does	example
start	`file`: the .mp4 to write (absolute, or relative to the folder the agent runs in)	start recording	`{"verb":"start","file":"run.mp4"}` → `wazza --gui record start run.mp4`
stop	`id`: the recording's id	stop it	`{"verb":"stop","id":"rec-1"}` → `wazza --gui record stop rec-1`

`host_app`#

Apps on the Wazza OS app's own virtual screen beside its window (CLI wazza --gui host-app): Chromium, VLC or xmessage; only on its virtual screen.

verb	arguments	what it does	example
list	-	the host apps running	`{"verb":"list"}` → `wazza --gui host-app list`
launch	`app`: the app	start one	`{"verb":"launch","app":"chromium"}` → `wazza --gui host-app launch chromium`
stop	`id`: its id from list 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef	stop one (removes or ends something)	`{"verb":"stop","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}` → `wazza --gui host-app stop 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

`native_input`#

Pointer and keyboard input into the Wazza OS app's own window (CLI wazza --gui native-input), on a desktop or its virtual screen: begin a lease, then focus, pointer, click, scroll, key, text, end. X,Y are the screenshot's pixels; never the user's pointer or another window.

verb	arguments	what it does	example
begin	-	start an input lease on the owned window (its id)	`{"verb":"begin"}` → `wazza --gui native-input begin --consent-owned-window`
focus	`id`: the lease id begin answered (64 hex)	focus the window	`{"verb":"focus","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}` → `wazza --gui native-input focus 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`
pointer	`id`: the lease id begin answered (64 hex) `x`: x `y`: y	move the pointer	`{"verb":"pointer","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","x":10,"y":20}` → `wazza --gui native-input pointer 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef 10 20`
click	`id`: the lease id begin answered (64 hex) `x`: x `y`: y `button` (optional): 1, 2 or 3 (default 1)	click	`{"verb":"click","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","x":10,"y":20}` → `wazza --gui native-input click 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef 10 20`
scroll	`id`: the lease id begin answered (64 hex) `x`: x `y`: y `direction`: the wheel's direction `steps` (optional): 1 to 20 wheel notches (default 1)	scroll	`{"verb":"scroll","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","x":10,"y":20,"direction":"down"}` → `wazza --gui native-input scroll 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef 10 20 down`
key	`id`: the lease id begin answered (64 hex) `key`: a printable key, Tab, Return, Escape, BackSpace, arrows, Ctrl+a, Ctrl+l...	press a key	`{"verb":"key","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","key":"Return"}` → `wazza --gui native-input key 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef Return`
text	`id`: the lease id begin answered (64 hex) `text`: 1 to 512 printable ASCII characters	type text	`{"verb":"text","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","text":"hello"}` → `wazza --gui native-input text 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --stdin`
end	`id`: the lease id begin answered (64 hex)	end the lease	`{"verb":"end","id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}` → `wazza --gui native-input end 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

`quit`#

Close the Wazza OS app (CLI wazza --gui quit): its VMs and Chats stop. Only when the user asked for it.

verb	arguments	what it does	example
-	-	close the Wazza OS app (removes or ends something)	`{}` → `wazza --gui quit`

Wazza OS user manual · written for Wazza OS 0.2.0 (build 44c5d0ea07c1) · screenshots from a test computer running Wazza OS 0.2.0.

Every Wazza OS MCP tool

Find the tool for a task#

How an agent uses them#

The typical flow#

The rules#

The 41 tools#

status#

start#

check#

version#

ui#

vm#

vm_memory#

vm_disk#

vm_gpu#

gpu#

vm_resources#

data#

app#

explorer#

drive#

chat_transcript#

chat_queue#

chat_model#

schedule#

crew_run#

tool_queue#

timeouts#

local_services#

dev_servers#

clipboard#

setup#

token_stats#

provider_keys#

provider_signin#

wazza_account#

wazza_llm#

copilot#

wazza_tools#

pro#

pro_input#

invoke#

screenshot#

record#

host_app#

native_input#

quit#