Skip to content

Setup

This guide will help you install and configure BalatroLLM.

Prerequisites

  • uv: for managing Python environment and dependencies
  • Balatro Game: You need a copy of Balatro installed
  • BalatroBot: The underlying framework for Balatro automation
  • Access to LLM model: exposing an OpenAI-compatible chat/completion API

BalatroBot Setup

Setting up Balatro with the BalatroBot mod requires careful configuration. Please refer to the BalatroBot documentation and follow the instructions step by step. Ensure that BalatroBot is installed and running before proceeding with the BalatroLLM installation.

Installation

  1. Clone the repository
git clone --depth 1 https://github.com/coder/balatrollm.git
cd balatrollm
  1. 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.

  1. Activate environment
source .venv/bin/activate
  1. Test that the new commands are available
balatrollm --help
balatrobench --help

Auto venv activation & Environment Variables

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

Provider Configuration

You need to configure your chosen provider. We recommend configuring the provider through environment variables using .envrc (see .envrc.example)

  • BALATROLLM_BASE_URL: API base URL
  • BALATROLLM_API_KEY: API key for LLM provider

Now you should be able to run

balatrollm --list-models

to see the available models. You can now set the model environment variable:

  • BALATROLLM_MODEL: Model to use

CLI precedence

All BALATROLLM_* environment variables have a corresponding CLI argument. The environment variables are used as defaults when running balatrollm. CLI arguments take precedence over the corresponding environment variable. For example, you can set a default model with BALATROLLM_MODEL but use another one: balatrollm --model "...".