--- title: "Instalar y configurar el SDK de Linux" description: "Instala el SDK de Linux versionado, configura la identidad y el permiso de micrófono, y compila la aplicación de ejemplo." last_updated: "2026-10-13T16:35:20+03:00" --- # Instalar y configurar el SDK de Linux Source: https://busymate.ai/es/docs/guides/linux-sdk Last modified: 2026-10-13T16:35:20+03:00 Integrate Busymate AI in a Linux desktop app using the official Linux SDK distribution **1.0.1**: a C library on GTK4 and WebKitGTK 6.0, built with Meson, with GObject Introspection data for Python, GJS, Vala and Rust. Source, the configuration reference and a buildable demo live in the [public repository](https://github.com/serebano/busymate-ai-sdk-linux/tree/1.0.1), released as [1.0.1](https://github.com/serebano/busymate-ai-sdk-linux/releases/tag/1.0.1). Identity uses protocol v2 / bridge build 2.0.0; microphone uses protocol v1 / adapter 1.0.0. The [release manifest](https://github.com/serebano/busymate-ai-sdk-linux/blob/1.0.1/release-manifest.json) pins the source hashes. Its `CONTRACT-v2.md` hash matches `https://busymate.ai/sdk/v2/2.0.0/SHA256SUMS`. ## 1. Install the pinned version 1. Requirements: GTK 4.10 or later, WebKitGTK 6.0 at 2.42 or later, GLib 2.76 or later, json-glib 1.6 or later and Meson 1.0 or later. 2. Pin the library as a Meson subproject: a `subprojects/` wrap file that points at the repository with `revision = 1.0.1`, then the `dependency(…)` line the README gives, with `example=false` and `tests=false`. Alternatively, install system-wide from tag `1.0.1` with `meson setup`, `meson compile` and `meson install`. Consumers find it through `pkg-config` and include the SDK header. 3. Create the bridge with the assistant and origins, connect its signals, install it on your web view and create the microphone adapter before `webkit_web_view_load_uri`. Install both once per web view, before the first load. Read the [versioned installation instructions](https://github.com/serebano/busymate-ai-sdk-linux/blob/1.0.1/README.md) before wiring callbacks. ## 2. Load the chat as the window's page Use the chat URL and assistant slug from your workspace, for example `https://YOUR_ASSISTANT.busymate.ai/?channel=desktop_sdk&locale=en`. Keep the URL's supported parameters and set `channel=desktop_sdk`. The chat is the window's top-level page: it uses the normal chat layout and shows your `locale` from the first frame. Do not use `channel=embed`, which needs an allowed parent web page and refuses to start as a window, or `channel=desktop`, which is reserved for the Busymate AI desktop app. Allow only exact HTTPS origins, without wildcards. The assistant slug adds exactly `https://.busymate.ai`. Add `https://busymate.ai` when you load a `/support/` URL, and add your mapped support host if you have one. ## 3. Configure every supported callback The bridge is configured with construct properties and signals: | Setting | Purpose | | --- | --- | | `assistant` | Required assistant slug (construct property). | | `origins` | Extra exact HTTPS chat origins (construct property). | | `app-id` | App id that salts the account key; set it explicitly. | | `get-account` | Signal returning the current account ID, or `NULL` when signed out. | | `mint` | Required signal: ask your backend for a fresh token and nonce and answer the mint request object. | | `action` | Optional app action handler; return `TRUE` only when handled. | | `close` | Optional host dismissal signal. | | `open-uri` | Optional; return `TRUE` when you opened the HTTPS URI yourself. | Your backend must sign the supplied nonce with ES256, a unique `jti` and an expiry within 120 seconds. Never ship signing keys, cache launch tokens or log tokens. See [backend signing](https://busymate.ai/es/docs/guides/identity-backend-signing) and the [complete configuration reference](https://github.com/serebano/busymate-ai-sdk-linux/blob/1.0.1/docs/configuration.md). ## 4. Wire the OS microphone callback Call the bridge's `account_changed` function after login, logout and account switches. When the web process crashes, the bridge reloads the chat and sends `restored`. Unsandboxed apps have no per-app runtime microphone prompt; capture goes through WebKitGTK to PipeWire or PulseAudio. Under Flatpak, add the `--socket=pulseaudio` finish-arg. Under Snap, connect `audio-record`. The adapter grants WebKit capture for audio only, for an allowed origin, after a tap. The optional `request-permission` signal lets you show your own consent dialog. A mic or voice tap sends `busymate.microphone.v1.request` with `id` and `source`. The SDK obtains OS permission and returns `{ id, granted }`. Chat waits for that reply before capture or voice token minting. Denial and timeout fail closed, and cancellation prevents a delayed grant from starting a cancelled session. Opening the chat never asks. See [microphone lifecycle and troubleshooting](https://github.com/serebano/busymate-ai-sdk-linux/blob/1.0.1/docs/microphone.md). ## 5. Build and test the demo Run `meson setup _build && meson compile -C _build`, then run the example binary under `_build/example-app/`. Its Settings dialog changes the chat URL, locale, origins, guest or identified mint, microphone and close callbacks. Follow the [example-app build instructions](https://github.com/serebano/busymate-ai-sdk-linux/blob/1.0.1/example-app/README.md). Guest chat needs no fake identity, and authenticated tests use your own backend. The event log helps with integration troubleshooting without exposing credentials. Knowledge, tools, handoff, branding and voice availability are workspace features. Locale and appearance follow the supported hosted chat parameters. The SDK does not invent native flags for these services. ## Verify 1. Build the example app and verify guest chat, loaded with `channel=desktop_sdk`. 2. Load `?channel=desktop_sdk&locale=de`: the first frame is in German and the chat fills the window with no extra title-bar inset. 3. Use your backend to test sign-in, logout and account switching without history leakage. 4. On a real machine, test the first mic/voice grant, denial, retry after changing the OS setting, and cancellation while the prompt is open. 5. Test external links, close/action callbacks, window re-activation and renderer recovery. ### Which version should I install? Linux SDK distribution 1.0.1, pinned by tag in a Meson wrap or installed from the tag. The release also attaches a source tarball and an Ubuntu 24.04 x86_64 build with `SHA256SUMS`. ### Does the demo authenticate without my backend? No. Guest mode works when your workspace allows it; authenticated mode requires your real backend and a current session. ### Which updates require an app release? SDK changes, OS permission declarations and native capabilities require an app release. Hosted chat changes arrive from the service.