STEP1. 개요 플로우 #

1. WSL 2 + 필수 Windows 기능 활성화

2. Docker Desktop(WSL 2 백엔드) 설치

3. AgentSeek 리포지토리 복제 후 Python 가상 환경(venv) 준비

4. Docker Compose로 「프론트엔드 + Redis + SearxNG」 시작

5. FastAPI 백엔드를 수동으로 확인 → NSSM으로 Windows 서비스화

6. BACKEND_URL을 host.docker.internal:8000으로 변경하여 프론트엔드와 연동

7. 재시작 테스트 & 운영 확인

STEP2. 전제 환경 체크 #

권장: 모든 작업을 관리자 권한의 PowerShell에서 수행하면 권한 오류를 방지할 수 있습니다.

STEP3. WSL 2 & Windows 기능 활성화 #

wsl --install -d Ubuntu          # 22.04가 기본으로 설치됨
# 중간에 오류가 발생하면: 아래를 개별 실행
# dism /online /enable-feature ...
# wsl --update
# wsl --set-default-version 2

완료 후 PC를 재시작하고, wsl -l -v로 Ubuntu가 Version 2로 동작하는지 확인합니다.

STEP4. Docker Desktop 설치 #

winget install -e --id Docker.DockerDesktop

초기 시작 시 설정 #

• Use the WSL 2 based engine → ON

• Add Docker CLI to the PATH → ON

• Start Docker Desktop when you log in → ON (General 탭)

작업 표시줄의 고래 아이콘이 _녹색 표시_로 안정화되면 OK입니다.

STEP5. 소스 다운로드 & Python 가상 환경 #

cd C:Dev               # 임의의 작업 디렉터리
git clone https://github.com/AgenticSeek/agenticSeek.git
cd agenticSeek
python -m venv .venv
..venvScriptsActivate.ps1
pip install -r requirements.txt

config.ini를 편집하여 GPUStack 등 백엔드 LLM 엔드포인트를 지정합니다:

[PROVIDER]
provider_name = gpustack
provider_server_address = http://<GPUStack_IP>:<port>/v1

[BROWSER]
headless_browser = True  ; 브라우저를 비표시로 하려는 경우

STEP6. Docker Compose로 프론트엔드 시작 #

docker-compose.yml의 frontend.environment를 수정하여 호스트 FastAPI를 참조하도록 합니다.

environment:
  - NODE_ENV=development
  - CHOKIDAR_USEPOLLING=true
  - BACKEND_URL=http://host.docker.internal:8000
  - VITE_BACKEND_URL=http://host.docker.internal:8000

# 반영
docker compose down
docker compose up -d --build   # 초기에는 --build 권장

상태 확인:

docker compose ps

frontend | Up, redis | Up, searxng | Up이 표시되면 준비 완료입니다.

STEP7. FastAPI 백엔드 수동 시작 테스트 #

cd C:AgentSeekagenticSeek
..venvScriptsActivate.ps1
python api.py --host 0.0.0.0 --port 8000

• 브라우저에서 http://localhost:8000/docs가 열리면 성공.

• Ctrl + C로 중지.

STEP8. NSSM으로 백엔드를 Windows 서비스화 #

8-1 NSSM 다운로드 #

https://nssm.cc/download에서 nssm-2.24.zip을 압축 해제: 예 C:Toolsnssmnssm.exe

8-2 서비스 등록(관리자 PowerShell) #

& "C:Toolsnssmnssm.exe" install AgentSeekBackend ^
  "C:AgentSeekagenticSeek.venvScriptspython.exe" ^
  "api.py --host 0.0.0.0 --port 8000" ^
  -d "C:AgentSeekagenticSeek"

추가 설정 #

• I/O 탭

  • Output: C:AgentSeekagenticSeek.logsbackend.log

  • Error: C:AgentSeekagenticSeek.logsbackend-err.log

• Service 탭

  • Start type: Automatic (Delayed Start)

Start-Service AgentSeekBackend
Get-Service AgentSeekBackend   # Status: Running

STEP9. 동작 검증 #

1. 브라우저 → http://localhost:3000 → 우측 상단이 Connected

2. Swagger UI → http://localhost:8000/docs가 열림

3. 재시작 테스트 후에도 ①②가 유지되면 자동 시작 설정 완료

STEP10. 에이전트 사용 TIPS #

• GUI는 자동 라우터로 에이전트를 분배

• 특정 에이전트 지정

  • @FileAgent zip *.csv into files.zip

  • JSON 지시 형식도 가능: @FileAgent {"action":"zip","pattern":"*.csv"}

• 100% 고정하려면 CLI:

  python cli.py --agent FileAgent "zip *.csv"

STEP11. 트러블슈팅 빠른 참고표 #

STEP12. 참고 링크 #

• Docker Desktop Documentation https://docs.docker.com/desktop/windows/

• NSSM – the Non‑Sucking Service Manager https://nssm.cc/

• AgentSeek GitHub (개발 브랜치) https://github.com/AgenticSeek/agenticSeek

이상으로 Windows 11에서 AgentSeek WebGUI를 안정적으로 운영하기 위한 설정 절차가 완료되었습니다.