클라우드 없이 100% 로컬 AI 코딩 환경 구축하기 – Ollama + Docker 실전 튜토리얼

: Ollama(Llama 3.1 / Qwen2.5-Coder) + Docker + FastAPI를 활용한 프라이빗 AI 코딩 에이전트 웹 구축

AI에게 “이런 기능 만들어줘”라고 말하면 코드를 바로 생성하고, Docker 샌드박스 안에서 안전하게 실행까지 해주는 웹 인터페이스가 있다면 어떨까요?

클라우드에 코드·데이터를 절대 보내지 않고, 내 맥미니·PC에서 100% 로컬로 돌아가는 OPENCODE WEB을 직접 구축하는 방법을 실제 구동 가능한 전체 코드와 함께 알려드립니다.

이 글을 따라 하면 브라우저만 열어도 “삼성전자 주가 분석해줘”, “내 코인 포트폴리오 백테스트 코드 만들어줘” 같은 요청을 바로 처리할 수 있습니다.

1. 필수 준비물 및 환경 설정

① Docker Desktop 설치

코드 실행의 보안 핵심! 외부 네트워크 완전 차단된 샌드박스를 만들어줍니다.

• Docker Desktop 공식 사이트에서 설치 (Windows / macOS / Linux 모두 지원)
• 설치 후 터미널에서 docker --version으로 확인

② Ollama 설치 및 코딩 특화 모델 다운로드

AI의 ‘뇌’ 역할을 할 LLM입니다. 2026년 기준 코딩 성능이 가장 좋은 모델 추천.

# 터미널에서 실행
ollama pull qwen2.5-coder:7b
# 또는 Llama 3.1 8B (가벼움)
ollama pull llama3.1:8b

③ Python 패키지 설치

pip install fastapi uvicorn jinja2 python-multipart docker psutil

2. 시스템 아키텍처 및 핵심 코드 (총 4개 파일)

[파일 1] config.py – 중앙 설정

# config.py
OLLAMA_MODEL = "qwen2.5-coder:7b"
DOCKER_IMAGE = "python:3.11-slim"
MAX_TIMEOUT = 30          # 실행 제한 시간(초)
PORT = 8000
ALLOWED_HOSTS = ["127.0.0.1", "localhost"]

[파일 2] sandbox.py – Docker 안전 실행 엔진 (가장 중요!)

# sandbox.py
import docker
import time

client = docker.from_env()

def run_code_safely(code: str):
    try:
        container = client.containers.run(
            image="python:3.11-slim",
            command=f"timeout {MAX_TIMEOUT}s python -c '{code}'",
            detach=True,
            mem_limit="512m",
            cpu_shares=256,
            network_disabled=True,      # 인터넷 완전 차단 (보안 최우선)
            remove=True
        )
        
        start = time.time()
        while time.time() - start < MAX_TIMEOUT + 5:
            if container.status == "exited":
                logs = container.logs().decode("utf-8").strip()
                return {"success": True, "output": logs or "실행 완료 (출력 없음)"}
            time.sleep(0.3)
        
        container.stop()
        return {"success": False, "error": "실행 시간 초과 (무한루프 방지)"}
        
    except Exception as e:
        return {"success": False, "error": str(e)}

[파일 3] main.py – OPENCODE WEB 핵심 서버

# main.py
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
import ollama
from sandbox import run_code_safely
from config import OLLAMA_MODEL

app = FastAPI(title="OPENCODE WEB")
templates = Jinja2Templates(directory="templates")

@app.get("/", response_class=HTMLResponse)
async def home(request: Request):
    return templates.TemplateResponse("index.html", {"request": request})

@app.post("/run")
async def run_ai_code(request: Request):
    data = await request.json()
    prompt = data.get("prompt", "")

    # 1. Ollama에게 코드 생성 요청 (설명 없이 코드만!)
    response = ollama.chat(
        model=OLLAMA_MODEL,
        messages=[{"role": "user", "content": f"Python 코드만 작성해. 설명, 주석, 마크다운 절대 넣지 말고 코드만:\n{prompt}"}]
    )
    generated_code = response['message']['content'].strip()

    # 2. Docker 샌드박스에서 실제 실행
    result = run_code_safely(generated_code)

    return {
        "generated_code": generated_code,
        "execution_result": result
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

[파일 4] templates/index.html (브라우저 UI)

<!-- templates/index.html -->
<h1 style="text-align:center">🔥 OPENCODE WEB</h1>
<textarea id="prompt" rows="4" style="width:100%" placeholder="예시 입력: 삼성전자 주가 데이터를 받아서 이동평균선 차트 그리는 코드를 만들어줘"></textarea>
<button onclick="sendPrompt()" style="margin-top:10px">AI 코드 생성 & 실행하기</button>

<div id="result" style="margin-top:30px"></div>

<script>
async function sendPrompt() {
    const prompt = document.getElementById('prompt').value;
    const res = await fetch('/run', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({prompt})
    });
    const data = await res.json();
    
    document.getElementById('result').innerHTML = `
        <h3>✅ AI가 생성한 코드</h3>
        <pre>${data.generated_code}</pre>
        <h3>📊 실행 결과</h3>
        <pre>${JSON.stringify(data.execution_result, null, 2)}</pre>
    `;
}
</script>

3. OPENCODE WEB 바로 실행하기

프로젝트 폴더에서 아래 한 줄만 입력하면 끝!

python main.py

브라우저에서 http://127.0.0.1:8000 접속 → 바로 사용 가능!