The GUI and the Desktop App

The Robota GUI shows a robota session in a window: the conversation, the questions it asks you, its settings and the work it runs in the background. Like the CLI, the GUI and the desktop app are maintained interfaces built from the Robota libraries — the page is agent-gui-web over the agent-ui-web presentation library, and the desktop app (apps/agent-app) is an Electron shell around that page. They hold no agent runtime of their own: every turn, command and permission check runs in a robota runtime on your machine, and the window is one more client of it, beside the terminal UI.

Two ways in

Both show the same page.

In a browser

Run this in your project folder:

robota --serve --open

It starts a runtime, serves the GUI on http://127.0.0.1:<port> and opens it in your default browser. The command needs an interactive terminal: it prints Monitor access code: …, and the browser shows a form that asks for that code before it serves the page. The page then connects to the runtime over a loopback WebSocket with a token the CLI puts in the page, so another page in your browser cannot connect to it. The runtime stops when you stop the command (Ctrl+C). It is not the workspace daemon: robota --attach and the desktop app do not see it.

In a folder you have not decided about, robota --serve --open asks in the terminal before it starts: y trusts the folder, r starts Restricted, and anything else quits. Plain --serve refuses instead, and so does --serve --open when its terminal cannot answer; both name the ways past: robota trust --yes, or --restricted-workspace. See the first run.

The desktop app

The desktop app is released as installers on GitHub Releases, named robota-desktop-<version>-<arch>: a .dmg or .zip for macOS, an .exe for Windows, and an .AppImage or .deb for Linux. It is not published to npm.

The macOS disk image is signed and notarized. The Windows and Linux installers are not code-signed, so the operating system can warn on the first launch:

• Windows SmartScreen warns. Choose More info, then Run anyway.
• Linux: make the AppImage executable (chmod +x robota-desktop-*.AppImage) before running it.

The app works on the folder you open. On its first launch it asks which folder to open; after that it reopens the most recent folder that still exists. File → Open Folder… (Cmd+O / Ctrl+O) switches to another folder and File → Open Recent lists the folders opened before. The window title names the open folder.

The app starts the workspace daemon for its folder, or connects to the one already running. Switching folders attaches to the other folder's daemon and leaves the first one running. Closing the window leaves the daemon running and the next launch reconnects to it; on macOS the app stays in the Dock, and clicking its icon opens a new window on the same folder. If the daemon stops while the window is open, the window offers Reconnect. With the CLI installed, robota daemon stop in the folder stops it. See the workspace daemon.

Secure conversations are optional. Enable them from an interactive terminal with robota secure setup and robota secure enable after closing Robota sessions. The secure desktop window is available on macOS only. The app then opens on a locked screen. Choose File → Unlock Secure Conversation… and enter the passphrase in the native window. Reloading or closing the window locks the conversation; an unsent draft and attachment paths are discarded. To return to plaintext for new conversations, close the current-version sessions and run robota secure disable at a terminal. The sealed archive remains. See secure conversations.

The first run

Trusting the folder

Robota loads a project's own configuration only from a folder you trust. In a folder you have not decided about, the desktop app asks Do you trust this folder? before it starts anything:

• Trust folder — Robota uses the project's own settings, hooks, skills and MCP servers.
• Start Restricted — the project's settings, hooks, plugins, skills, agent definitions, provider overrides and MCP servers are not loaded.
• Quit — nothing starts.

Details lists what the project would load. robota --serve --open asks the same question in the terminal before the page opens. The answer is the same trust decision robota trust records, described in workspace trust. A folder that is not in a Git repository has nothing to trust, so Robota runs there Restricted without asking.

Connecting a model provider

If no provider is configured yet, the GUI shows Connect a model provider to start. in place of the conversation. Set up provider walks you through the same steps as /provider add in the terminal:

1. Choose a provider type: Anthropic, OpenAI, Gemini, a local server (listed as Ollama / LM Studio / llama.cpp), Qwen or DeepSeek.
2. Answer that type's questions: its base URL where it has one, the API key (the field is masked; a local server needs none) and the model, with a default offered.

The answers are saved as a provider profile in <user-state>/settings.json, and the conversation appears without a restart. Add more profiles, or change this one, later in Settings → Providers & Models. The providers and their options are described in Providers.

When the runtime cannot start

If the runtime stops before the window can connect, the window shows The agent process stopped: followed by the runtime's own message, which names the fix. Try again starts it again.

Using the GUI

The header switches between Chat, Project and Usage. The sessions sidebar is on the left; the Agents panel appears on the right whenever work is running in the background.

Sessions

