overbrainer

Distill a large "parent" LLM into a smaller open-weights "child" model, from the command line.

overbrainer asks an LLM for questions on your topics, collects answers and their reasoning from a parent model, then fine-tunes a child model with Axolotl on this machine, over SSH or on Runpod. A terminal UI shows the dataset and the training runs as they progress.

Status: early development. Expect breaking changes between minor versions until 1.0.

How it works

flowchart LR
    T[Topics in overbrainer.toml] --> S[Subtopics]
    S --> Q[Questions]
    Q --> A[Parent answers with reasoning]
    A --> SP[Train and eval split]
    SP --> F{Axolotl fine-tune}
    F -->|Local| L[LoRA adapter]
    F -->|SSH| L
    F -->|Runpod| L

A generator model writes the subtopics and questions, and drops near-duplicates. The parent model answers each question; answers that were truncated, refused or empty, or that lack the raw reasoning asked for, are kept for inspection and left out of training. split writes data/train.jsonl and data/eval.jsonl in Axolotl's chat format, and train fine-tunes the base model on them.

Install

Download a binary

Each GitHub release has a binary for three targets:

• x86_64-unknown-linux-musl: Linux on x86-64, statically linked
• aarch64-unknown-linux-musl: Linux on ARM64, statically linked
• aarch64-apple-darwin: macOS on Apple silicon

Each archive holds overbrainer, the README and the licenses, next to a .sha256 file. On Linux:

version=v0.3.1
target=x86_64-unknown-linux-musl   # or aarch64-unknown-linux-musl
file="overbrainer-$version-$target.tar.gz"
curl -LO "https://github.com/nayrosk/overbrainer/releases/download/$version/$file"
curl -LO "https://github.com/nayrosk/overbrainer/releases/download/$version/$file.sha256"
sha256sum -c "$file.sha256"
tar xzf "$file" overbrainer
sudo install overbrainer /usr/local/bin/

On macOS, set target=aarch64-apple-darwin and check the archive with shasum -a 256 -c "$file.sha256".

Build with cargo

cargo install --locked overbrainer

The latest code from main installs with cargo install --locked --git https://github.com/nayrosk/overbrainer.

Requirements

• Rust 1.89 or newer to build it. CI builds and tests on Linux, and checks that it builds on macOS.
• ssh for SSH targets, and ssh with ssh-keygen for Runpod targets.
• For training on this machine: Axolotl 0.19 in a virtual environment or on PATH, or Docker or Podman with NVIDIA GPU access to run the Axolotl image.

Shell completions

overbrainer completes its commands and flags in bash, zsh and fish. It also completes run IDs (with their state and target), topic names and target names, read from the project in the current directory or the one given with -C. Add the line for your shell to its startup file:

source <(COMPLETE=bash overbrainer)          # ~/.bashrc
source <(COMPLETE=zsh overbrainer)           # ~/.zshrc
COMPLETE=fish overbrainer | source           # ~/.config/fish/completions/overbrainer.fish

The script must match the installed version, so generate it when the shell starts, as above, rather than saving it to a file.

Quickstart

overbrainer init my-project && cd my-project
cp .env.example .env        # fill in the provider URL and key
overbrainer config check    # prints the resolved configuration, secrets masked
overbrainer run             # subtopics, questions, answers, split, then train
overbrainer tui             # browse the dataset and follow the runs

init writes overbrainer.toml, .env.example, the prompt templates in prompts/ and a .gitignore. Edit the topics in overbrainer.toml before run. run trains only when overbrainer.toml has a [training] section; otherwise it stops after split. Each stage also runs on its own (subtopics, questions, answers, split, train) and resumes where it stopped: see the dataset pipeline.

Providers

A provider is any API that speaks the OpenAI chat completions protocol or the Anthropic Messages API. overbrainer.toml names it and its protocol; the URL and the key come from the environment. OpenRouter and NanoGPT both work, and both publish prices, so every stage prints what it cost.

[providers.openrouter]
protocol = "openai"

[providers.nanogpt]
protocol = "openai"

[roles]
generator = { provider = "nanogpt", model = "qwen/qwen3-235b-a22b-instruct-2507" }
parent = { provider = "openrouter", model = "deepseek/deepseek-r1", reasoning = true }

