docs/DESKTOP.md
Rama main · réplica de lectura del repositorio original.
# AgentRQ Desktop
The desktop app is the AgentRQ web interface in a native shell. It is the same
application — the same views, the same shortcuts, the same design — plus the
things a browser tab cannot do: notifications that arrive while the window is in
the background, a menu-bar item, links that open the app at the right place, and
updates that install themselves.
It is a **client**. Your AgentRQ server keeps running wherever you run it —
localhost, a machine on your network, or a hosted instance — and the app
connects to it.
---
## Installing
### macOS and Linux: one command
```sh
curl -fsSL https://agentrq.com/install.sh | sh
```
That is also how you update — run the same command again and it replaces the
app in place. It works out which build matches your machine, checks the download
against the checksum published with the release, and installs to `/Applications`
(or `~/Applications` if that is locked down) on macOS, or `~/.local/bin/agentrq`
plus a launcher entry on Linux.
On macOS it does one more thing worth knowing about: it clears the quarantine
flag, so the ["developer cannot be verified" dialog](#the-first-launch-security-warning)
never appears. Installing this way skips that problem entirely.
Options go after a `--`:
| Option | Effect |
|---|---|
| `--quit` | Quit a running AgentRQ instead of refusing to overwrite it |
| `--version v0.5.0` | Install a specific release rather than the newest |
| `--dir <path>` | Install somewhere other than the default |
| `--force` | Reinstall even if that version is already installed |
```sh
curl -fsSL https://agentrq.com/install.sh | sh -s -- --quit
```
### Windows, or downloading by hand
Take the build for your machine from the
[latest release](https://github.com/agentrq/agentrq/releases/latest).
| Platform | File | Notes |
|---|---|---|
| macOS (Apple silicon) | `AgentRQ-<version>-arm64.dmg` | |
| macOS (Intel) | `AgentRQ-<version>-x64.dmg` | |
| Windows | `AgentRQ Setup <version>.exe` | x64 and arm64 |
| Linux (AppImage) | `AgentRQ-<version>.AppImage` | `chmod +x` then run |
| Linux (Debian/Ubuntu) | `agentrq_<version>_amd64.deb` | `sudo dpkg -i` |
Linux ships both x64 and arm64, so a Raspberry Pi or an ARM cloud instance works
as well as an ordinary desktop.
### The first-launch security warning
Until the project has code-signing certificates, the builds are **unsigned** and
your operating system will say so on a **hand-downloaded** build. (The install
command above avoids this on macOS.) It is worth knowing exactly what the
warning means rather than clicking through blind:
- **macOS**: "AgentRQ cannot be opened because the developer cannot be
verified." On macOS 14 and earlier, right-click the app → **Open** →
**Open**. On macOS 15 and later Apple removed that shortcut: try to open the
app, then go to **System Settings → Privacy & Security**, find the message
about AgentRQ near the bottom, and click **Open Anyway**. Once, either way.
- **Windows**: SmartScreen shows "Windows protected your PC." **More info** →
**Run anyway**.
- **Linux**: no warning.
The other consequence is on macOS, and it is not cosmetic: **an unsigned macOS
build cannot update itself.** macOS validates an application's signature before
replacing it, so the app can check for updates and tell you one exists, but
cannot install it. That is what the install command is for. Windows and Linux
update normally. See [Auto-update](#auto-update).
---
## Connecting to a server
On first launch the app asks for your AgentRQ server URL, defaulting to the
hosted instance at `https://app.agentrq.com`. If you run your own server, put
its address in instead -- `http://localhost:3000` for one on this machine.
The address is checked before it is saved, so a typo is caught immediately
instead of turning into a mysterious failure to sign in later. Then you sign in
exactly as you would in a browser: root token, Google, or GitHub.
To point at a different server afterwards, use **Switch Server** in the
application menu (macOS: `AgentRQ` menu; Windows and Linux: `File`).
**Log Out** clears the session without forgetting the server.
The choice is stored in `agentrq-desktop.json` under the app's data directory:
| Platform | Location |
|---|---|
| macOS | `~/Library/Application Support/agentrq-desktop/` |
| Windows | `%APPDATA%\agentrq-desktop\` |
| Linux | `~/.config/agentrq-desktop/` |
---
## What the desktop adds
**Notifications.** Native notifications when an agent creates a task, changes a
task's status, or replies. Clicking one opens the app at that task. The unread
count appears on the dock icon or the taskbar. Mute them per workspace in
**Workspace Settings → Notifications → Desktop Alerts**.
Notifications only fire for things *agents* do — you are not told about your own
clicks.
**Tray / menu-bar item.** Unread count, your most recently active workspaces, and
a shortcut to create a task.
**Global shortcut.** `Cmd/Ctrl+Shift+N` creates a task from anywhere, even when
the app is not focused.
**Deep links.** `agentrq://` URLs open the app at a specific place:
```
agentrq://workspaces/<workspaceId>
agentrq://workspaces/<workspaceId>/tasks/<taskId>
agentrq://events
agentrq://workflows
```
Useful in a Slack message, a calendar invite, or a script.
**Web links.** A web link in a task or a message — a URL an agent put there —
opens in the side panel, next to the task it came from. Hold `Cmd` (macOS) or
`Ctrl` while clicking, or middle-click, to open it in your own browser instead,
where your extensions, bookmarks and signed-in tabs already are; the links the
app itself draws, like the docs, always go there. Signing in to AgentRQ is the
exception to both and stays in the app: the session it earns has to belong to
the app to be any use.
**Side panel.** A browser beside the app, on the right of the window, so a page
can sit next to the task it belongs to. Open and close it with
`Cmd/Ctrl+\` (**View → Side Panel**), the panel button in a task's header, the
**Panel** button at the bottom of the sidebar, or — on macOS — the panel button
in the title bar. It has back, forward, reload, an address field, **Open in
browser** and **Expand**, which gives it the whole window beside the sidebar
until you collapse it again. `Cmd/Ctrl+F` finds text in its page: `Enter` and
`Shift+Enter` step through the matches, `Esc` closes the find bar.
Opened, it takes all the room except a phone's width for the page beside it,
and a task there is shown the way it is on a phone. Drag the panel's left edge
to share the window differently; double-click the edge to go back.
When a page in the panel asks to use your camera, microphone, location,
notifications or the like, a bar under its toolbar names the site and asks:
**Allow** or **Block**. Your answer is remembered for that site, so it does not
ask again; the shield button in the toolbar lists every site's answers and
removes any of them, after which that site asks again. Unanswered, a question is
a Block after a minute, or as soon as you leave the page. Anything newer than
this list is blocked without asking.
The panel keeps its own cookies, one set per profile, separate from the app's:
a site you sign in to there never sees your AgentRQ session, and AgentRQ's own
sign-in links always go back to the main window. Its width, whether it is open
or expanded, the last page it showed and every site's permissions are remembered
on this computer only — nothing
about the panel is sent to the server or synced to another machine. Removing a
profile clears its panel's cookies too.
**Local file links.** A `file:///…` link in a task or a message is clickable
here. Documents, images, source files and media open in whatever application you
normally use for them. Anything that would *run* — a script, a `.app`, an `.exe`,
an archive, an `.html` page, or a file with no extension at all — is shown in
Finder or your file manager instead, and the app says so. AgentRQ never runs a
file because a message linked to it.
In the browser the same link cannot be opened at all — no web page may reach
your filesystem — so clicking it copies the path to your clipboard instead.
**Copying a link.** Every link in a task or a message has a small copy button
beside it, in both the desktop app and the browser. It puts the link's target on
your clipboard: the plain filesystem path for a local file, the URL for anything
else.
**Window state.** Position and size are remembered between launches — and
checked against the displays you currently have, so the window never reopens on
a monitor you have unplugged.
**Theme.** Follows your AgentRQ theme setting, not your operating system's. If
you choose light inside AgentRQ, the window chrome is light even on a dark
system.
---
## Auto-update
The app checks for updates when it starts and every fifteen minutes after that,
and downloads them quietly in the background. When one is ready you get the same
banner the web app shows for a new version, with an **Update now** button. The
banner stays until you act on it or close it with the ✕ — a later check will not
take it away, and dismissing it keeps it away until a newer version appears.
Ignore it and the update installs the next time you quit.
On a build that cannot replace itself — an unsigned macOS app, which Squirrel
refuses to update — **Update now** runs the one-command installer for you
instead: it closes the app, installs the new version, and reopens it. Nothing to
copy into a terminal.
**Check for Updates…** in the application menu asks immediately and tells you
what it found. A background check that finds nothing stays silent.
> **macOS needs a signed build.** An unsigned build reports *"This build is not
> signed, so it cannot update itself"* — macOS refuses to replace an unsigned
> app in place. Update with the install command instead, which is not subject to
> that check:
>
> ```sh
> curl -fsSL https://agentrq.com/install.sh | sh -s -- --quit --force
> ```
>
> Windows and Linux are unaffected and update themselves normally.
---
## Troubleshooting
**"Could not reach <url>" on the connection screen.**
The server is not answering at that address. Check it is running and that the
port is right — the default is 3000. If the server is on another machine,
confirm nothing is filtering the port between you and it. If you are running the
server behind a reverse proxy on a sub-path, include the path
(`https://example.com/agentrq`).
**"That URL is not an AgentRQ server."**
Something answered, but it was not AgentRQ. Usually a proxy, a login portal, or
the wrong port on the right host.
**A self-signed HTTPS certificate.**
The app rejects certificates it cannot verify, exactly as a browser does. Either
add the certificate to your system trust store — the app uses it — or connect
over plain `http://` on a network you trust. There is deliberately no "ignore
certificate errors" switch: it would silently apply to every future connection.
**Notifications do not appear.**
Check the operating system first — macOS **System Settings → Notifications →
AgentRQ**, Windows **Settings → System → Notifications**. Then check the
workspace is not muted under **Workspace Settings → Notifications**. Remember
that only agent activity notifies.
**`agentrq://` links do nothing.**
The app registers the scheme when it first runs, so launch it once. On Linux
you may need `update-desktop-database`. If another application has claimed the
scheme, the operating system will prefer that one.
**Dictation does not work.**
It needs microphone permission — macOS asks the first time; grant it under
**System Settings → Privacy & Security → Microphone** if you dismissed it. The
speech model is downloaded on first use, so the first run needs a connection and
a moment.
**The window opened somewhere I cannot see it.**
It should not — saved positions are checked against your current displays. If it
happens, delete `agentrq-window.json` from the data directory above and relaunch.
**Starting over.**
Quit the app and delete its data directory. That clears the server URL, the
session, mute settings and window position. It does not touch anything on your
server.
---
## Preview: Tauri build
There is a second build of the desktop app, on [Tauri](https://tauri.app)
instead of Electron. It is the same application: the same views, built from the
same code, with the features above. What changes is the shell around it. Tauri
uses the webview your operating system already has (WebKit on macOS and Linux,
WebView2 on Windows) rather than shipping a browser of its own, so the
download is around 15 MB instead of 100 to 230 MB, and the app uses less
memory.
**Electron stays the default.** The install command, the downloads in the table
above and the updates of an installed app are all Electron's. The Tauri build
is a preview: try it if you are curious, and expect the differences listed below.
The Tauri build updates from its own `latest-tauri.json` feed rather than
Electron's `latest*.yml`.
### Installing the preview
On macOS and Linux, add `--tauri` to the install command:
```sh
curl -fsSL https://agentrq.com/install.sh | sh -s -- --tauri
```
Run it again to update. Setting `AGENTRQ_TAURI=1` does the same as `--tauri`.
On Windows, or by hand from the
[latest release](https://github.com/agentrq/agentrq-desktop/releases/latest) of
[agentrq/agentrq-desktop](https://github.com/agentrq/agentrq-desktop), where the
Tauri build lives, download the
assets named `AgentRQ-Tauri-<version>-<arch>.<ext>`:
- **macOS**: `AgentRQ-Tauri-<version>-arm64.dmg` (Apple silicon) or `AgentRQ-Tauri-<version>-x64.dmg` (Intel)
- **Windows**: `AgentRQ-Tauri-<version>-x64.exe` (NSIS setup installer)
- **Linux**: `AgentRQ-Tauri-<version>-x64.AppImage` or `AgentRQ-Tauri-<version>-x64.deb`
The preview installs beside the Electron app, not over it. It is called
**AgentRQ Tauri**, it opens `agentrq-tauri://` links rather than `agentrq://`,
and it keeps its own data, so you connect and sign in again the first time:
| Platform | Data directory |
|---|---|
| macOS | `~/Library/Application Support/com.agentrq.desktop.tauri/` |
| Windows | `%APPDATA%\com.agentrq.desktop.tauri\` |
| Linux | `~/.local/share/com.agentrq.desktop.tauri/` |
The first-launch security warning and the rest of this guide apply to it as
they do to the Electron app.
### Differences that remain
Each of the following differences remains between the Tauri preview and the Electron app:
- **Extensions run on a Node.js the app downloads.** The Electron app runs extensions on the Node.js inside Electron. The preview ships without one, so the first time you install an extension, the Extensions page offers to download Node.js v24.22.1 from nodejs.org, once, with its checksum pinned. The download is 27.5 MB on Apple silicon Macs, 29.3 MB on Intel Macs, 32.0 MB on Linux x64, 31.0 MB on Linux arm64, 37.7 MB on Windows x64 and 33.8 MB on Windows arm64. Only the `node` binary is kept in the data directory: 82 to 127 MB unpacked.
- WKWebView lacks public permission hooks for geolocation, notifications and screen capture, so side-panel guests cannot request them on macOS.
- No Linux arm64 preview build is published in release assets yet (Linux preview is x64 only).
- On macOS 13 and earlier, WKWebView ignores `data_store_identifier`, so side-panel guests run incognito and do not retain cookies across restarts.
- On macOS, WKWebView process crashes are not reported through wry, so a crashed webview stays blank until manually reloaded with `Cmd+R`.
- During preview, deep links use the `agentrq-tauri://` scheme and bundle ID `com.agentrq.desktop.tauri` to avoid conflicting with Electron.
- In the side panel, WebKit makes no new window of a Cmd/Ctrl-click, so user link clicks are routed to the system browser instead of an in-app window.
---
## Building it yourself
```bash
make install # dependencies for the whole repo
make desktop-dev # run the desktop app against a local server
make desktop # build installers into desktop/release/
```
`make desktop-dev` expects an AgentRQ server on `http://localhost:3000` — `make
dev` in another terminal gives you one. Point it elsewhere with
`AGENTRQ_SERVER_URL`:
```bash
AGENTRQ_SERVER_URL=https://agentrq.example.com make desktop-dev
```
The renderer is built from `frontend/src`, so a change to the web app appears in
the desktop app with no separate step.
The Tauri preview lives in
[agentrq/agentrq-desktop](https://github.com/agentrq/agentrq-desktop), which
pins this repository as a submodule and builds the same renderer.
Deeper detail — how the app:// proxy works, why the connection screen lives
where it does, how to run the verification scripts — is in
[`desktop/README.md`](../desktop/README.md).
---
## Releasing
Pushing a `v*` tag builds on all three platforms and publishes installers and
the update manifests to a GitHub Release, which is also the update feed. The
desktop, frontend and backend versions must agree, and the tag must match them;
the release is published only once every platform has finished, so nobody sees a
release missing the installer for their machine.
To enable signing, add `MAC_CERTIFICATE`, `MAC_CERTIFICATE_PASSWORD`,
`APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD` and `APPLE_TEAM_ID` as repository
secrets, plus `WIN_CERTIFICATE` and `WIN_CERTIFICATE_PASSWORD` for Windows. No
code changes are needed — the workflow builds unsigned when they are absent.