Set up the desktop companion

Overview

The MetaLens360 Companion is a small desktop application for the Meeting Copilot. It does the three things a browser cannot:

Everything else — transcription, suggestions, the review where you save, share or discard — is the MetaLens360 server and web app. The companion streams the same audio frames over the same connection as the browser, so the server has one ingestion path and one set of rules. After Stop, the companion links to the review in the web app; it deliberately has no review screen of its own.

What it stores and sends

The 15-minute access token lives only in the application's main process; the overlay and the other windows never see a credential. The companion never asks for your password.

Before you start

• Pairing a device needs Record meetings and dictate, and the workspace policy must allow the Desktop companion (on by default). See Roles and permissions.
• Use the installer your administrator points you to. Builds must be signed: an unsigned or development build attributes macOS permissions to the terminal that launched it, so capture works properly only in a signed build.
• Windows 10 version 2004 or later, or Windows 11; macOS 13 or later (14.2 or later recommended); Linux with PipeWire (second tier, experimental).

Steps

Install and grant permissions — Windows 10 (2004+) and Windows 11

1. Run the installer (per user, no administrator rights needed).
2. On first capture Windows may ask for microphone access (Settings → Privacy & security → Microphone → allow desktop apps). Meeting audio needs no permission: it is loopback of the default playback device.
3. Done. The tray icon shows the state; the overlay appears top-right.

If the companion says no speaker output was found, set a default playback device in Sound settings. Click-through hover detection pauses while an elevated (Administrator) window is in the foreground. Content protection works from Windows 10 2004; older Windows shows a black box instead.

Install and grant permissions — macOS 13 or later (14.2+ recommended)

1. Open the notarized disk image, drag the app to Applications, launch it. The app lives in the menu bar; the Dock icon shows only while the control window is open.
2. Microphone: macOS prompts on first capture; choose Allow.
3. Meeting audio depends on the version:
   • 14.2 and later — captured with Core Audio taps, gated by System Audio Recording (System Audio Recording Only in Privacy & Security). macOS prompts once; choose Allow. If the permission is missing or denied, macOS still hands the app a silent audio track and reports no error. The companion watches the levels for three seconds and tells you (no meeting audio); fix it in System Settings → Privacy & Security → Screen & System Audio Recording → System Audio Recording Only → enable MetaLens360 Companion → quit and reopen the app.
   • 13.0 – 14.1 — captured with ScreenCaptureKit, gated by Screen Recording. First capture prompts once; if denied, System Settings → Privacy & Security → Screen Recording → enable → quit and reopen.
   • 12 and earlier — no system-audio API. Microphone-only works; a virtual audio device set as the microphone is the workaround.
4. Screen Recording is also needed for Ask about a screen region. There is no in-app prompt once it has been denied; enable it in System Settings and relaunch.
5. macOS 15 and later may show a recurring "… is requesting to bypass the system private window picker" alert for apps that capture the screen directly. Allowing it for a month is fine. Settings → Capture in the companion offers Apple's content picker as an experimental alternative (it avoids the alert, but the companion cannot attach loopback audio itself through the picker — whether audio comes along depends on what you pick).

Content protection on macOS is cosmetic: ScreenCaptureKit-based recorders (QuickTime, OBS, some Zoom modes on 14/15+) capture the overlay anyway.

Install and grant permissions — Linux (second tier, experimental)

Requirements: PipeWire with pipewire-pulse; pw-record (pipewire-utils) or parec (pulseaudio-utils) for the audio helper; a desktop with xdg-desktop-portal (ScreenCast v4+ for restore tokens).

1. Make the AppImage executable and run it (or integrate it with AppImageLauncher so the desktop id is registered — Wayland global shortcuts need a valid desktop id).
2. The portal picker appears on each start unless your desktop supports restore tokens (the companion stores the token).
3. Loopback audio on PipeWire is undocumented. If the meeting-audio meter stays flat after start, the companion starts the audio helper, which records the default output's monitor and splices it into the meeting channel. Alternatively select a Monitor of … input as the microphone in your sound settings.

Not available on Linux: content protection, window opacity (the overlay uses a translucent background), hover-based click-through (the whole overlay is either interactive or click-through), guaranteed always-on-top under Wayland. If the desktop has no secret service, the pairing is kept in memory only and you pair again after a restart — the app says so.

