Skip to main content

Running AutoResearch by Andrej Karpathy Locally on Mac Mini M4 with Ollama

· 5 min read
Ahmed BARGADY
Ahmed BARGADY
PhD Student

AutoResearch on Mac Mini M4

Andrej Karpathy recently released AutoResearch, an open-source tool that fundamentally changes how we approach machine learning experiments. Instead of manually tweaking code and hyperparameters, AutoResearch shifts the researcher's role to orchestrating high-level goals while an AI agent handles the repetitive loop of proposing, implementing, and evaluating ML experiments.

In this post, I'll walk you through how to set up and run AutoResearch locally on your Mac Mini M4 using Ollama and local LLMs.

What is AutoResearch?​

AutoResearch is an autonomous agent framework. You define a research direction in a program.md file, and the agent takes over:

  1. It reads the goal and modifies your training script (e.g., train.py).
  2. It runs a fixed-time training loop (usually around 5 minutes).
  3. It evaluates the validation metrics.
  4. If the new code improves performance, it commits the changes via Git. If not, it reverts them.

Originally designed for powerful cloud GPUs and premium APIs like Claude or GPT-4, the community has quickly adapted it to run on local hardware.

Why Mac Mini M4 and Ollama?​

The Mac Mini M4, especially with 16GB or 32GB of Unified Memory, is an excellent machine for running local, quantized LLMs. By combining it with Ollama, you get:

  • Zero API Costs: Run your experiments 24/7 without worrying about skyrocketing API bills.
  • Data Privacy: Your proprietary code and datasets never leave your machine.
  • "Agentic Engineering": You get hands-on experience with managing an AI researcher on your own hardware.

Prerequisites​

Before we start, make sure you have the following installed on your Mac:

  • Git: Pre-installed on macOS or available via brew install git.
  • Homebrew: The standard macOS package manager.
  • Ollama: For running local LLMs.

1. Install Ollama​

If you don't have Ollama installed, you can easily get it via Homebrew:

brew install ollama

Once installed, start the Ollama service:

brew services start ollama

2. Pull a Capable Model​

For an agentic coding task, you need a model that excels at reasoning and generating Python code. Models like qwen2.5-coder or llama3 are great starting points.

ollama pull qwen2.5-coder

uv is a blazingly fast Python package manager written in Rust. It makes setting up the environment much smoother.

curl -LsSf https://astral.sh/uv/install.sh | sh

Step-by-Step Setup​

Step 1: Clone the Repository​

You can clone the original repository or look for a community fork optimized for local macOS execution.

git clone https://github.com/karpathy/autoresearch.git
cd autoresearch

Step 2: Initialize the Environment​

Set up your Python virtual environment and install the required dependencies. Using uv, this is incredibly fast:

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

(Note: Depending on the specific fork or updates, you might need to install additional packages like litellm to route requests to Ollama.)

Step 3: Configure the Local Agent​

The original code might default to OpenAI or Anthropic. You'll need to point the agent to your local Ollama instance. If the codebase uses LiteLLM or a similar router, set your environment variables to route traffic to localhost:

export OPENAI_API_BASE="http://localhost:11434/v1"
export OPENAI_API_KEY="ollama" # Dummy key
export MODEL="qwen2.5-coder" # Or whatever model you pulled

Step 4: Define Your Research Goal​

Open program.md in your favorite editor. This is where you tell the agent what to do. Keep it focused and provide clear, measurable constraints.

Example program.md:

# Goal
Improve the validation loss of the simple CNN in `train.py` on the MNIST dataset.

# Constraints
- Do not increase the training time beyond 5 minutes per run.
- You may modify the architecture, learning rate, or optimizer.
- Log the validation loss at the end of the script for evaluation.

Step 5: Start the Loop!​

Run the orchestrator script. The exact command depends on the repository structure, but it usually looks like this:

python main.py

Now, sit back and watch. Your Mac Mini M4 will use the local LLM to generate code changes, execute the training script, and commit improvements.

Important Considerations for M4 Users​

  1. Memory Management: Running an LLM (the researcher) and training a model simultaneously consumes a lot of Unified Memory. If you only have 16GB, stick to smaller models (e.g., 7B or 8B parameters) and lightweight training tasks.
  2. Throughput: Your Mac won't match an H100 GPU cluster. The agent's iteration loop will be slower, but it's perfect for overnight runs.
  3. The Evaluation Metric: The agent relies entirely on the metric you define. Ensure your train.py outputs a clean, parseable score (like a final validation loss) for the agent to read.

Conclusion​

Running AutoResearch locally on a Mac Mini M4 with Ollama is a fantastic way to explore the future of AI-driven ML development without incurring cloud costs. By delegating the repetitive code-test-evaluate loop to an agent, you can focus on the bigger picture: asking the right questions and defining better research constraints.

Happy (automated) researching!