Getting Started

settl is a terminal hex settlement game where AI players compete using tool-calling LLMs. You can play against them, spectate, or run headless simulations.

Installation

Homebrew (macOS / Linux)

brew install --cask mozilla-ai/tap/settl

From source

git clone https://github.com/mozilla-ai/settl.git
cd settl
cargo build --release

The binary is at target/release/settl.

Your First Game

Launch the TUI:

settl              # if installed via brew
cargo run          # if built from source

This opens the title screen. Select New Game to configure players and start.

Player 1 is always human. You choose how many AI opponents (up to 3) and their personalities. The default AI backend is llamafile, which runs a local LLM with no API keys needed.

Headless Mode

Run games without the TUI for scripting and CI:

# Random AI players, no API keys needed
cargo run -- --demo

# LLM players via API
ANTHROPIC_API_KEY=sk-... cargo run -- --headless --model claude-sonnet-4-6

# Per-player model assignment
cargo run -- --models "claude-sonnet-4-6,gpt-4o-mini,claude-haiku-4-5-20251001"

# Reproducible board
cargo run -- --demo --seed 42

CLI Options

Flag	Description	Default
`--headless`	Run in text mode (no TUI)	off
`--demo`	Random AI players, no API keys	off
`-p, --players N`	Number of players (2-4)	4
`-m, --model MODEL`	Default LLM model	claude-sonnet-4-6
`--models M1,M2,...`	Per-player model assignment	—
`--personality FILE`	TOML personality file	built-in
`--seed N`	RNG seed for reproducible boards	random

API Keys

Set environment variables for cloud LLM providers:

export ANTHROPIC_API_KEY=sk-ant-...   # Claude
export OPENAI_API_KEY=sk-...          # GPT
export GOOGLE_API_KEY=...             # Gemini

No API keys are needed when using llamafile (the default) or --demo mode.