Desktop app¶

The desktop app runs the same sketcher as the browser, with native file open/save dialogs, recent files and a local Python server. The self-contained macOS package includes Electron, Python, RDKit, QVF and the browser editor. It supports Apple Silicon on macOS 14 or newer; no separate installation or first-run download is needed. Source installations still use their own Python environment. Windows and Linux packaging do not yet bundle Python.

What the self-contained app leaves out¶

The self-contained macOS app and Linux AppImage draw, import, export, clean up, prepare 3D structures and write calculation inputs on their own. They do not include vibe-scheduler or vibe-qc’s naming engine, and nothing installed beside the app reaches its bundled Python, so for now these need a source installation of vibe-sketcher, a checkout or the release wheel, set up as installation describes:

Submitting and following calculations. Where Submit to vibe-scheduler would be, the Inputs panel says so. Write inputs works as usual, and the written inputs can be run by hand or submitted from a source installation.
Species names. Species show no name: the naming engine is not installed; hovering over it gives the reason. Formula, SMILES, InChIKey and the other properties are unaffected.
Importing a structure by name and reading a campaign’s journal, which need OPSIN and vibe-scheduler in the same way.

Install and first run¶

When a release is available, download its macOS disk image or ZIP from the release’s download links and verify the published checksum. Open the disk image and copy vibe-sketcher to Applications, or extract the ZIP and move the app there. The app is ready to run offline.

The macOS app is ad-hoc signed, without an Apple Developer ID or notarization. Gatekeeper may block the first launch. If you trust the downloaded artifact and have checked its checksum, use System Settings → Privacy & Security → Open Anyway after the blocked attempt. Follow Apple’s instructions for opening downloaded apps; do not disable Gatekeeper globally.

Open the app from Finder or Spotlight. It starts its bundled chemistry engine and opens the editor when that engine is ready. Existing Python installations and saved interpreter records do not affect this package. A missing or broken runtime shows a repair page; retry, then replace the app with a fresh copy if the problem persists. Saved sketches are separate from the application bundle.

For a source installation, follow the desktop installation instructions. The source launcher follows its checkout and is distinct from a packaged app.

Open, save and recent files¶

Use File → Open (Cmd+O on macOS), File → Open Recent, a file drop onto the window or Dock icon, or Finder’s Open With → vibe-sketcher. A file double-click opens the user’s selected default app; choose vibe-sketcher as the default only if that is what you want. The installer offers file types without replacing an existing preferred application.

File type	Desktop association	Behaviour
`.vsk`	Editor	Open and save a native sketch document.
`.qvf`	Editor	Import a supported sketch or structure from the archive; saving a calculation result requires another destination.
`.mol`, `.sdf`, `.rxn`, `.cdxml`, `.ket`, `.xyz`	Viewer	Import the supported structure or reaction data into a sketch.

File → Save (Cmd+S) synchronizes the current drawing before writing. Save As (Cmd+Shift+S) selects another destination. A failed export, external file change or cancelled dialog leaves the original file untouched. For an imported or protected QVF, Save opens Save Sketch Copy with a suggested name such as result-sketch.qvf. Choose another destination to keep the original result payloads intact. Cancel leaves the sketch unsaved and keeps its original destination. Selecting the protected original still refuses replacement; subsequent saves use the new sketch copy. Native sketch QVF files save in place. The macOS Open dialog preserves the chosen symbolic-link name, including its extension, while save protection checks the target identity. Open Recent and the document name retain that selected path after opening or saving. QVF support is included in the macOS package. Source installs need the optional qvf-writer integration; .vsk works without it. See files in the app and formats.

Open Recent shows up to ten recent paths. Its Clear Recent entry clears the list; it does not delete documents. Missing or unsupported files produce an error without replacing the current drawing.

Settings and local files¶

Data	Default location
Recent file list	`~/.cache/vibe-sketch/recent.json`
Interpreter recorded by the CLI	`~/.cache/vibe-sketch/interpreter.json`
App-managed Python environment	`~/.local/share/vibe-sketch/venv`
Window state on macOS	`~/Library/Application Support/vibe-sketch/window-state.json`

The interpreter record and app-managed Python environment apply to source installations; the self-contained macOS app does not read them.

XDG_CACHE_HOME replaces ~/.cache, and XDG_DATA_HOME replaces ~/.local/share, when set in the app’s environment. Window state uses Electron’s platform-specific user-data directory. These are settings and environment records, not document storage; documents stay where you save them.

Updates and quitting¶

Help → Check for Updates checks the packaged app’s update feed. On macOS, the ad-hoc signed app offers a download link; it cannot install an update itself. Quit the app, download and verify the replacement, then replace the Applications copy. The replacement includes its matching Python runtime and packages. Keep your documents and settings.

