Fine-Tune Text and Image Models with Homebrew’s Guided AI Workflow

What Homebrew Does

Homebrew is a guided agent for fine-tuning language and image models. Instead of requiring you to assemble training scripts and configurations manually, it lets you chat with a brewmaster: an AI model that guides the project from the initial idea through data preparation, training, testing, export, and publication.

The brewmaster can be Claude, an OpenAI model, a model accessed through OpenRouter, a local Ollama or LM Studio model, or another OpenAI-compatible server. Guidance adapts to your selected experience level: Beginner, Hobbyist, Builder, or Expert.

Homebrew is designed to help with the complete workflow:

• Turn a broad model idea into a concrete training goal.
• Detect local hardware or prepare a remote GPU server over SSH.
• Select a compatible base model and training method.
• Find, import, clean, preview, or generate training data.
• Propose hyperparameters within model-specific guidelines.
• Run detached training jobs and report loss, progress, and ETA.
• Test the result against the original base model.
• Export an adapter or merged model.
• Generate a model card and upload the result to Hugging Face.

Homebrew asks for confirmation before spending money, installing software, sending data to an external provider, or publishing a model. Passwords, API keys, and tokens do not pass through the chat.

Supported Training Workflows

Text models

Homebrew supports listed model families including Qwen3, Qwen3.5 and compatible Qwen architectures, Qwen3.5 MoE, Llama 3.1 through 3.3, Gemma 3, and Gemma 4. Depending on the model and available hardware, training can use LoRA, QLoRA, or full fine-tuning.

Each text training job has one of three objectives:

• SFT: Supervised fine-tuning for teaching an instruct model a behavior, style, response format, or tool-use pattern.
• CPT: Continued pretraining on raw text, often used to teach a base model a domain or language.
• DPO: Preference tuning using chosen and rejected responses.

These objectives can be chained. Common regimes include plain SFT, CPT followed by SFT, and SFT followed by DPO. When LoRA stages are chained, Homebrew merges each stage into its starting weights before beginning the next stage.

Image models

For image training, Homebrew supports LoRA adapters for Qwen-Image 2.1. These adapters can target styles, characters, or objects. During training, Homebrew can render preview images at step zero and at later checkpoints using fixed seeds, making visual comparison easier.

Install Homebrew

Control-plane installation

If training will run on a rented or remote GPU server, your local computer only needs the lightweight Homebrew installation:

pip install "homebrew-ai @ git+https://github.com/empero-org/homebrew-ai"

Start the guided interface with:

homebrew

Local GPU installation

If the computer has an NVIDIA GPU and will perform the training locally, install the training extras:

pip install "homebrew-ai[train] @ git+https://github.com/empero-org/homebrew-ai"

You can verify the installation, provider configuration, Hugging Face login, and hardware with:

homebrew doctor
homebrew hardware

To inspect a remote training server instead, pass its SSH command:

homebrew hardware --ssh "ssh user@example-server"

Configure the Guiding AI

On its first run, Homebrew asks which AI should act as the brewmaster. It then requests the necessary API key, stores it locally with restricted permissions, asks for your experience level, and creates a project.

The available guide types are:

• Claude: The README recommends this option for the strongest guidance.
• OpenAI: Uses a chat model with tool calling.
• OpenRouter: Provides access to multiple models through one API key.
• Ollama or LM Studio: Runs locally; the project recommends a model with at least 14B parameters and tool calling for good results.
• Custom: Connects to an OpenAI-compatible endpoint such as vLLM or llama.cpp.

Change the guiding model later by running:

homebrew setup

Homebrew adjusts its behavior to the guide. Strong models receive the full toolset, while smaller local models receive phase-specific tools and more structured guidance. Models without native tool calling can use Homebrew’s text protocol automatically.

Create Your First Fine-Tuning Project

You can start in the current directory with homebrew, or create a named project directly:

homebrew new my-pirate-chemist
cd my-pirate-chemist
homebrew

Describe the desired result in ordinary language. For example:

a chatbot that explains chemistry like a friendly pirate

The brewmaster will ask questions until the goal is concrete. It then evaluates hardware, recommends a base model, discusses licensing needs, and determines whether local or rented compute is appropriate.

