brymol Documentation

Introduction

brymol embeds an open source PyMOL instance and exposes it through a chat interface and a 3D viewport in one window. You write a request in natural language. A model converts it into PyMOL commands. brymol classifies each command, previews it, and runs it against the embedded session.

Because PyMOL runs in the same process, brymol reads the live session (objects, chains, ligands, selections) and sends that state to the model as context, and it can render the viewport to an image for vision models. Tasks it handles: loading by PDB id or name, selections, representations and colouring, measurements, alignment, mutagenesis, scenes, and ray-traced figures.

Requirements

No separate PyMOL install is needed. The installer provisions an isolated PyMOL build so it will not touch or conflict with any existing PyMOL on your machine.

Installation

The macOS download is a DMG containing a standard installer package. It installs brymol.app into Applications and support files into Application Support. On first launch, brymol provisions Miniforge (a minimal conda distribution), creates an isolated environment with Python 3.11 and the open source build of PyMOL, and installs brymol's Python dependencies. The runtime setup is idempotent, so running it again is safe and only fills in what is missing.

Standard install

1. Download the macOS DMG, then open it.
2. Right-click brymol-installer.pkg, choose Open, then confirm Open if macOS asks.
3. If macOS blocks it, open System Settings, go to Privacy & Security, then choose Open Anyway.
4. On first launch, wait for the runtime setup to finish. It can take a few minutes while PyMOL downloads.
5. Launch brymol from Spotlight (Command-Space, then type "brymol") or from the Applications folder.

open downloads/brymol-macos.dmg

What the installer does

OpenRouter Setup

brymol calls models through OpenRouter: one key, one billing account, many providers. It uses the OpenAI-compatible chat completions endpoint at https://openrouter.ai/api/v1.

Step by step

1. Sign up at openrouter.ai.
2. Open Settings, Credits, and add a balance. Five dollars is plenty to start.
3. Open Settings, Keys, Create Key. Optionally set a credit limit on the key as a hard spend cap.
4. Copy the key (it starts with sk-or-).
5. In brymol, open Settings, paste the key, pick a model, and save.

Key storage

The key is written to the macOS Keychain through the system keyring, never to a plain text file. brymol also reads it from an environment variable. Lookup order: environment variable, then Keychain, then any legacy value in settings.

export OPENROUTER_API_KEY="sk-or-..."

Models

Agent mode and Explain send a rendered image, so they need a vision capable model. The default is vision capable. Any OpenRouter model id can be typed into the model field. The HTTP client uses a request timeout and retries on transient failures.

Cost control

• Spend is yours and visible in the OpenRouter dashboard, capped by the credit you load.
• brymol caps output tokens per call (chat and agent steps around 1500, Explain around 900) to avoid reserving large amounts of credit per request.
• A chat request on a cheap model costs a fraction of a cent. An agent run with vision is a few cents because it sends images over several steps.
• Set a per-key credit limit in OpenRouter as a hard backstop.

How It Works

Process model

When PyMOL is importable, brymol hosts the PyMOL OpenGL viewport widget in the same process and drives the command layer directly. No second window, no network bridge. If PyMOL cannot be imported, it falls back to a local HTTP bridge against an external PyMOL. Both expose the same engine interface (run commands, read session, snapshot, render).

Request pipeline (chat)

brymol sends your text plus a session summary. The model must return JSON in this schema. brymol validates it, classifies each command, and shows a preview. Commands run on confirm, or immediately for SAFE commands in Bypass mode.

{
  "intent": "short label",
  "explanation": "what the commands do",
  "requires_confirmation": true,
  "commands": ["fetch 1ubq", "show cartoon", "color marine"]
}

If the model replies with prose instead of JSON, brymol surfaces that text as a chat message rather than failing.

Session context sent to the model

Coordinate files are not uploaded. The model sees this summary, and in vision modes a rendered image.

Load by name

A fetch by name (for example fetch hemoglobin) is resolved to a PDB id with an RCSB text search before it runs. If the name spans more than one source organism, brymol groups hits by organism and asks which species, then re-runs with the chosen id. PDB ids and UniProt accessions are detected and passed through unchanged.

