Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Desktop deep links (avibe://)
Status
Frozen implementation contract for gap G5. Companion to
desktop-product-gaps.md (G5), desktop-notifications-sse.md (G4 click
upgrades to a locate, not a redesign), and
tauri-desktop-vertical-slice.md (thin shell, Workbench stays the
product UI).
Owner: Avibe core
Date: 2026-09-10
Baseline: desktop branch after #1975 (single-instance plugin already
focuses the running window and ignores argv).
Product outcome
A click on avibe://session/<id> (from IM, mail, or a future G4
notification) brings Avibe to the front and shows that session. If the
app was not running, it starts, finishes bootstrap, then shows the
session. Unknown or malformed links are dropped, never echoed back
into a WebView.
v1 is locate-in-the-existing-window. Opening a second native window for a Show Page is G8 and is not this contract.
Frozen grammar
Scheme: avibe (no + / no vendor prefix). Registered for the
packaged app identifier bot.avibe.desktop.
v1 URLs use the avibe:// form users type and OS scheme handlers
deliver. A WHATWG parser therefore treats <kind> as the authority
(host), not as a path segment. That is the frozen grammar: kind is
the allow-listed authority. Do not also accept a second, host-less
spelling (avibe:session/...); one form only.
| Link (kind = authority) | Workbench navigation |
|---|---|
avibe://session/<session_id> |
/chat/<session_id> |
avibe://show/<session_id> |
/apps/show/<session_id> |
avibe://settings |
/settings/general |
avibe://settings/computer-use |
/settings/computer-use |
avibe://vaults/request/<request_id> |
/vaults?request_id=<request_id> |
Parse as a URL. Accept only when scheme == avibe, host is one of
session, show, settings, vaults, and port is absent
(avibe://session:443/<id> is malformed even though host_str()
would look allow-listed). Userinfo is rejected. Path/id rules:
session/show: path is exactly one segment, the id.settings: path empty.vaults: path is exactlyrequest/<request_id>.
<session_id> and <request_id> are the product's existing identifiers
(Workbench session ids, vault request ids). They are accepted only when
they match ^[A-Za-z0-9._-]+$, are at most 128 bytes, and are not
the complete path segments . or ... Ordinary dots inside an id
(ses.abc) remain valid.
Rejected complete . / .. because WHATWG URL path normalization
would turn /chat/. into /chat/ and /chat/.. into /, so the
in-window navigation could not land on the mapped session route. Percent-encoded %2E / %2E%2E do normalize as dot-segments under
WHATWG (/chat/%2E → /chat/, /chat/%2E%2E → /). They are still
rejected, but by the character-class rule (% is not in
[A-Za-z0-9._-]), not by a special encoded-dot exception. Do not
document them as surviving the parser.
Rejected (no navigation, no quoted echo into the WebView):
- any scheme other than
avibe; - host/authority not in
{session, show, settings, vaults}(this is what "reject unknown authority" means — userinfo, non-allow-listed hosts,avibe://session@…); - extra path segments, query, or fragment other than the table;
- an id that fails the character/length rule or is complete
./...
The mapping table is the contract. A new kind is a contract revision, not a silent addition in the parser.
Delivery: the shell never talks IPC to the Workbench
Two launch shapes, one Workbench mechanism.
- Hot path (app already running). Every OS delivery of an
avibe://URL is parsed by the same function and applied to the live window. On Windows a second launch typically arrives as single-instance argv (already wired to focus the main window indesktop/src-tauri/src/lib.rs). On macOS, Launch Services delivers custom-scheme activations as a native open-URL event (RunEvent::Opened/ the deep-link plugin's current-URL /on_open_urlRust callback) — not as a second-process argv. Feed that native event into the same parser/stash as argv. Never handle it in WebView JavaScript, never add an IPC command. After the window is showing the Workbench origin, navigate in-window to{origin}{path}{query}from the table. Same origin as the currently adopted Runtime; neverdevUrl/ port 1420. - Cold path (app was not running). OS starts the packaged app with the URL in argv or (macOS) as the first open-URL event. The shell stashes the parsed target, runs the existing bootstrap/adopt flow unchanged, and on the first successful Workbench navigation includes the target path so the SPA lands on it instead of the default session list.
Both paths resolve to "the Workbench SPA navigates to a same-origin
URL it already implements". There is no new Tauri command, no new
capability, no remote grant. A Workbench page still cannot invoke
bootstrap IPC; the shell pushing a same-origin path into its own
WebView is not an IPC grant.
One narrow exception keeps an in-app gesture from costing the user
their place: the native Settings… item (menu, tray, CmdOrCtrl+,)
opens General Settings over whatever the Workbench is showing, so
closing Settings returns to that session, project, or draft. While the
window shows the adopted origin, the shell evaluates one constant
script that dispatches the cancelable avibe:desktop-open-settings
event; the SPA cancels it and opens its Settings overlay in place. An
uncancelled event (an older Workbench) falls back to
location.assign('/settings/general'), and a window not showing the
Workbench, or a failed evaluation, falls back to delivering
avibe://settings through this path. The script is shell-owned and
carries no page data; the page gains no command and no capability.
External avibe://settings links keep the ordinary navigation.
If the Runtime is not yet ready (bootstrap screen still up), the stashed target waits. Bootstrap failure discards it and stays on the bootstrap screen — a deep link must not override a failed Runtime with a half-navigated Workbench.
Why not an IPC command
An IPC open_target callable from the WebView would have to be
granted to the navigated Workbench to be useful on the hot path,
which is exactly the capability boundary shell_boundaries.rs
forbids. Same-origin in-window navigation keeps the privilege in
the shell: only the process that owns the window decides to move it.
Producer side (Python, separate from the shell PR if needed)
Today vault_request_url / IM formatters emit public https://
Workbench URLs via workbench_url (core/avibe_cloud.py). That
remains the right link for browsers and for users without the
desktop app.
v1 desktop does not require those producers to switch. The
shell's job is to honour avibe:// when the OS delivers one.
Producers may start emitting avibe:// in addition to https
(for example in a native-notification payload once G4 lands) under
their own PR; that is a link-grammar consumer, not a scheme-parser
change. Until they do, G5 is still testable: open
avibe://session/<known-id> from Terminal / a test page.
Do not replace https links in IM with avibe:// in v1: IM clients
are not the desktop OS and cannot route the scheme.
Plugin and packaging
tauri-plugin-deep-linkregisters the scheme at build/install time for the packaged app. Developmenttauri devmay not receive OS-levelavibe://clicks (scheme registration is an installed-app concern); argv injection and the single-instance callback remain the testable path.- macOS: the scheme lands in
Info.plistvia the plugin. That file is generated; do not hand-edit it in source. - Windows: the scheme lands in the NSIS file association. Unsigned acceptance builds still register it for that install; signing (G1) does not change the grammar.
Tests (invariants)
- Parser: every row in the mapping table produces the exact
Workbench path; every rejected shape (wrong scheme, extra
segment, bad id, complete
./..path id, authority, explicit port) producesNoneand never includes the raw input in a UI string. An id that merely contains a dot still maps. - Hot path: a valid link focuses the main window and requests
in-window navigation to the mapped path on the currently adopted
origin, not on
devUrl/ port 1420 — whether the link arrived as second-instance argv or as a macOS native open-URL / GURL Apple Event (raw string into the same parser/stash). An implementation that only wires argv does not satisfy this. - Cold path: a stashed valid target (from argv or the first macOS open-URL event) is applied on the first successful Workbench navigation and then cleared; a failed bootstrap leaves the stash dropped and the window on bootstrap.
- Boundary: no new command appears in
src-tauri/build.rs;shell_boundaries.rsstill forbidsremotegrants. Deep-link handling lives in argv, the single-instance callback, and the macOS native open-URL adapter — none of which are WebView-callable. The adapter must feed the shared parser/stash; it must not reintroduce aUrl::as_str()path after Tao has normalized the URL. - Capability: a Workbench origin (remote after navigation) still cannot invoke bootstrap commands after a deep link is consumed.
Drive parser tests without Tauri (pure function in runtime-host or
an equivalent Tauri-free module). Drive the stash/apply state
machine with the existing fake-Runtime bootstrap tests.
Explicit non-goals (v1)
- Native multi-window as the link's destination (G8).
avibe://show/<id>in v1 locates inside the main window. - Replacing https Workbench URLs in IM / mail.
- Authenticating the link (ids are capabilities-by-guess of a local-only app; loopback Workbench already assumes the user on the machine).
- Query parameters other than
request_idon/vaults. - Custom URL scheme beyond
avibe.
Sequencing
- Independent of G1 signing. Scheme registration works on unsigned acceptance builds.
- G4 may adopt these URLs as notification click targets in a follow-up; G4 v1 remains "focus the window".
- G6 (window state) is independent; a restored frame still receives the in-window navigation.
- G8, when it exists, may reinterpret
avibe://show/<id>as "tear out that Show Page"; the grammar stays, the destination policy is a G8 revision of this table's third column.