Quickstart

Note

Start with the published 0.6.3 source archive and its checksums, or an existing authorized checkout. The GitHub mirror does not yet contain a published source snapshot. Extract the archive and enter its repository directory.

This walkthrough uses the supported vibe-sketch command available in that published source. The preferred vibe-sketcher launcher requires a rename-aware build; see names and compatibility.

For a guided introduction with screenshots, start with Your first molecule. The tutorials also cover reactions and calculation inputs; runnable examples provide downloadable files and scripts.

From the extracted source directory or a checkout, install and start the app:

./scripts/install.sh
.venv/bin/vibe-sketch serve --open

install.sh creates .venv, installs vibe-sketcher and builds the browser app when Node.js is installed. serve --open starts the server on port 8766 (or the next free port, which it prints) and opens the app in your browser.

Document actions and drawing tools become available after the initial document has loaded. If startup fails, the header keeps a retry hint and the error message explains what failed; reload the page after correcting it.

Draw, import, save, export

  • Draw with Ketcher’s palettes: bonds and chains, rings, elements and the periodic table, functional groups, charges, reaction and curved arrows, text. Clean up standardizes bond lengths and angles.

  • Import ▾ adds structures to the drawing: a SMILES string (a reaction as A.B>>C), a compound name, or a file.

  • The properties panel lists each species with its formula, masses, charge, multiplicity, SMILES, InChIKey and name, and each reaction the drawing implies. Type a compound number into a species’ box; change a multiplicity the drawing cannot know, such as a metal’s.

  • Save downloads a QVF file, the vibe family’s format (a .vsk without qvf-writer; install it with ./scripts/install.sh --qvf-path ../qvf). Started with a file, serve saves back to it instead:

    .venv/bin/vibe-sketch serve scheme.qvf --open

  • Export ▾ writes SVG, PNG, MOL, SDF, RXN, SMILES, InChI or KET.

Generate 3D and write calculation inputs

After drawing or importing a molecule, check its charge and multiplicity in the properties panel. Generate 3D creates geometries for species without one; Generate or Redo on a species card works on that species alone. See 3D structures for geometry and stereochemistry checks and force-field limitations.

In Inputs, choose vibe-qc (script), select the task, method, basis and any supported options, and tick the species to include. Write inputs downloads one input or a zip of several. Missing 3D geometries are generated first. Unsupported settings are refused with a reason; see the input writer reference. Writing an input does not execute it. If you also use ORCA, select it as the alternative calculation program.

Submit, calculate and analyze

For queued work, install and configure vibe-scheduler, start its daemon, and register your working vibe-qc interpreter as vibeqc, as described in the app guide. Submit to vibe-scheduler sends the prepared inputs to that queue. The Calculations section shows recorded runs, updates their status and lets you cancel unfinished work. The calculation runs in the selected program, outside the sketcher.

Open supported result files in vibe-viewer for analysis. View in 3D or Send to vibe-viewer on a species card instead sends the prepared structure; it does not create a calculated result. See the viewer hand-off. Without a queue, run the downloaded input directly using the selected program’s instructions.

Run the desktop app

The Electron shell is available from the same checkout. After running the installer at the top of this page, install its pinned runtime:

python3 electron/install-electron.py
python3 electron/install-electron.py --check

On macOS, open the installed Sketcher app from Finder or Spotlight after the installer creates its source app; older builds display vibe-sketch. With npm available, start the source shell on any supported platform with:

cd electron
npm start

The desktop window uses the same drawing, 3D and calculation-preparation interface as the browser. This source route is available now; public release packages have their own publication status. See desktop installation for updates and the remaining desktop features.

The same from the command line

.venv/bin/vibe-sketch convert "Brc1ccccc1.OB(O)c1ccccc1>>c1ccc(-c2ccccc2)cc1" --from smiles -o suzuki.vsk

.venv/bin/vibe-sketch info suzuki.vsk

.venv/bin/vibe-sketch render suzuki.vsk -o suzuki.svg

For a small molecular input example:

.venv/bin/vibe-sketch convert CCO --from smiles -o ethanol.vsk
.venv/bin/vibe-sketch embed ethanol.vsk
.venv/bin/vibe-sketch input ethanol.vsk --all --program vibeqc --task sp --method B3LYP --basis def2-SVP --output-dir inputs

With vibe-scheduler and vibe-qc configured, submit and inspect runs:

.venv/bin/vibe-sketch submit ethanol.vsk --all --program vibeqc --task sp --method B3LYP --basis def2-SVP
.venv/bin/vibe-sketch runs ethanol.vsk

The submit command embeds any species that still lacks a 3D geometry and records successful submissions in the document. See the CLI reference for refusals, exit statuses and cancellation.

Names

Names use the optional standalone vibeqc-naming package. Install it in the same Python environment as vibe-sketcher; no quantum-chemistry core is needed:

python -m pip install --find-links https://vibe-qc.com/updates/vibeqc-naming/0.1.1/index.html 'vibeqc-naming>=0.1.1,<0.2'

The adapter sends explicit bonds, hydrogens and RDKit CIP labels to the engine; it does not embed a conformer or perceive the drawing’s bonds again. R/S and E/Z names are available within the engine’s supported vocabulary. A stereo name is verified only if mapping it back reproduces the full stereochemical identity. Otherwise it remains an unverified suggestion, even when the connectivity matches. Ions and radicals remain unsupported.

Every name the engine suggests is checked against the drawing first; see the browser app.