# SWE-agent Code Fixer

## Overview

[SWE-agent](https://github.com/SWE-agent/SWE-agent) is an AI-powered software engineering agent that **automatically resolves GitHub issues** by letting a language model interact with a code repository through a terminal interface. Presented at **NeurIPS 2024** and with over **15,000 GitHub stars**, SWE-agent has become the leading open-source solution for automated bug fixing and code repair.

Unlike most tools in this documentation, SWE-agent does **not require a GPU** — it calls external LLM APIs (Claude, GPT-4, Gemini, or self-hosted models) to reason about code and generate fixes. What it *does* need is a reliable Docker environment for safe, sandboxed code execution. Clore.ai's CPU servers (or any rented instance with Docker) are a perfect fit.

**Key features:**

* 🐛 Automated GitHub issue resolution with a single command
* 🔒 Sandboxed execution inside Docker containers — safe to run arbitrary code
* 🤖 Supports Claude, GPT-4, Gemini, OpenAI-compatible, and local models
* 🌐 Web UI for monitoring agent progress
* 🛡️ Cybersecurity mode for CTF challenges and penetration testing
* 📊 SWE-bench compatible — tested against 300+ real GitHub issues
* 🔧 Configurable agent behaviors via YAML config files

***

## Requirements

### Hardware Requirements

SWE-agent doesn't need a GPU — it uses API-based LLMs for reasoning:

| Tier                | CPU        | RAM   | Storage    | Clore.ai Price |
| ------------------- | ---------- | ----- | ---------- | -------------- |
| **Minimum**         | 4 cores    | 8 GB  | 30 GB SSD  | \~$0.03/hr     |
| **Recommended**     | 8 cores    | 16 GB | 60 GB SSD  | \~$0.06/hr     |
| **Heavy workloads** | 16 cores   | 32 GB | 100 GB SSD | \~$0.10/hr     |
| **With local LLM**  | GPU server | 32 GB | 100 GB SSD | \~$0.20/hr     |

> 💡 **Cost tip:** SWE-agent is unusually cheap to run on Clore.ai since you don't need a GPU. The main cost is the LLM API calls (e.g., Claude Sonnet costs \~$0.003/1K tokens). A typical issue fix costs $0.50–$2.00 in API fees.

### Software & API Requirements

| Requirement      | Details                                      |
| ---------------- | -------------------------------------------- |
| **Docker**       | Required for sandboxed code execution        |
| **LLM API Key**  | Anthropic, OpenAI, Google, or self-hosted    |
| **GitHub Token** | For accessing private repos and creating PRs |
| **Python 3.11+** | For `pip install sweagent` method            |

### LLM API Pricing Reference

| Model           | Input          | Output         | Typical run cost          |
| --------------- | -------------- | -------------- | ------------------------- |
| Claude Sonnet 4 | $3/M tokens    | $15/M tokens   | \~$1.00–$2.00             |
| GPT-4o          | $5/M tokens    | $15/M tokens   | \~$1.00–$3.00             |
| GPT-4o mini     | $0.15/M tokens | $0.60/M tokens | \~$0.05–$0.20             |
| Ollama (local)  | Free           | Free           | Clore.ai hourly cost only |

***

## Quick Start

### Step 1 — Rent a Server on Clore.ai

1. Log in to [clore.ai](https://clore.ai)
2. Filter: **Docker enabled** — GPU is optional (CPU server is fine)
3. Recommended image: `ubuntu:22.04` or any Docker-enabled image
4. Open ports: **22** (SSH), **7860** (SWE-agent Web UI)
5. Minimum 16 GB RAM recommended for running Docker-in-Docker

### Step 2 — Connect via SSH

```bash
ssh -p <CLORE_SSH_PORT> root@<CLORE_SERVER_IP>

# Verify Docker is available
docker --version
docker run --rm hello-world
```

### Step 3 — Pull the SWE-agent Docker Image

```bash
# Pull the official SWE-agent image (pre-built, recommended)
docker pull sweagent/swe-agent:latest

# Verify
docker images | grep sweagent
```

Alternatively, build from source for the latest development version:

```bash
git clone https://github.com/SWE-agent/SWE-agent.git
cd SWE-agent
docker build -t sweagent/swe-agent:local .
```

### Step 4 — Set Up API Keys

```bash
# Create a directory for SWE-agent configuration
mkdir -p /workspace/sweagent && cd /workspace/sweagent

# Create environment file with your API keys
cat > /workspace/sweagent/.env << 'EOF'
# LLM API Keys (add only what you have)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# GitHub token for accessing repos and creating PRs
GITHUB_TOKEN=ghp_...

# Optional: self-hosted LLM endpoint
# OPENAI_BASE_URL=http://your-ollama-server:11434/v1
EOF

chmod 600 /workspace/sweagent/.env
```

### Step 5 — Fix Your First GitHub Issue

```bash
# Basic usage — fix a GitHub issue with Claude Sonnet
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /workspace/sweagent/output:/output \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.model.per_instance_cost_limit=2.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1 \
    --actions.apply_patch_locally=true \
    --output_dir=/output
```

### Step 6 — Review the Output

```bash
# SWE-agent writes results to the output directory
ls -la /workspace/sweagent/output/

# View the generated patch
cat /workspace/sweagent/output/*.patch

# View the full agent trajectory (what the agent did)
cat /workspace/sweagent/output/*.traj | python3 -m json.tool | less
```

***

## Configuration

### Basic Configuration File

Instead of long command-line flags, use a YAML config:

```bash
cat > /workspace/sweagent/config.yaml << 'EOF'
# SWE-agent configuration
agent:
  model:
    name: claude-sonnet-4-20250514
    per_instance_cost_limit: 2.00
    total_cost_limit: 10.00
    temperature: 0.0
  config:
    # System prompt for the agent
    system_template: "default"
    # How many retries on API errors
    retry_with_output_if_run_fails: true

env:
  repo:
    # Will be set per-run
    github_url: ""
  deployment:
    docker_args:
      - "--memory=4g"
      - "--cpus=2"

problem_statement:
  github_url: ""

actions:
  apply_patch_locally: true
  open_pr: false  # Set to true to auto-create a PR

output_dir: /output
EOF
```

```bash
# Run with config file
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /workspace/sweagent/output:/output \
  -v /workspace/sweagent/config.yaml:/config.yaml \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python run.py \
    --config /config.yaml \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/42
```

### Web UI Mode

SWE-agent includes a Gradio-based web interface for interactive use:

```bash
# Start the web UI
docker run -d \
  --name sweagent-ui \
  --env-file /workspace/sweagent/.env \
  -p 7860:7860 \
  -v /workspace/sweagent/output:/output \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python app.py --port 7860 --host 0.0.0.0

# Access the UI
echo "Open: http://<CLORE_SERVER_IP>:<MAPPED_PORT>"
docker logs -f sweagent-ui
```

### Using Different LLM Providers

```bash
# GPT-4o (OpenAI)
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=gpt-4o-2024-11-20 \
    --agent.model.per_instance_cost_limit=3.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# GPT-4o Mini (budget option)
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=gpt-4o-mini-2024-07-18 \
    --agent.model.per_instance_cost_limit=0.50 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# Local Ollama (pair with Ollama guide)
# First deploy Ollama on a GPU server (see ../language-models/ollama.md)
# Then use it as the backend for SWE-agent:
docker run --rm \
  -e OPENAI_API_KEY=dummy \
  -e OPENAI_BASE_URL=http://<OLLAMA_HOST>:11434/v1 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=qwen2.5-coder:32b \
    --agent.model.per_instance_cost_limit=0.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1
```

### Batch Processing Multiple Issues

```bash
# Process multiple issues using SWE-bench format
cat > /workspace/sweagent/batch_issues.json << 'EOF'
[
  {
    "repo": "USER/REPO",
    "issue_number": 1,
    "model": "claude-sonnet-4-20250514"
  },
  {
    "repo": "USER/REPO",
    "issue_number": 2,
    "model": "claude-sonnet-4-20250514"
  }
]
EOF

# Batch run script
cat > /workspace/sweagent/run_batch.sh << 'BASH'
#!/bin/bash
set -e

ISSUES_FILE="${1:-/workspace/sweagent/batch_issues.json}"
OUTPUT_DIR="/workspace/sweagent/output"
ENV_FILE="/workspace/sweagent/.env"

echo "Starting batch SWE-agent run..."
python3 -c "
import json
issues = json.load(open('$ISSUES_FILE'))
for i, issue in enumerate(issues):
    print(f'Issue {i+1}/{len(issues)}: {issue[\"repo\"]}#{issue[\"issue_number\"]}')
" 

jq -c '.[]' "$ISSUES_FILE" | while read issue; do
    REPO=$(echo "$issue" | jq -r '.repo')
    ISSUE_NUM=$(echo "$issue" | jq -r '.issue_number')
    MODEL=$(echo "$issue" | jq -r '.model')

    echo "=== Processing: $REPO#$ISSUE_NUM with $MODEL ==="
    
    docker run --rm \
      --env-file "$ENV_FILE" \
      -v "$OUTPUT_DIR:/output" \
      -v /var/run/docker.sock:/var/run/docker.sock \
      sweagent/swe-agent:latest \
      python run.py \
        --agent.model.name="$MODEL" \
        --agent.model.per_instance_cost_limit=2.00 \
        --env.repo.github_url="https://github.com/$REPO" \
        --problem_statement.github_url="https://github.com/$REPO/issues/$ISSUE_NUM" \
        --output_dir=/output || echo "FAILED: $REPO#$ISSUE_NUM"
done

echo "Batch complete. Results in $OUTPUT_DIR"
BASH

chmod +x /workspace/sweagent/run_batch.sh
/workspace/sweagent/run_batch.sh
```

***

## Docker-in-Docker Setup

SWE-agent runs code in nested Docker containers for security. This requires Docker socket access:

```bash
# Verify Docker socket is accessible
ls -la /var/run/docker.sock

# Test that Docker-in-Docker works
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker:latest docker run --rm hello-world

# SWE-agent will automatically pull its sandbox image
# Default sandbox: sweagent/swe-agent:latest (or a specialized env image)
```

### Security Considerations

```bash
# SWE-agent sandbox resource limits (configure in your YAML)
cat >> /workspace/sweagent/config.yaml << 'EOF'
env:
  deployment:
    docker_args:
      - "--memory=4g"          # Limit sandbox RAM
      - "--cpus=2"             # Limit sandbox CPU
      - "--network=bridge"     # Isolated network
      - "--read-only"          # Read-only filesystem (with exceptions)
      - "--tmpfs=/tmp:size=1g" # Writable /tmp only
EOF

# Never run SWE-agent on your host directly — always use Docker
# The sandbox container isolates potentially harmful code
```

### Using a Pre-built Environment Image

```bash
# SWE-agent supports custom environment images per repository
# This speeds up runs by pre-installing dependencies
cat > /workspace/sweagent/env-config.yaml << 'EOF'
env:
  deployment:
    image: sweagent/swe-agent:latest
    pre_install:
      - "pip install -e ."
      - "pip install pytest"
    post_clone:
      - "git config --global user.email 'agent@sweagent.ai'"
      - "git config --global user.name 'SWE-agent'"
EOF
```

***

## Tips & Best Practices

### 🎯 Writing Effective Problem Statements

The quality of SWE-agent's fix depends heavily on the issue description:

````bash
# Method 1: Use a GitHub issue URL (recommended)
--problem_statement.github_url=https://github.com/USER/REPO/issues/42

# Method 2: Provide a text file with detailed description
cat > /workspace/sweagent/issue.txt << 'EOF'
## Bug Description
The function `calculate_total()` in `billing/calculator.py` returns 0 
when the discount is exactly 100%. 

## Steps to Reproduce
```python
total = calculate_total(price=100, discount=100)
assert total == 0  # This fails, returns 100 instead
````

## Expected Behavior

Should return 0 when discount is 100%.

## Relevant Code

See `billing/calculator.py` lines 45-67. EOF

docker run --rm\
\--env-file /workspace/sweagent/.env\
-v /workspace/sweagent/output:/output\
-v /workspace/sweagent/issue.txt:/issue.txt\
-v /var/run/docker.sock:/var/run/docker.sock\
sweagent/swe-agent:latest\
python run.py\
\--agent.model.name=claude-sonnet-4-20250514\
\--env.repo.github\_url=<https://github.com/USER/REPO\\>
\--problem\_statement.text\_file=/issue.txt

````

### 💰 Cost Control

```bash
# Always set per-instance cost limits
--agent.model.per_instance_cost_limit=2.00  # Max $2 per issue

# Use GPT-4o mini for initial triage, Claude for complex fixes
# Budget strategy: ~$0.10 to scan, ~$1.50 to fix

# Monitor costs in real-time
docker logs -f sweagent-ui | grep -E "(cost|tokens|spent)"

# Set a total budget across all runs
--agent.model.total_cost_limit=20.00  # Stop all runs after $20
````

### 🔄 Auto-PR Creation

```bash
# Automatically create a pull request with the fix
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.model.per_instance_cost_limit=2.00 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/42 \
    --actions.open_pr=true \
    --actions.push_gh_repo_url=https://github.com/USER/REPO
```

### 📊 SWE-bench Evaluation

```bash
# Run SWE-agent against the official SWE-bench benchmark
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run_batch.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --instances.type=swe_bench \
    --instances.subset=lite \
    --instances.split=test \
    --output_dir=/output \
    --num_workers=4
```

### 🛡️ Cybersecurity Mode

```bash
# SWE-agent supports CTF and cybersecurity challenges
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.config=config/default_from_url_ctf.yaml \
    --env.deployment.image=sweagent/ctf-env:latest \
    --problem_statement.text="Find the flag in the running web service at http://challenge.local:8080" \
    --output_dir=/output
```

***

## Troubleshooting

### Docker socket permission denied

```bash
# Error: permission denied while trying to connect to Docker daemon
# Solution: ensure Docker socket is mounted correctly

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  docker ps

# If you see permission errors, check socket permissions
ls -la /var/run/docker.sock
# Should be: srw-rw---- root docker

# Add current user to docker group (if not root)
usermod -aG docker $USER
newgrp docker
```

### API key errors

```bash
# Verify your API key is set correctly
docker run --rm \
  --env-file /workspace/sweagent/.env \
  sweagent/swe-agent:latest \
  python -c "
import os
keys = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GITHUB_TOKEN']
for k in keys:
    val = os.environ.get(k, 'NOT SET')
    masked = val[:8] + '...' if len(val) > 8 else val
    print(f'{k}: {masked}')
"

# Test Anthropic API key
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"
```

### Agent gets stuck in a loop

```bash
# SWE-agent has a built-in step limit (default ~100 steps)
# Increase or decrease via config:

docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --agent.model.per_instance_cost_limit=2.00 \
    --agent.max_requeries=5 \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# Kill a stuck run
docker ps | grep sweagent
docker stop <container_id>
```

### Out of memory during code execution

```bash
# Increase sandbox memory limit
docker run --rm \
  --env-file /workspace/sweagent/.env \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /workspace/sweagent/output:/output \
  sweagent/swe-agent:latest \
  python run.py \
    --agent.model.name=claude-sonnet-4-20250514 \
    --env.deployment.docker_args='["--memory=8g", "--cpus=4"]' \
    --env.repo.github_url=https://github.com/USER/REPO \
    --problem_statement.github_url=https://github.com/USER/REPO/issues/1

# For large codebases, increase the Clore.ai instance to 32GB RAM
```

### GitHub rate limiting

```bash
# GitHub API has rate limits — use a personal access token with repo scope
# Check your current rate limit status
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit | jq '.rate'

# If rate limited, wait for reset or use a different token
# Rate limit resets every hour
```

***

## Further Reading

* [SWE-agent GitHub](https://github.com/SWE-agent/SWE-agent) — Main repository and docs
* [SWE-agent Documentation](https://swe-agent.com/docs/) — Official documentation
* [SWE-agent Paper (NeurIPS 2024)](https://arxiv.org/abs/2405.15793) — Research paper
* [SWE-bench Leaderboard](https://www.swebench.com/) — See how different models perform
* [Clore.ai Getting Started](https://docs.clore.ai/guides/getting-started/getting-started) — Platform basics
* [GPU Comparison Guide](https://docs.clore.ai/guides/getting-started/gpu-comparison) — If you need GPU for local LLMs
* [Running Ollama on Clore.ai](https://docs.clore.ai/guides/language-models/ollama) — Local LLM backend for SWE-agent
* [Running vLLM on Clore.ai](https://docs.clore.ai/guides/language-models/vllm) — High-throughput local LLM server
* [Anthropic API Pricing](https://www.anthropic.com/pricing) — Claude API costs
* [OpenAI API Pricing](https://openai.com/api/pricing/) — GPT-4 API costs

> 💡 **Clore.ai + SWE-agent sweet spot:** Rent a CPU-only server (4 cores, 16GB RAM) at \~$0.05/hr, run SWE-agent with Claude Sonnet 4, and fix GitHub issues for roughly **$1–2 total per issue** (API costs) plus a few cents of Clore.ai time. For teams with many issues, this beats hiring a developer for routine bug fixes by orders of magnitude.