Follow the Brewing Workflow

1. Define the goal

Explain the model’s intended behavior, audience, subject area, output style, or image concept. Specific goals help the brewmaster choose suitable data and an appropriate training objective.

2. Choose compute

Homebrew detects local hardware. If no suitable NVIDIA GPU is available, it can recommend a compatible GPU and provide approximate Runpod and Vast.ai prices. It does not create an account or spend money on your behalf.

After you rent a machine, paste the provider’s SSH command into the guided session. Homebrew can then check the hardware, prepare the environment, upload the data, start training, and retrieve the results.

Stopped cloud instances may continue billing for storage. Destroy rented resources when the project is complete.

3. Select a base model

The brewmaster recommends a model based on the goal, available memory, intended training method, and licensing requirements. It also checks whether access to a gated model is available.

To inspect supported models yourself, use:

homebrew models
homebrew models --modality text --all
homebrew models --modality image --all

4. Prepare the data

Training data can come from Hugging Face, local files, examples written with the brewmaster, or optional synthetic generation. Homebrew can search and preview Hugging Face datasets without downloading them first.

Synthetic data generation is opt-in. It can create conversations from a brief, rewrite an existing dataset into a requested style, or produce preference pairs for DPO. Work is saved as batches finish, so canceling a generation run does not discard completed batches.

The clean_dataset operation removes empty, duplicate, or broken records and creates a backup. Preview the processed records carefully to confirm that they teach the intended behavior.

5. Build the training recipe

Homebrew’s propose_training_config operation selects hyperparameters from the supported model’s guidelines and sizes the job for the available GPU. Before training begins, Homebrew estimates memory use, duration, and cost.

6. Run and monitor training

Training runs as a detached process on the machine containing the GPU. Closing the local terminal does not stop the job. Return to the project folder and run homebrew to resume the conversation.

Useful monitoring commands include:

homebrew status
homebrew status JOB_ID

Inside an interactive session, use:

/status
/jobs
/watch

Homebrew follows progress, reports the loss curve and ETA, and provides a plain-language explanation when a failure occurs.

7. Taste-test the model

After training, test prompts against the fine-tuned model and compare its answers with those from the base model. This can reveal whether the new model learned the requested style or behavior without damaging general response quality.

8. Export and share

Homebrew can package the result as an adapter or merged model. It also generates a model card covering the training regime, data, licenses, credits, and relevant examples. Uploads to Hugging Face are private by default.

Licensing checks include considerations such as Llama naming requirements, Gemma terms, and non-commercial dataset or model notices.

Advanced Text Training: CPT, SFT, and DPO

Use CPT followed by SFT

Choose CPT when the model first needs exposure to raw domain or language data. Follow it with SFT to teach conversational behavior. Each later job references the previous stage through init_from.

Base model -> CPT on raw text -> SFT on conversations

Refine preferences with DPO

After SFT, DPO can sharpen preferences for qualities such as tone, structure, or answer style. Preference pairs may come from Hugging Face, synthetic generation, or the newly trained model itself.

Homebrew can generate two candidate responses for each prompt with generate_candidates. You can select the better response in the terminal with review_candidates, or ask the guiding AI to judge candidates against a rubric and then spot-check its decisions.

Base model -> SFT -> generate candidate pairs -> review preferences -> DPO

DPO reference log-probabilities are calculated once from the stage’s starting model, so a second model does not need to remain in GPU memory. This applies to both LoRA and full fine-tuning.

Monitor an Image LoRA Visually

Qwen-Image 2.1 LoRA jobs can generate a base-model preview at step zero and a new preview set at every configured checkpoint. The prompts and random seeds remain fixed, allowing meaningful checkpoint comparisons.

Downloaded previews are stored under:

runs/<job>/samples/step_NNNNNN/

Include the adapter’s trigger word in preview prompts. If an earlier checkpoint looks better than the final one, ask the brewmaster to package that checkpoint.

For a side-by-side browser interface, enter:

/gallery

