OpenDDE Harness

Harness for agentic antibody design: prepare targets, optimize CDR sequences, predict structures with OpenDDE, and inspect results. Supports VHH, scFv and paired VH/VL binders while preserving configured fixed residues.

• Guided setup and reviewed design plans in natural language.
• Generate antibody sequences through LLM reasoning and structural verification.
• Agentic evolutional discovery for antibody design.

[!NOTE] OpenDDE Harness is an early preview, and you may encounter bugs. If something goes wrong, please open an issue with steps to reproduce it and your ddeharness doctor --json output. Your feedback helps us fix problems and improve the tool together.

News

• 2026-09-09: Introducing OpenDDE Harness (preview) for agentic antibody design! Read the technical report.
  • Design VHH, scFv, and paired VH/VL binders with LLM-guided sequence optimization and OpenDDE structure prediction.
  • Get started with the installation guide, onboarding, and design examples.
  • Inspect candidate sequences, structures, and design progress in the tracing dashboard.

See the changelog for release details.

https://github.com/user-attachments/assets/1530c7e6-9a7e-4069-b861-0e6cf58e6752

Installation

Use a Linux or macOS client with Python 3.12 or newer. Native Windows is not currently supported. Use uv to install the opendde-harness package and its ddeharness command in an isolated environment. No environment activation is needed.

Install from PyPI

uv tool install --python 3.12 opendde-harness

The release wheel includes the built terminal UI.

To update a PyPI installation, close the TUI and run:

uv tool upgrade opendde-harness

OpenDDE Harness checks PyPI once a day and says when a newer release is out: in the TUI's status bar and once in its transcript at launch, and in ddeharness doctor. ddeharness upgrade runs the update for your kind of install (uv tool upgrade or pip install --upgrade). Set OPENDDE_HARNESS_NO_UPDATE_CHECK=1 to turn the check off.

After installation

After installation, verify the client:

ddeharness --version
ddeharness --help
ddeharness tui --check

If the command is not found, run uv tool update-shell and open a new terminal. Updates preserve configuration, results, and model data. Running compute containers keep their current code until they exit; later starts use the updated code. See the installation guide for runtime overrides, compute environments, and model download options.

Uninstall

Close the TUI and remove the client with:

uv tool uninstall opendde-harness

Configuration, results, model data, and compute services are retained.

Quick Start

1. Configure the client and compute

ddeharness onboard

Follow the wizard to configure your LLM provider, optional memory, and a local Docker environment or existing Linux compute service. Choose API or local OpenDDE folding; both use the Harness compute service.

Local compute requires Linux x86-64 and Docker; CUDA also requires NVIDIA drivers and NVIDIA Container Toolkit. See onboarding for setup and model preparation details.

After setup, check your configuration, memory service, and compute readiness:

ddeharness doctor

Use ddeharness doctor --probe to send a test message to your LLM, or ddeharness doctor --compute-only to check just the compute service. When reporting a problem, include ddeharness doctor --json output and your command or design request. See troubleshooting for common issues.

2. Start a design

Launch the terminal UI:

ddeharness

Then describe your task:

Design a VHH against human CRLF2. Verify the target and epitope, keep the framework fixed, and design CDRs. Show the plan and start only after I confirm.

See the terminal UI guide for the screen, commands and keys. CLI-based design workflows are also supported. See the CLI usage guide. For YAML-based runs, see the complete parameter reference and the CRLF2 staged example, which changes batch size, strategy weights, population capacity, and parent temperature by cycle interval. The parameter reference also explains stagnation-triggered redesign, defaults, and current limitations.

3. Inspect results

ddeharness tracing

Open the printed URL and select Protein design to inspect sequences, structures, metrics and agent activity.

Started design tasks run in background processes and continue after the TUI closes while the client host remains running. Task state and worker logs default to ~/.opendde_harness/protein_design/<task_id>/; set OPENDDE_HARNESS_PROTEIN_DESIGN_ROOT to change the task root. With remote compute, original structure files are stored on the compute host, and the dashboard uses structures captured in the client's tracing data. See the dashboard guide.

Development & License

See the repository rules and compute image build instructions. Ordinary users consume a prebuilt image; Dockerfiles remain available for publishers and customization. Licensed under Apache-2.0; see third-party notices. TUI and memory foundations are adapted from Raven, and long-term memory is served by EverOS. Models may have separate terms. Computational results require experimental validation. Model calls and compute may incur costs.

Citation and Acknowledgements

If you use OpenDDE Harness in your work, please cite this software and the technical report linked above. When using OpenDDE for structure prediction, also cite the OpenDDE technical report and follow its citation and acknowledgement guidance. Cite the original methods for other models and tools used in your experiments, including SolubleMPNN and ESM2 when applicable.

We acknowledge Raven, EverOS, and the upstream projects listed in the third-party notices. Their software and model licenses continue to apply.

Partnership and Collaboration