---
title: Agent integrations | Boltz API Docs
description: Use Boltz from Claude Code, Codex, Cursor, and other coding agents.
---

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:

Terminal window

```
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:

Terminal window

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

You can also provide an API key through the environment:

Terminal window

```
export BOLTZ_COMPUTE_API_KEY="your-api-key"
```

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

Terminal window

```
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:

Terminal window

```
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.

Terminal window

```
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:

Terminal window

```
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](/docs/guides/predictions/index.md) for the full structure prediction example.