boltz

Boltz

概述

所有 Boltz 工作流都直接使用官方 boltz-api CLI，并遵循以下三条护栏， 同时使用随附的持久化辅助脚本来保留结果。

模式 → CLI 资源：

模式	<resource>	额外标志
结构与结合（sab）	predictions:structure-and-binding	--model boltz-2.1
蛋白质设计	protein:design	—
蛋白质筛选	protein:library-screen	—
小分子设计	small-molecule:design	—
小分子筛选	small-molecule:library-screen	—
ADME	predictions:adme	--model adme-v1

身份验证

首选方式（Sandwalk Agent）： 通过 Sandwalk Integrations （Boltz / Fastfold Cloud 提供商配置）设置 BOLTZ_API_KEY。Sandwalk 会将已配置的提供商密钥同步到 供 shell.run 使用的聊天 Shell 环境中。不要要求用户在聊天中粘贴密钥。

替代方式： 本地 .env / export BOLTZ_API_KEY=...，或在 Boltz 控制台创建密钥：https://api.boltz.bio/console（Fastfold Cloud 提供商页面： https://cloud.fastfold.ai/integrations/providers?provider=boltz）。

如果缺少 BOLTZ_API_KEY： boltz-api / printenv BOLTZ_API_KEY 检查失败后立即停止；告知用户配置 Integrations（或使用 export / .env），然后重试。不要 在文件系统中搜寻密钥。

安装

• 如果缺少 boltz-api：curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh
• 它会安装到 PATH、~/.local/bin 或 ~/.boltz/bin。不要使用 pip install boltz-api。

基本规则

1. 先估算，再确认。 首先运行 estimate-cost，向用户展示费用，并且只有在用户明确批准后才运行计费的 start/run。估算不会产生费用。设计/筛选运行可以提前停止（stop）以限制支出；sab/adme 运行时间较短，且无法停止。计算任务无法暂停或恢复。
2. 将结果保存到持久位置——具体位置取决于运行环境（择一使用）。
   • 本地 Agent（sandwalk、Claude Code、Codex、Cursor 或任何本地机器）： 文件系统是普通的 POSIX 文件系统，并会在会话期间持续保留。直接下载到相对于项目的输出目录——使用 --root-dir "${OUTPUT_DIR:-./outputs}/boltz"（sandwalk 会设置 OUTPUT_DIR； 其他 Agent 默认使用 ./outputs/boltz）。无需复制；不要使用 persist.sh。
   • 使用 S3 后端 /workspace 的托管沙盒： CLI 无法直接下载到 /workspace （它不是完整的 POSIX 文件系统），而且 /tmp 是临时目录（驱逐时会清空）。下载到 /tmp/boltz-runs/<slug>，然后使用 scripts/persist.sh 复制到 /workspace。
   • 如果不确定：设置了 $OUTPUT_DIR 或存在可写的 ./outputs ⇒ 本地 Agent；挂载了 /workspace ⇒ 托管沙盒。
3. 从 API 恢复，绝不重新提交。 任务保存在服务端。如果本地运行目录丢失，通过 list 查找任务（匹配 idempotency_key），并按 ID 重新运行 download-results。绝不要仅为获取结果而再次提交计费任务。

CLI 速查表

从上表选择 <resource>；每个实验使用同一个 <slug>，同时作为 --idempotency-key 和 --name。负载通过文件传递，格式为 @yaml://payload.yaml。

根据规则 2 设置 <root>——本地 Agent："${OUTPUT_DIR:-./outputs}/boltz"；托管沙盒： /tmp/boltz-runs（之后使用 persist.sh）。

# Estimate (never bills)
boltz-api <resource> estimate-cost --input @yaml://payload.yaml        # + --model for sab/adme

# Submit + wait + download (after the user approves)
boltz-api <resource> run --input @yaml://payload.yaml \
  --idempotency-key <slug> --name <slug> --root-dir <root>
# hosted sandbox only: scripts/persist.sh /tmp/boltz-runs/<slug>       # copy to /workspace

# Or submit async, then poll + download later
boltz-api <resource> start --input @yaml://payload.yaml --idempotency-key <slug>   # prints job id
boltz-api <resource> retrieve --id <id> --format json                 # status / progress
boltz-api download-results --id <id> --name <slug> --root-dir <root>
# hosted sandbox only: scripts/persist.sh /tmp/boltz-runs/<slug>

# Inspect / enumerate
boltz-api <resource> list --limit 20 --format jsonl                    # find jobs by idempotency_key
boltz-api <resource> list-results --id <id> --format jsonl            # per-item results (design/screen)
                                                                       #   page with --after-id / --max-items -1

# Lifecycle
boltz-api <resource> stop --id <id>                                    # design/screen only, caps spend
boltz-api <resource> delete-data --id <id>                            # permanent + irreversible — confirm first

说明：

• run/download-results 会将完整结果集获取到 <root>/<slug>/results/<result_id>/。 如需返回前 N 个结果，请读取该目录（每个条目都包含 metadata.json），或使用 list-results。
• 丢失本地运行目录后恢复：运行 boltz-api <resource> list --limit 50 --format jsonl 查找 ID，然后运行 download-results --id <id> --name <slug> --root-dir <root>（仅在 托管沙盒中使用 persist.sh）。

载荷

各模式的载荷结构和便于复制粘贴的小示例见 references/examples.md。使用 @yaml://<file> 传入载荷。如果不确定某个模式的架构，请先查看示例——估算步骤也会在产生任何费用前，以较低成本检查载荷是否有误。

资源

• references/api.md — 模式与资源的映射以及原始 HTTP 端点。
• references/examples.md — 载荷和提示词示例。
• references/results.md — 运行目录结构以及持久化／恢复说明。