Pair the companion with your account

1. In the companion, enter your MetaLens360 address (secure https addresses only) and a name for this computer, for example Priya's MacBook.
2. The companion shows a code such as ABCD-EFGH and opens the Pair a desktop companion page of the web app, where you are already signed in. You can also open Overview → Meeting Copilot, the Devices tab, Pair device, and type the code yourself.
3. Check that the Pairing code matches what the companion shows, optionally change the Device name, and click Approve this device. The device is bound to your user and workspace.
4. The companion receives its credentials within a few seconds and stores only the device token, encrypted by the operating system. Codes expire after ten minutes; a declined pairing is reported as declined.

The companion renews its credential on its own (the server allows 30 renewals an hour per device). If a renewal fails in a way that may have reached the server — it timed out, the connection dropped mid-answer, the server returned an error or an unreadable answer — the companion presents the same credential again after 10, 20 and 40 seconds, never later than 90 seconds after the first attempt. The server answers that repeat with a fresh credential for two minutes after the renewal it repeats (audited as COMPANION_TOKEN_RETRANSMIT), so a dropped answer does not unpair the device. After the computer wakes from sleep, a renewal that fails this way gets its own retries too. A renewal that never left the computer (offline, no DNS, connection refused, certificate error) changes nothing and is tried again when a credential is next needed. The same credential presented later than those two minutes, or the credential issued for the lost answer presented at all, is treated as a copy in someone else's hands: the device is revoked and must be paired again. The one exception is a network address — or IPv6 /64 network — that has already sent 600 refused renewals within the hour: from there such a credential is refused with Too many invalid refresh attempts from this address. Try again later., without revoking the device and without an audit row. No new credential is issued either way.

To revoke a device later, open Overview → Meeting Copilot, the Devices tab, and click Revoke on its row (a holder of Manage meeting policy and sessions sees every device in the workspace). MetaLens360 refuses the device's next request at once, and its stored credential can no longer be renewed. A live connection that is already open ends within 10 minutes, at the server's next check. Unpair in the companion is immediate and deletes the stored credential. Unpairing or a revocation also makes the companion forget its current session and review link, so after you pair again it starts at Ready.

Use the overlay

• Start listening opens the consent card: the workspace's consent text, the sources (microphone, meeting audio), the participant-notice checkbox when the policy requires it, and ephemeral mode when the policy defaults to it. Nothing is captured before you agree; the server also refuses a session without a current consent record.
• The status strip is the persistent indicator: Ready / Listening / Transcribing / Processing / Paused / Stopped / Reconnecting, elapsed time, source chips, provider, and Stop — one action, also a global shortcut, also in the tray menu. The tray icon changes shape with the state.
• Suggestions arrive privately as the conversation raises questions, with Confirmed / Likely / Hypothesis labels and citations; Helpful, Not helpful and Dismiss feed the evaluation; Deeper runs the full copilot on the same question. Late and superseded suggestions grey out rather than disappearing.
• Transcript expands on demand; instruction-like speech the server flagged is marked ignored.
• Ask anything about the meeting; typing briefly gives the overlay keyboard focus and releases it on blur. Questions, including screen-region ones, are answered for the org the session was set up with.
• Ask about a screen region: drag a rectangle on any display; the pixels go once to the server for text extraction and are discarded. You can ask up to 10 of these a minute. Off when the policy disables Screenshot questions from the companion.
• After Stop, the overlay links to the review in the web app: there you save, share (as a candidate learning) or discard each insight, decide the transcript's fate, and see impact previews before deletion.
• Drag the strip to move the overlay; drag the corner handle to resize; opacity, density, click-through and position reset are in Settings.

Shortcuts

Defaults (all rebindable in Settings; Ctrl on Windows and Linux, ⌘ on macOS):

A combination another application already owns is reported next to the binding (in use elsewhere); one already bound to another of the companion's own actions reads not set: … is used by “Show or hide the overlay” (naming that action), and choosing it in Settings is refused with … is already used by “Show or hide the overlay”. The previous binding stays until a new one registers. Because a global shortcut takes the keys away from every application, the companion refuses combinations that would hijack typing or a system command:

