Agent integrations

Claude Code, Codex, Cursor, and other coding agents can create API inputs, estimate cost, submit jobs, and download results by using the boltz-api CLI in the user's environment.

Use an official Boltz plugin or skill when available. If there's no official plugin for the harness you are using show the agent the command pattern below.

Set up the host environment

Install the boltz-api CLI where the agent can access it:

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

Agents can 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

Alternatively, provide an API key through the environment:

export BOLTZ_API_KEY="your-api-key"

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

export BOLTZ_API_OUTPUT_DIR="$HOME/boltz-experiments"
mkdir -p "$BOLTZ_API_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.

Install an agent integration

Claude Code

Install the Boltz Claude Code plugin from the default Boltz marketplace source:

claude plugin marketplace add boltz-bio/boltz-api-skills
claude plugin install boltz@boltz-marketplace --scope user

Restart Claude Code after installing.

See the official Claude Code docs for installing Claude Code and installing plugins from marketplaces.

Codex

Install Codex CLI 0.131.0 or newer. First verify your version:

codex --version

Codex CLI versions before 0.131.0 do not include codex plugin add, so upgrade Codex if you see unrecognized subcommand 'add'. Then add the Boltz marketplace and plugin:

codex plugin marketplace add boltz-bio/boltz-api-skills
codex plugin add boltz@boltz-marketplace

Restart Codex after installing, then complete the shared host setup above so the plugin can call boltz-api from the project environment.

See the official OpenAI Codex docs for installing Codex CLI and using plugins.

Gemini CLI / Antigravity CLI

Note: Gemini CLI will be replaced by Antigravity CLI on June 18, 2026. The Boltz extension is compatible with both gemini and agy. Install from the extension repo:

# Gemini CLI
gemini extensions install https://github.com/boltz-bio/boltz-gemini-cli
# Antigravity CLI
agy plugin install https://github.com/boltz-bio/boltz-gemini-cli

Restart the CLI after installing, then verify the Boltz plugin is visible:

# Gemini CLI
/skills list
/extensions list
# Antigravity CLI
/skills

See the official Gemini CLI extension docs and Antigravity CLI plugin docs for more detail.

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 API 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. The API will reject payloads which pass the same idempotency key with different inputs
• 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 after job submission with boltz-api --format json download-status --name "<run-name>" --root-dir "./boltz-experiments"
• For more detail see the CLI reference and the REST reference

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