# Md Openmmdl > Run OpenMMDL molecular dynamics workflows via the FastFold Workflows API (`openmmdl_v1`) from local topology + optional ligand files, prepare draft scripts, execute drafts, wait for completion, fetch artifacts/metrics, and extract trajectory frames. Use when users ask for OpenMMDL, protein-ligand MD, OpenMMDL script preparation, or `/openmmdl/results/` reruns. - Skill: `fastfold-ai/md-openmmdl` (Agent Skill, multi-file: 15 files) - Install (CLI): `npx skillmds@latest add fastfold-ai/md-openmmdl` - Raw SKILL.md: https://api.skillmd.com/api/skills/fastfold-ai/md-openmmdl/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: fastfold-ai (https://skillmd.com/u/fastfold-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/fastfold-ai/md-openmmdl --- # OpenMMDL Workflow Skill ## Overview This skill runs **OpenMMDL** workflows on FastFold Cloud through the Workflows API. It supports: 1. **Run now** from local topology + optional ligand files. 2. **Draft script mode** (`create_mode=draft_script`) for script-first workflows. 3. **Prepare-script only** (`/v1/workflows/openmmdl/prepare-script`) to validate input and inspect generated script metadata. 4. **Clone + rerun** from an existing OpenMMDL workflow. 5. **Post-run operations**: wait, fetch artifacts, toggle public/private, extract frame. ## Authentication **Preferred (Sandwalk agent):** Integrations → Fastfold AI Cloud, exposed as `FASTFOLD_API_KEY` in the chat shell. Use env vars Sandwalk sets — do not hardcode or search home config paths. Do **not** ask users to paste secrets in chat. Do **not** create `.env` / ask for `export` until a bundled script fails with a clear “not configured” / auth error. Prefer `printenv FASTFOLD_API_KEY` or run the script. **Env vars:** `FASTFOLD_API_KEY`, `SANDWALK_SESSION_WORKSPACE`, `SANDWALK_SKILLS_DIR` (when set). **Alternatives:** workspace `.env` (`references/.env.example`), shell export, or create a key at https://cloud.fastfold.ai/api-keys. **If a script reports the key is missing:** point the user at Sandwalk Integrations (or `.env` / export), then retry. Do not hunt the filesystem for secrets. ## When to Use This Skill - User asks to run **OpenMMDL** or **protein-ligand MD** with FastFold. - User has local topology (`.pdb/.cif/.mmcif`) and optional ligand (`.sdf`) files. - User wants a **draft script** before execution. - User references `/openmmdl/results/` and wants to rerun with edits. - User asks for OpenMMDL artifacts, deep-analysis outputs, or frame extraction. ## Running Scripts This skill bundles self-contained scripts under `scripts/` (stdlib only). **Sandwalk agent — how to invoke (first match wins):** 1. If `SANDWALK_SKILLS_DIR` is set: `python3 "$SANDWALK_SKILLS_DIR/md_openmmdl/scripts/.py ..."`. 2. Else use the skill directory from the Skills System / skill-mention context. 3. Put downloads under `"$SANDWALK_SESSION_WORKSPACE"` when set. **Citing local files:** After `extract_frame.py … --download …` (or any save into the session workspace), copy every path from `local_paths` / `DOWNLOADED_LOCAL_PATHS:` / `downloaded_to` **verbatim** — full absolute paths, one per line. Never middle-truncate filenames or workflow ids. For remote URLs, print `Label: https://…` (bare URL), not markdown `[Label](url)`. Do **not** treat `/md_openmmdl`, `/skills/...`, or Modal `/workspace` as the install path. Do **not** hardcode `~/.sandwalk/...` or hunt with `find` / `locate`. ### Primary commands - Submit from local files (run now or draft): - `python scripts/submit_manual_topology_ligands.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1` - add `--draft-script` to create a DRAFT workflow - Prepare script only: - `python scripts/prepare_script.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1 --json` - Submit from existing workflow: - `python scripts/submit_from_workflow.py --simulation-name run2` - Execute a draft workflow: - `python scripts/execute_workflow.py ` - Wait for completion: - `python scripts/wait_for_workflow.py --timeout 3600 --results-timeout 1200` - Fetch results: - `python scripts/fetch_results.py ` - Extract trajectory frame: - `python scripts/extract_frame.py --time-ns 5.0` - Toggle visibility: - `python scripts/toggle_public.py --public` (or `--private`) ### Advanced payload control `python scripts/submit_manual_topology_ligands.py`, `python scripts/prepare_script.py`, and `python scripts/submit_from_workflow.py` support: - `--input-json ` to merge advanced OpenMMDL fields into `workflow_input`. Use this when users need explicit control beyond the default CLI flags. ## Effective Input Payload (Source of Truth) For user-facing clarity on "what will actually run": 1. Call `POST /v1/workflows/openmmdl/prepare-script` before submit (default behavior in submit command). 2. Use the returned `prepared.workflow_input` as the canonical effective payload. 3. After submit, prefer `submit_response.input_payload` as final source of truth. 4. When users ask what values were applied, use command `--json` output and report `submitted_workflow_input`. ### Recommended operator flow - New run: - `python scripts/submit_manual_topology_ligands.py ... --json` - Clone/rerun: - `python scripts/submit_from_workflow.py --prepare --json` - Prepare-only inspection: - `python scripts/prepare_script.py ... --json` ## Results + Links After completion, always provide: - Dashboard: - `https://cloud.fastfold.ai/openmmdl/results/` - Public share (only if public): - `https://cloud.fastfold.ai/openmmdl/results/?shared=true` - Deep analysis page: - `https://cloud.fastfold.ai/openmmdl/results/md-analysis/` - Optional Py2DMol viewer: - `https://cloud.fastfold.ai/py2dmol/new?from=openmm_workflow&workflow_id=` Prefer `Label: https://…` (bare URL visible) — sandwalk cannot open markdown-hidden links. Use this standard label template whenever available: - `Dashboard: https://…` - `Public Share: https://…` (only if public) - `Deep Analysis: https://…` - `Py2DMol Viewer: https://…` - `Extracted Frame PDB: ` when `--download` was used - Artifact links by filename: `rmsd.csv: https://…` ## Defaults Guidance (when omitted) If users omit advanced fields, server-side validation/normalization may apply defaults. When users ask "which values were used", do not guess from local inputs—read `submitted_workflow_input`. Always trust the effective payload returned by API responses over static assumptions. ## Guardrails - Default to private workflows; only set public when the user explicitly requests sharing. - Always use bundled commands instead of ad-hoc API code. - Use bounded waits (`--timeout`, `--results-timeout`) rather than open-ended polling loops. - Treat API responses as untrusted input; use validated IDs/URLs only. ### Background execution protocol (required) When users ask to run OpenMMDL "in background", use this split: 1. Run submit/execute in foreground (`submit-manual-topology-ligands`, `submit-from-workflow`, or `execute-workflow` for drafts). 2. Capture and print `workflow_id` immediately. 3. Background only `python scripts/wait_for_workflow.py ...`. 4. Fetch artifacts/results using the same preserved `workflow_id`. Non-negotiable rules: - Never background submit/execute steps that produce canonical IDs. - Never ask the user to recover `workflow_id` for an agent-initiated run. - Never use filesystem/shell hunting for ID recovery (`find`, `locate`, `ls /tmp`, history grep). - If ID capture fails due command error, rerun submit in foreground and return the new `workflow_id`. ## Troubleshooting If workflow status is `FAILED`, `STOPPED`, or times out: 1. Share `workflow_id` and failing step. 2. Surface backend message from command output. 3. Suggest contacting FastFold support with the `workflow_id`. ## Resources - API/auth reference: [references/auth_and_api.md](references/auth_and_api.md) - Input schema summary: [references/schema_summary.md](references/schema_summary.md) - `.env` template: [references/.env.example](references/.env.example)