OVERBRAINER_PROVIDERS__OPENROUTER__BASE_URL=https://openrouter.ai/api/v1
OVERBRAINER_PROVIDERS__OPENROUTER__API_KEY=sk-or-...
OVERBRAINER_PROVIDERS__NANOGPT__BASE_URL=https://nano-gpt.com/api/v1
OVERBRAINER_PROVIDERS__NANOGPT__API_KEY=...

NanoGPT: nano-gpt.com (referral link). Any key can also be a vault: reference to a Vault or OpenBao secret. Configuration covers roles, pipeline settings, secrets and logs.

Training targets

Runpod: runpod.io (referral link). A run's LoRA adapter (or full model) lands in runs/<run-id>/output/. train attach follows a run again after Ctrl-C, and train cancel stops it. Training covers targets, settings and the Hugging Face token; Runpod covers pods, the watchdog and costs.

Terminal UI

overbrainer tui has four views:

• Dataset (1): the topics, subtopics, questions and answers as a tree, with each answer's reasoning, stats and a filter. Edit or delete items in place.
• Pipeline (2): run a stage and watch its progress, tokens and cost.
• Training (3): the runs, with progress, pod, spend, a loss chart and learning rate and gradient norm sparklines. Start, follow or cancel a run.
• Logs (4): the captured log lines, filtered by level.

The TUI draws its own crimson theme in 24-bit or 256 colors, and falls back to the terminal's 16 colors. OVERBRAINER_TUI_COLOR (truecolor, 256 or 16) and OVERBRAINER_TUI_MOTION (on, reduced or off) override the detection, and NO_COLOR turns it monochrome. The TUI page has every key and behavior.

AI agents

overbrainer ships an agent skill that teaches AI coding agents to drive it: set up a project, run the stages and training, read the results, and keep to a few rules (never read .env, ask before spending money, clean up Runpod pods). It matches the installed version of overbrainer.

overbrainer skill install            # this project: .claude/skills/overbrainer/SKILL.md
overbrainer skill install --global   # every project: ~/.claude/skills/overbrainer/SKILL.md
overbrainer skill install --dir DIR  # another agent's skills directory: DIR/overbrainer/SKILL.md

An installed skill that was edited is only replaced with --force. In Claude Code, the skill is also a plugin:

/plugin marketplace add nayrosk/overbrainer
/plugin install overbrainer@overbrainer

Documentation

• The dataset pipeline: stages, resuming, deduplication, the split, the answer format, reasoning and prompt templates.
• Configuration: overbrainer.toml, environment variables, providers, roles, pipeline settings, Vault and logs.
• Training: runs, local and SSH targets, the Hugging Face token, chat templates and training settings.
• Runpod: pods, the watchdog, --keep-pod, stray pods and custom images.
• Terminal UI: views, keys, editing, quitting, color and motion.

Releasing

Releases are cut by hand from main:

1. Open a release pull request from a chore/release-vX.Y.Z branch with the release label, which makes CodeRabbit skip it. It needs no issue. It bumps the version in Cargo.toml (cargo updates Cargo.lock on the next build) and in .claude-plugin/plugin.json, points the docs links of skills/overbrainer/SKILL.md and the binary install example above at vX.Y.Z, and regenerates the changelog with git-cliff: git cliff --tag vX.Y.Z -o CHANGELOG.md. cliff.toml holds the changelog format. Tests fail until the versions and links agree.
2. Review and merge that pull request.
3. Tag the merge commit with a signed tag and push it: git tag -s vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z.
4. The tag runs .github/workflows/release.yml. It checks that the tag matches Cargo.toml, runs the checks and cargo semver-checks, builds the binaries without any cache, publishes the crate to crates.io through trusted publishing (no token is stored; the crate trusts release.yml in the production environment, which only v* tags can deploy to) and creates the GitHub release from the changelog entry with the binaries attached.

To test the release build from a branch without publishing, run the release workflow by hand: a manual run verifies and builds, and never publishes.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md for the workflow and the code of conduct. Report vulnerabilities privately as described in SECURITY.md.

Terms of service

Several model providers forbid using their outputs to train models that compete with them. This includes OpenAI and Anthropic, and the restriction still applies when their models are reached through a gateway such as OpenRouter or NanoGPT. Check the terms of the models you configure as parent before training on their outputs.

License

Licensed under either of MIT or Apache-2.0 at your option.