Agent integrations

Boltz agent integrations are CLI-backed. Claude Code, Codex, Cursor, and other coding agents can create payload files, estimate cost, submit jobs, and download results by calling boltz-api in the user’s environment.

Use the Boltz plugin or skill when your agent has one available. If it does not, give the agent the command pattern below.

Set up the host environment

Install the CLI where the agent can access it:

curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh
boltz-api --version

Authenticate with device-code login, which works well when an agent sandbox cannot open a browser directly:

boltz-api auth login --device-code
boltz-api auth status

You can also provide an API key through the environment:

export BOLTZ_COMPUTE_API_KEY="your-api-key"

Choose a stable output directory so long-running downloads can resume:

export BOLTZ_COMPUTE_OUTPUT_DIR="$HOME/boltz-experiments"
mkdir -p "$BOLTZ_COMPUTE_OUTPUT_DIR"

If your agent runs in a filesystem or network sandbox, install and authenticate boltz-api in the real host environment. The agent can still write payloads and run jobs once the CLI, credentials, and output directory are available.

Agent command pattern

Ask the agent to write an input file in the current working directory with API body field names, then pass it with @yaml://./prediction-input.yaml or @json://./prediction-input.json.

entities:
  - type: protein
    value: MKTIIALSYIFCLVFA
    chain_ids: ["A"]
  - type: ligand_smiles
    value: CC(=O)OC1=CC=CC=C1C(=O)O
    chain_ids: ["B"]
num_samples: 3
binding:
  type: ligand_protein_binding
  binder_chain_id: B

First estimate cost and ask for confirmation:

boltz-api predictions:structure-and-binding estimate-cost \
  --model boltz-2.1 \
  --input @yaml://./prediction-input.yaml

Then submit with a stable idempotency key. --raw-output --transform id prints only the job ID, which is easier for agents to copy into the download command.

boltz-api predictions:structure-and-binding start \
  --model boltz-2.1 \
  --idempotency-key "aspirin-check" \
  --input @yaml://./prediction-input.yaml \
  --raw-output --transform id

Finally, download with the same run name and output root:

boltz-api download-results \
  --id "<prediction-id-from-start>" \
  --name "aspirin-check" \
  --root-dir "./boltz-experiments" \
  --poll-interval-seconds 10

Prompt template

Use Boltz to predict structure and binding for this protein-ligand complex.
Create a YAML payload, estimate cost first, and ask before starting the job.
Use idempotency key "aspirin-check".
Download results into ./boltz-experiments/aspirin-check.
After submission, report the job ID, run name, and output directory.

Operational notes

• Keep each Boltz call as a top-level command that starts with boltz-api. This works better with agent permission prompts than shell-wrapped command strings.
• Use the same slug for --idempotency-key and download-results --name so retries resume instead of creating duplicate runs.
• Keep payload files and output directories in the working directory, for example prediction-input.yaml and ./boltz-experiments.
• Run download-results with the agent runtime’s managed long-running command mode when available. Avoid shell backgrounding with & or nohup.
• Check progress later with boltz-api --format json download-status --name "<run-name>" --root-dir "./boltz-experiments".

Next, see Predict structure and binding for the full structure prediction example.