Deploy mini-SWE-agent v2.4.2: Setup Guide

Here’s a fact that catches most people off guard: the original SWE-agent – the tool that put agentic coding on the map at NeurIPS 2024 – has been officially superseded by its own maintainers. The official install page now literally recommends you install a different project instead: mini-swe-agent. Same team, ~100 lines of Python, and – as of the current README – north of 74% on SWE-bench verified.

If you’re deploying an SWE-bench agent today, this is the one to reach for. Below is the current install path for mini-swe-agent v2.4.2 (the latest wheel on PyPI), plus the classic SWE-agent 1.1.0 route for people who need EnIGMA or existing batch evaluation pipelines.

System requirements

The minimums are almost embarrassingly small. That’s the whole point – mini can run anywhere bash runs, no container runtime required.

Classic SWE-agent 1.1.0 is stricter – it requires Docker and will crash with a cryptic FileNotFoundError: 'docker' if the binary isn’t on PATH. Mini has no such requirement in local mode.

Install mini-swe-agent (the recommended path)

Pick one of these. I’d go with pipx for daily use – it isolates dependencies without polluting your system Python.

# Isolated CLI (pipx - my pick)
pip install pipx && pipx ensurepath
pipx install mini-swe-agent

# Or with uv (fastest)
pip install uv
uv tool install mini-swe-agent

# Or plain pip if you want the Python bindings too
pip install mini-swe-agent

# Or from source if you plan to hack on it
git clone https://github.com/SWE-agent/mini-swe-agent.git
cd mini-swe-agent
pip install -e .

Core dependencies (from pyproject.toml): pyyaml, jinja2, pydantic >=2.0, litellm, tenacity, rich, python-dotenv, typer, and datasets. That’s the full list.

Security note: Pin your litellm version. The mini-swe-agent team flagged litellm 1.82.7 and 1.82.8 as compromised – those releases could expose SSH keys and API keys. Newer mini-swe-agent releases block those versions in dependency constraints, but if you’re working from an older lockfile, run pip list | grep litellm and upgrade immediately.

First-time configuration

Run this once:

mini-extra config setup

The wizard prompts for a model name in provider/model format, then the matching API key variable name, then the actual key value. Everything gets written to ~/.mini-swe-agent/config. Skip it if you prefer: a bare export ANTHROPIC_API_KEY=sk-... in your shell also works.

Mini routes all model calls through litellm, which means OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, and local ollama endpoints all work – anything litellm supports. Turns out that one dependency does a lot of heavy lifting here.

Verify it works

Simplest smoke test:

mini --help # should print the CLI, including config path
mini -t "list the 5 largest files in this directory sorted by size"

By default the agent runs in interactive mode – it proposes a bash action and waits before executing. The quickstart docs cover the mode-switching commands in detail. Every run writes a trajectory log: a linear record of every message, every command, every response. That file is your debugging goldmine, and the first thing worth reading after any unexpected behavior.

Common install errors and the actual fixes

Pulled from real GitHub issues, not hypotheticals.

• FileNotFoundError: [Errno 2] No such file or directory: 'docker' – You’re running classic SWE-agent without Docker installed. Fix: install Docker Desktop, or switch to mini which runs locally without it. The docs don’t say Docker is mandatory (community complaints in issues #1021 and #1289 make this point repeatedly) – but it is.
• image ... does not match the specified platform: wanted linux/amd64, actual: linux/arm64/v8 – WSL2 x86_64 machines pull ARM64 images even when you set --platform linux/amd64 and DOCKER_DEFAULT_PLATFORM (tracked in issue #107). Workaround: pull the image manually with the platform flag first, then let SWE-agent reuse the cached image.
• WARN Model X does not support function calling – Then the run silently produces garbage. Fix: set agent.tools.parse_function.type: thought_action in your config. Applies to qwen3-coder, some deepseek variants, and older local models that don’t implement the function-calling spec.
• Custom config from an old tutorial doesn’t parse actions – v2 changed the default action regex from ```bash to ```mswea_bash_command. If you copy a pre-v2 config, actions won’t match. Fix: update the regex or set action_regex explicitly in your YAML. The official v2 migration guide lists this among the breaking changes.
• pipx: command not found after install – Run pipx ensurepath and restart your shell. Classic PATH issue on fresh installs.

Upgrade and uninstall

Upgrading between v2.x releases:

pipx upgrade mini-swe-agent # or: uv tool upgrade mini-swe-agent
# from source:
cd mini-swe-agent && git pull

Moving from v1 to v2? The big documented breaking change: the action regex. Check the migration guide linked above before touching your YAML configs.

Uninstall:

pipx uninstall mini-swe-agent
# or: pip uninstall mini-swe-agent
rm -rf ~/.mini-swe-agent # removes config, trajectories, keys

When to still use classic SWE-agent

There’s an interesting tension in the project’s own history here: the original framework accumulated years of custom scaffolding – specialized tools, the ACI interface, Docker-based isolation – and then the maintainers found that stripping most of it out didn’t hurt benchmark scores at all. That’s either a story about good engineering discipline or a reminder that complex scaffolding often serves the developer’s intuitions more than the model’s actual needs. Probably both.

Two cases where you’d stay on classic anyway. If you need EnIGMA (the CTF/cybersecurity mode), it runs on an older SWE-agent branch that hasn’t been ported to the new architecture yet. And if you have existing batch evaluation pipelines wired to the classic YAML config schemas, stay put until you have bandwidth to migrate – the schemas aren’t compatible across major versions.

For everyone else right now: mini is smaller, faster to start, and matches performance. Hard to argue with that combination.

FAQ

Is mini-swe-agent really as accurate as the original SWE-agent?

Yes – it’s on the SWE-bench verified leaderboard at north of 74% resolve rate (as of the current README). The benchmark numbers are the same; the codebase is ~100 lines instead of thousands.

Do I need an OpenAI or Anthropic key, or can I run this fully local?

Fully local works. Point litellm at an ollama endpoint with a config block specifying your local model name and api_base: "http://localhost:11434". One real catch: small models under roughly 14B parameters tend to struggle on SWE-bench-style tasks – the context windows and instruction-following aren’t quite there yet. Manage expectations accordingly, and check the litellm docs for any local model quirks specific to your setup.

Why does the docs page keep telling me to switch away from classic SWE-agent?

As LLMs got better at raw tool use, most of the custom scaffolding stopped adding value. Mini hands the model a bash environment and gets out of the way – fewer moving parts, easier debugging, same benchmark score. That’s the whole case.

Next step: run mini -t "fix the failing tests in this repo" inside a real project you know well, then read the resulting trajectory log. That single exercise teaches you more about how the agent actually works than any documentation will.