Agent mode

Agent mode is an iterative tool-calling loop. The model calls two tools: run_pymol_command and look_at_structure, which auto-frames the view, ray-traces it to a PNG, and returns it as a vision input. The loop runs to a fixed step cap, and a repetition detector aborts it if it stalls or oscillates. Safety classification applies to every command, and BLOCK is refused inside the loop.

Undo and history

brymol snapshots the full session (get_session) before each change and restores it (set_session) on undo, so Undo and Redo recover the entire scene rather than reversing a single command. Conversations persist locally and are reachable from the Recent menu.

Features

Drag and drop a structure file (.pdb, .cif, .sdf, .mol2, .pse and others) onto the 3D view to load it. Every toolbar action snapshots first, so anything can be undone.

Selections & Syntax

brymol generates standard PyMOL selection algebra. Knowing it helps you phrase requests precisely and read the previewed commands. Selectors below combine with the operators and, or, not, and parentheses.

Proximity operators

select site, byres (polymer within 5 of organic)
select iface, byres (chain A within 5 of chain B)
select pocket_polar, site and (resn ASP+GLU+LYS+ARG+HIS)
select bb, name C+N+CA+O

Commands brymol emits

Common verbs in generated and toolbar commands: fetch, load, show and hide, color with the util.cbc / cbag / cbay / cbao / cbac helpers, spectrum, select, zoom and orient, distance, align / super / cealign, dss, cartoon putty, set, scene, and png for ray-traced output. Mutagenesis is run through the PyMOL mutagenesis wizard rather than a single command.

Privacy & Data

brymol runs locally. The only time data leaves your machine is when you call the model, fetch a structure, or run a search. This section states exactly what is sent and where.

What is sent to the model

When you send a chat or agent request, brymol transmits your text, a compact text summary of the current session (object names, chains, ligand residue names, enabled objects, and a small sample of atoms from active selections), and the model id, to OpenRouter and the provider you selected. In Agent mode and the Explain feature, brymol also renders the current viewport to a PNG image and sends that image so the model can see the structure. Full atomic coordinate files are not uploaded. The model sees the text summary and, where vision is used, the rendered picture.

What is fetched from public databases

Loading a structure by id or name downloads coordinates from RCSB, and AlphaFold lookups query the EBI AlphaFold service. These are standard requests to public scientific databases, made directly from your machine.

What stays on your machine

Your API key is stored in the macOS Keychain. Conversation history, recently loaded structures, application logs, and the structured error log are all written under ~/.pymol_ai_companion and are never transmitted. Downloaded structures are cached locally in that same directory.

Third party handling

Prompts and images you send are received by OpenRouter and the underlying model provider, and are subject to their data and retention policies. If you work with confidential or unpublished structures, review those policies and use your OpenRouter account settings to control routing and retention. Do not send anything you are not permitted to share with a third party service.

Command Safety

A language model can produce any text, including commands that would run code or touch the file system. brymol does not trust model output. Every command, whether from chat, from the agent, or resolved from a name, is classified before it can run. There are three outcomes.

What is blocked

The classifier rejects line prefixes that escape into a shell or the Python layer, the command verbs that run or load code (such as python, run, spawn, system, exec, eval, import, alias, and extend), dotted calls into the PyMOL or command internals, dangerous tokens that appear anywhere in a line (such as os., eval(, exec(, system(, and double underscores), and loading or running script files with extensions like .py, .pml, .sh, or .bash. The intent is defence in depth, so that even an unusual phrasing that slips past one rule is caught by another.

Troubleshooting

Reference

Keyboard and input

Run from source

./brymol.sh                                  # launch the app
./build_app.sh                               # rebuild brymol.app
ruff check app                               # lint
QT_QPA_PLATFORM=offscreen python3 -m pytest app/tests -q   # run tests

Example prompts

fetch 3HTB
colour key binding residues
show the protein as cartoon and the ligand as sticks
colour by chain and hide waters
align this onto 1ubq
make a publication quality view of the active site