The gallery is served locally at a tokenized 127.0.0.1 address and is not reachable from outside the computer. Rows represent checkpoints and columns represent preview prompts. The gallery refreshes during training, supports enlarged images, lets you move through checkpoints with the arrow keys, and uses C to compare a result with the base model.

Understand ETF Data

Homebrew uses Empero Trace Format, or ETF, as a unified JSON Lines format. ETF can represent chats, system prompts, tool schemas and calls, reasoning, retrieval documents, preference pairs, raw text, completions, and images.

Use the ETF command group to inspect and manage files:

homebrew etf validate dataset.jsonl
homebrew etf stats dataset.jsonl
homebrew etf convert
homebrew etf schema

See the project’s ETF documentation for its complete structure.

Useful Commands and Session Controls

• homebrew: Start or resume the current project.
• homebrew new NAME: Create a project.
• homebrew setup: Select or change the guiding AI.
• homebrew doctor: Check the installation, AI provider, Hugging Face login, and hardware.
• homebrew hardware: Display a local or remote hardware report.
• homebrew models: List supported base models.
• homebrew status JOB: Inspect training jobs.

Inside a session, /level changes the explanation level, /usage displays usage information, /thinking full expands the brewmaster’s visible reasoning display, /thinking off hides it, and /quit exits the session.

Advanced Setup Tips

Adapt Homebrew to limited terminals

Homebrew provides environment variables for simplified terminal interfaces:

HOMEBREW_AI_PLAIN_INPUT=1 homebrew
HOMEBREW_AI_SIMPLE_PROMPTS=1 homebrew
HOMEBREW_AI_THINKING=off homebrew

HOMEBREW_AI_PLAIN_INPUT replaces the framed input bar with a plain prompt. HOMEBREW_AI_SIMPLE_PROMPTS uses numbered choices instead of arrow-key menus. HOMEBREW_AI_THINKING accepts on, full, or off.

Control synthetic-data concurrency

Synthetic generation supports between one and sixteen parallel workers. For example:

HOMEBREW_AI_SYNTH_WORKERS=4 homebrew

Choose a value that respects your provider’s rate limits and account constraints.

Inspect the project files

A typical project contains:

my-project/
  homebrew.yaml
  data/
  data/_sets/<name>/
  runs/<job_id>/
  .homebrew/

• homebrew.yaml stores decisions and state, including the goal, model, compute, datasets, jobs, and exports.
• data/ contains ETF datasets and manifests describing sources, licenses, and mappings.
• data/_sets/<name>/ contains constructed training and evaluation sets.
• runs/<job_id>/ stores the job configuration, copied data, status, metrics, logs, and final artifacts.
• .homebrew/ contains conversation history used to resume the session.

User settings are stored under ~/.config/homebrew-ai/. Credentials are kept in credentials.yaml with mode 600. Additional model profiles can be placed in ~/.config/homebrew-ai/profiles/ using the same schema as the included profiles.

Practical Recommendations

1. Begin with a narrow goal. A precise behavior or visual concept is easier to evaluate than a general-purpose objective.
2. Preview the final training records. Cleaning and stylistic rewriting can change what the model sees, so inspect representative examples before training.
3. Start with SFT for behavioral changes. Use more complex chains only when the project genuinely needs domain pretraining or preference optimization.
4. Compare with the base model. Side-by-side tests make it easier to determine whether training created a useful improvement.
5. Review licenses before publishing. Your output belongs to you, subject to the licenses of the base models and datasets used.
6. Keep useful checkpoints. For image LoRA training in particular, the visually strongest checkpoint may not be the final one.
7. Terminate rented infrastructure. Stop and destroy cloud resources after downloading and verifying the results.

Conclusion

Homebrew turns model fine-tuning into a guided, conversational workflow while preserving control over data, costs, installation, and publication. It supports straightforward SFT projects as well as chained CPT, SFT, and DPO regimes, plus checkpoint-based Qwen-Image LoRA training. Start by installing the command-line tool, choose a capable guide, describe a focused goal, and let the brewmaster walk through each confirmed step.

For source code and current documentation, visit the Homebrew GitHub repository. Homebrew uses its own license: MIT-style terms apply to individuals and organizations up to the revenue threshold stated in the repository, while larger organizations require a commercial license.