For a source checkout, quit the app and run ./scripts/update-desktop.sh from the checkout root. That route updates the environment and browser and refreshes the source launcher. See updating a checkout.

Closing the last window leaves the app running. Launch the app again to reopen the editor on the current document; an editor that is already open is brought to the front. During startup or runtime repair, relaunching shows the existing setup window or waits for startup without starting another backend. Choose vibe-sketcher → Quit or press Cmd+Q to stop the app and its local server. This does not stop calculations already submitted to an external queue.

Help → Third-party Notices opens the bundled notice index. Packaged apps include browser and desktop dependency notices, Electron and Chromium texts, and the corresponding Indigo and separate InChI source archives. macOS apps also include Python/RDKit/QVF notices, Cairo and Eigen source, and native-library license texts under Contents/Resources/third-party/python/. See licensing.

Packaged macOS acceptance¶

For a release, perform this check on the exact candidate’s unpacked app and on a copy installed from its disk image or ZIP. Use disposable documents and an isolated test profile so existing user settings and file associations are preserved. Record the source commit, artifact checksums, macOS architecture, Python/package versions and the result of each step in the release issue. A source launcher or a successful package build does not establish this check.

Build the unpacked app with electron/build-desktop.sh --dir, then the macOS disk image and ZIP with electron/build-desktop.sh. Verify the app signature, version, bundled updater, file declarations and notices. When reusing qualified CI browser assets, keep their exact source identity and run the same packaging and notice checks.
Install a copy at a different path, including a path with spaces. Launch with a fresh user profile, only system tools on PATH, and deliberately invalid PYTHONHOME, PYTHONPATH and VIBESKETCH_WEB_DIST. The editor must load without setup or network access. Import a SMILES structure; export SVG, PNG and QVF, then reopen QVF and generate 3D coordinates. Verify that the child interpreter and imported modules live inside this installed app. In a disposable copy, remove the runtime manifest or use a mismatched version: the repair page must appear, without suggesting pip or an external interpreter. Exercise activation and pending file opens during startup and confirm there is only one backend. Keep source-launcher onboarding checks separate; installing a wheel must never repair a broken packaged runtime.
Open a .vsk and a supported .qvf through Finder double-click or explicit Open With. Exercise Open, Open Recent, window drop and Dock drop. Confirm the expected structure each time.
Edit and save a .vsk, reopen it and check the edit. Save As to another file. Import a calculation QVF, save the sketch elsewhere, and compare the original QVF checksum. Cancel a save dialog and check the original. Repeat Save As through a .qvf symbolic link whose target has another extension, and through a differently named link to a .qvf target. Protected result bytes must remain unchanged in both cases. A native sketch QVF selected through a link must retain QVF format across Save As, subsequent Save and reopen. Preserve the links themselves.
Open Third-party Notices and verify its referenced texts and source archives. Check that the macOS update action offers download/replacement rather than an unusable automatic-install action.
Close the window and reopen it; then quit the app. Confirm that its owned server process exits and its listening port closes. Reopen the app and confirm recent files still work. Remove the disposable test profile.

Complete this checklist with observed results before marking packaged desktop acceptance complete. Keep deployment credentials and machine-specific evidence outside product source.

Record failed checks as well as passing ones. If a repair changes the candidate, rebuild and repeat the affected checks on the resulting package; results from an older app do not qualify the corrected artifact. Never replace already published downloads with different bytes under the same version.

Self-contained Linux desktop¶

Linux x86-64 AppImages include Python and the application libraries. No external Python, pip, Node.js or source checkout is needed. Download the package and its SHA-256 checksum from the downloads page. Linux desktop downloads are public and require no supporter membership. macOS and Windows Store editions are planned paid purchases; their availability is separate from Linux downloads.

The initial Linux target is Debian 12 or Ubuntu 24.04 on x86-64 with a graphical desktop and standard GTK3, NSS, ALSA, OpenGL and X11/Wayland compatibility libraries. Make the AppImage executable and launch it as a regular user. If FUSE is not available, extract with --appimage-extract and launch squashfs-root/AppRun. The application and Python runtime remain inside that directory. Offline local work is supported; remote services and external calculation engines remain optional. Linux updates currently use replacement AppImages from the website.

Build natively on Linux x86-64 using electron/build-desktop.sh --linux. The Linux runtime lock pins interpreter and wheel hashes; the builder checks native library resolution and the installed runtime before packaging. Both platform locks use the supported QVF 0.6 toolkit. Runtime verification saves and reopens a native QVF document, comparing the complete document, so an importable but incompatible writer cannot pass the package check.