Skip to content

Installation

This guide will help you install and configure BalatroLLM.

Prerequisites

Tool Use (Function Calling) Required

The LLM model you choose must support tool use (also known as function calling). BalatroLLM relies on tool calls to execute game actions — models without this capability will not work.

Most frontier models (e.g., GPT-4o, Claude, Gemini) support tool use, but smaller or older models may not. Check your provider's documentation to confirm support.

BalatroBot Setup Required

Setting up Balatro with the BalatroBot mod requires careful configuration. Please follow the BalatroBot Installation Guide step by step.

Ensure BalatroBot is installed and working before proceeding with BalatroLLM installation.

Installation

1. Clone the Repository

git clone --depth 1 https://github.com/coder/balatrollm.git
cd balatrollm

2. Create Environment and Install Dependencies

uv sync --no-dev

When running uv sync, uv automatically downloads the required Python version, creates a new environment at .venv, and installs the project dependencies.

3. Activate Environment

source .venv/bin/activate

4. Verify Installation

balatrollm --help

Auto venv activation

You can use direnv to automatically activate the environment when you enter the project directory. See the .envrc.example file for an example configuration.

Provider Configuration

Configure your LLM provider through environment variables. We recommend using .envrc (see .envrc.example):

export BALATROLLM_BASE_URL="https://openrouter.ai/api/v1"
export BALATROLLM_API_KEY="sk-..."
Variable Description
BALATROLLM_BASE_URL API base URL (e.g., OpenRouter, OpenAI)
BALATROLLM_API_KEY API key for your LLM provider

For full CLI reference, see CLI Reference.