boltz

Boltz

概要

以下の3つのガードレールに従い、バンドルされた永続化ヘルパーを使用して結果を保存しながら、すべての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 エージェント）： Sandwalk のインテグレーション （Boltz／Fastfold Cloud プロバイダーの設定）でBOLTZ_API_KEYを設定します。Sandwalk は設定済みのプロバイダーキーを shell.run用のチャットシェル環境変数に反映します。チャットでユーザーにシークレットを貼り付けるよう求めてはいけません。

代替手段： ローカルの.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の確認が失敗した時点で停止し、インテグレーション（または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. 永続的な場所に結果を保存します。保存先は実行環境によって異なるため、いずれかを選びます。
   • ローカルエージェント（sandwalk、Claude Code、Codex、Cursor、または任意のローカルマシン）： ファイルシステムは通常のPOSIX形式で、セッションをまたいで保持されます。プロジェクト相対の出力ディレクトリに直接ダウンロードします。--root-dir "${OUTPUT_DIR:-./outputs}/boltz"を使用してください（sandwalk はOUTPUT_DIRを設定し、その他のエージェントでは./outputs/boltzにフォールバックします）。コピー手順は不要です。persist.shは使用しないでください。
   • S3バックエンドの/workspaceを備えたホスト型サンドボックス： CLIは/workspaceに直接ダウンロードできません（完全なPOSIXファイルシステムではありません）。また、/tmpは一時的であり（退去時に消去されます）。/tmp/boltz-runs/<slug>にダウンロードしてから、scripts/persist.shで/workspaceにコピーします。
   • 判断に迷う場合：$OUTPUT_DIRが設定されているか、書き込み可能な./outputsがある場合はローカルエージェントです。/workspaceがマウントされている場合はホスト型サンドボックスです。
3. 再送信せず、APIから復旧します。 ジョブはサーバー側にあります。ローカルの実行ディレクトリが失われた場合は、listでジョブを検索し（idempotency_keyを照合）、IDを使って再度download-resultsを実行します。結果を取得するためだけに課金対象の送信を再実行してはいけません。

CLI早見表

上の表から<resource>を選び、実験ごとに1つの<slug>を使って、--idempotency-keyと--nameの両方に指定します。ペイロードは@yaml://payload.yamlを使い、ファイルとして渡します。

ルール2に従って<root>を設定します。ローカルエージェントの場合は"${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 — 実行ディレクトリの構成、および永続化と復旧に関する注意事項。