--- title: Agent integrations | Boltz API Docs description: Use Boltz API from Claude Code, Codex, and other coding agents. --- 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](#agent-command-pattern). ## Set up the host environment Install the `boltz-api` CLI where the agent can access it: Terminal window ``` export BOLTZ_BASE_URL="https://api.boltz.bio" 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: Terminal window ``` export BOLTZ_BASE_URL="https://api.boltz.bio" boltz-api --auth-issuer-url "https://lab.boltz.bio" auth login --device-code boltz-api auth status ``` For a first-time user, the browser opened by either login command supports **Create account**. Finish signup and email verification, then return to the device authorization page and choose **Allow access**. If the user enters Lab directly, open `/setup` and either accept a pending organization invitation or create an organization before retrying the agent login. Ordinary authentication no longer creates a personal organization; an SSO deployment may retain that behavior when its personal-organization setting is enabled. Alternatively, provide an API key through the environment: Terminal window ``` export BOLTZ_API_KEY="your-api-key" ``` Choose a stable output directory so long-running downloads can resume: Terminal window ``` 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: Terminal window ``` 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](https://code.claude.com/docs/en/installation) and [installing plugins from marketplaces](https://code.claude.com/docs/en/discover-plugins). ### Codex Install Codex CLI 0.131.0 or newer. First verify your version: Terminal window ``` 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: Terminal window ``` 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](https://developers.openai.com/codex/cli) and [using plugins](https://developers.openai.com/codex/plugins). ### Gemini CLI / Antigravity CLI Note: [Gemini CLI](http://geminicli.com/) will be replaced by [Antigravity CLI](https://antigravity.google/product/antigravity-cli) on June 18, 2026. The [Boltz extension](https://geminicli.com/extensions/?name=boltz-bioboltz-gemini-cli) is compatible with both `gemini` and `agy`. Install from the extension repo: Terminal window ``` # 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: Terminal window ``` # Gemini CLI /skills list /extensions list # Antigravity CLI /skills ``` See the official [Gemini CLI extension docs](https://geminicli.com/docs/extensions/reference/) and [Antigravity CLI plugin docs](https://antigravity.google/docs/plugins) 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: Terminal window ``` export BOLTZ_BASE_URL="https://api.boltz.bio" 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 ``` export BOLTZ_BASE_URL="https://api.boltz.bio" 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 ``` export BOLTZ_BASE_URL="https://api.boltz.bio" boltz-api download-results \ --id "" \ --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 "" --root-dir "./boltz-experiments"` - For more detail see the [CLI reference](/docs/api/api/cli/index.md) and the [REST reference](/docs/api/api/index.md) Next, see [Predict structure and binding](/docs/api/guides/predictions/index.md) for the full structure prediction example.