• A letter, digit, punctuation or navigation key (Space, Tab, the arrows, Home …) needs two modifiers, such as Ctrl/⌘ + Shift, Ctrl/⌘ + Alt or Alt + Shift. Alt + M or Ctrl + K alone is refused: … cannot be used: hold two modifiers (for example Ctrl/⌘ + Shift), or Ctrl/⌘ or Alt with a function key.
• A function key (F1–F24) needs Ctrl/⌘ or Alt. Shift alone never counts as a modifier.
• System and editing commands are reserved by the system and refused with … is a system shortcut (copy, paste, quit, screenshots …); choose another: among them Alt + F4, Alt + Shift + Tab, Ctrl + Alt + Delete, the macOS screenshot keys, and Ctrl/⌘ + Shift + Z, V or C (redo, paste and copy in terminals, the browser's inspect element). Ctrl, ⌘ and the Windows key count as the same modifier here.
• A saved binding that breaks these rules — for example one chosen in an earlier version, before two modifiers were required — falls back to its default, which is saved. The first window that opens says so once: Some saved shortcuts are no longer allowed and were reset to their defaults (…), naming each binding, its default and, for a reserved one, (reserved by the system).
• If that default is already another action's own binding (you moved, say, Show or hide the overlay to Ctrl/⌘ + Shift + S), the other action keeps it and this one is left with no shortcut. Nothing is saved, so at every start the companion says “Stop listening” has no shortcut: its saved … is no longer allowed, and … is already used by “Show or hide the overlay”; choose another shortcut for “Stop listening” in Settings → Keyboard shortcuts. until you pick one. Stop in the status strip and the tray menu still works.

On Wayland, shortcuts go through the GlobalShortcuts portal (GNOME asks once, KDE binds silently; an invalid desktop id makes GNOME deny every bind silently).

Hide the overlay from screen sharing — what it is and is not

The setting is labelled Hide overlay from screen sharing (best effort), and that label is the contract:

• Windows: removes the window from most capture on Windows 10 2004+; Microsoft documents it as not a security feature.
• macOS: honoured by older capture paths, not by ScreenCaptureKit-based recorders.
• Linux: no equivalent; the option is disabled.

It cannot hide the overlay from a camera or capture card, from the viewer of a remote-desktop session, from software running inside your session with elevated rights, or from newer macOS recorders. Screen readers may not read the overlay while it is on. If the overlay must not be seen, share a window instead of the screen, or put the overlay on another display.

Example

Lee runs Zoom's desktop client on a MacBook with macOS 14.4. He installs the companion from the notarized disk image, pairs it from the code it shows, and clicks Start listening before his design review. macOS asks once for System Audio Recording; he allows it, and the meeting-audio meter moves. Halfway through, a colleague shares an error dialog; Lee presses ⌘ + Shift + R, drags a box around it and asks "what does this exception usually mean for our CPQ triggers?" — the text is read from the pixels, the image is dropped, and the answer cites a learning from an earlier incident. After Stop he clicks the link to the review in the web app.

FAQs

Why a separate application?

Capturing the audio of a native meeting client is something browsers forbid for good reasons. The companion asks the operating system for that audio once, with its own permission prompts, and does nothing else that the browser could do better.

Does the companion have the review, notes or export?

No, by design. Those live in the web app; the companion links to the right page after Stop.

How long is a revoked companion still able to connect?

Its next request is refused and its credential cannot be renewed, both straight away. Only a live connection that was already open can last longer: up to 10 minutes, until the server checks it again. Unpair in the companion itself is immediate. Either way the companion then forgets the current session, and a revoked device must be paired again.

What happens to the audio while the companion reconnects?

When the server asks the companion to renew its credential mid-meeting, the companion holds up to 80 seconds of audio while it renews and reconnects, then sends it. Anything beyond that is dropped and reported — N s of audio could not be delivered while reconnecting — never lost silently.

Where are my settings?

In the app's user-data folder, in a plain settings file with no secrets; the device token is in the operating system's credential store.

Troubleshooting

Related articles

• Meeting Copilot — private suggestions while you talk
• Meeting privacy, consent and retention
• Dictate instead of typing
• Roles and permissions