The sidebar lists this folder's saved sessions, each with its name (or the start of its first message), when it was last updated, and a dot when it is live. New session starts one; clicking another session switches to it. A row's ⋯ menu (or a right-click) offers Rename and Delete…, which asks first because it removes the conversation from your computer. /resume opens the same sidebar. A session file this version cannot read is listed as one collapsed line instead of disappearing.

Sending, stopping and queuing

Enter sends and Shift+Enter starts a new line. While a turn runs, the send button becomes Stop (Esc also stops it). A message you send while a turn is running waits in a Queued strip above the composer, where you can edit or remove it. Your draft is kept per session and survives a reload.

Typing / opens a menu of Commands and Skills. /settings, /resume and /help open their screen at once; the other commands fill the composer so you can add arguments. /help lists the keyboard shortcuts and every command.

Attaching files

In the desktop app, the paperclip button or dragging files onto the composer attaches them as @ references to files in the project: up to 8 text files per message, 64 KiB each and 256 KiB in total. A file outside the project folder, an image or another non-text file is refused with a message. A browser cannot tell the page where a file is on disk, so there every file is refused with Only files inside this project folder can be attached.

Model, mode and effort

The controls under the composer change the session without adding anything to the conversation; each control's label shows the current value.

• Model lists the models you can switch to, grouped by provider, with a check on the current one. Manage providers… opens Settings.
• Mode is the permission mode, shown with a plain name and description. Skip all checks asks you to confirm first, because every action — file edits, shell commands and network access — then runs without asking. See permission modes.
• Effort offers Auto, Low, Medium and High, with the other levels under More.

A ring beside them shows how much of the model's context window the conversation uses.

Questions and permission prompts

When the agent needs you, the question appears above the composer:

• Allow tool to run? — Allow (1) or Deny (2); Esc denies. A file edit shows its diff first. A request from a background agent names the agent.
• A question with choices shows them as buttons (1–9). A destructive choice, such as deleting a provider profile, is set apart from the others and has no number key.
• A question that needs text shows a field and Continue; the field is masked for secrets such as API keys.

A new prompt ignores answer keys for a moment and never takes focus from a field you are typing in, so a keystroke meant for something else does not answer it.

Settings

Settings (the gear in the sidebar, /settings, or ⌘, / Ctrl+, in the desktop app) has five sections, and every change applies at once — there is no Save button:

• General — language, output style and preset.
• Permissions — the permission mode, the sandbox switch, and the allow, ask and deny rules (remove one here).
• MCP Servers — turn a configured server on (approve) or off (reject), see its tools, and reload the servers. Revoking an approval and signing in are /mcp commands, and servers are added in settings files; see MCP.
• Plugins — turn installed CLI plugins on or off, or uninstall them.
• Providers & Models — your provider profiles: use, change the model, edit, test, duplicate or delete one, or add a provider.

Project, work in progress and usage

• Project shows the folder's Git changes (click a file for its diff) and the project memory.
• The Agents panel lists background agents and tasks, scheduled tasks and the current /goal, with Stop, Pause and Resume where they apply. Selecting an entry opens its transcript and result.
• Usage shows your token use and cost for the current session and for the last 7 or 30 days, by model. It is shown in the desktop app and in robota --serve --open, not in the browser remote client.

Keyboard shortcuts

The GUI and the terminal together

The desktop app and robota --attach both connect to the folder's workspace daemon, so you can use the window and the full terminal UI on the same runtime at once. Each client is on its own session and switches independently; two clients on the same session share its turns, prompts and background tasks, and a message or prompt that came from the other kind of client is labelled, for example from the terminal. The limits — four live sessions, the idle grace period — are in several sessions in one runtime.

A robota --serve --open runtime is separate from the daemon, so a terminal cannot attach to it.

What the GUI cannot do yet

• Attach images or other non-text files, or attach anything from a browser.
• Add or edit an MCP server. Configure servers in settings files; Settings turns them on or off.
• Create a schedule or a goal from a form. Use /schedule and /goal; the Agents panel then shows and controls them.
• Rewind to a checkpoint. The GUI has no checkpoint list.
• Run the terminal-only commands. /shell needs a terminal; /theme, /keybindings, /editor and /statusline configure the terminal UI (the GUI follows your system's appearance); pairing a device stays in the terminal. Typing one of them in the GUI says what to use instead.
• Show Advisor settings, or sandbox options beyond on and off, on a screen. Use /advisor and /sandbox.
• Install a signed desktop app on Windows or Linux. Those installers are unsigned.

Troubleshooting

Related

• Sessions, Background Sessions and the Daemon — the daemon, attaching and workspace trust
• CLI Reference — the same commands in the terminal
• Permissions and Hooks — permission modes and rules
• Devices, Peers and Remote Control — co-driving a session from a browser on another device