XaresAICoder
Ask DeepWiki
생산성 향상을 위해 VS Code (code-server)와 여러 AI 코딩 어시스턴트를 통합한 전문 브라우저 기반 AI 개발 환경입니다.
Workspace Manager
개요 (Overview)
XaresAICoder는 브라우저에서 VS Code를 실행하는 격리된 개발 워크스페이스를 제공하며, 포괄적인 개발 지원을 위해 통합 AI 코딩 도구를 갖추고 있습니다. 각 워크스페이스는 리소스 제한, 자동 정리 기능, 원활한 서브도메인 기반 포트 포워딩이 적용된 별도의 Docker 컨테이너에서 실행됩니다.
✨ 주요 기능 (Key Features)
🎯 전문 개발 환경 (Professional Development Environment)
- 브라우저 기반 VS Code: 라이트 테마에서 영감을 받은 디자인의 브라우저 기반 VS Code 지원
- 격리된 Docker 워크스페이스: 자동 리소스 관리 기능을 갖춘 격리형 Docker 워크스페이스 제공
- 설정 가능한 메모리 할당 (Configurable Memory Allocation): 워크스페이스별로 1GB, 2GB, 4GB, 8GB 또는 16GB RAM 선택 가능
- CPU 코어 선택 (CPU Cores Selection): 워크스페이스별로 1~8개의 CPU 코어 할당 가능
- 리소스 제한 (Resource Limits): 동시 워크스페이스 제한 및 워크스페이스별 리소스 상한 설정 가능
- GPU 가속 지원 (GPU Acceleration Support): ML/AI 워크로드에 대한 자동 GPU 패스스루(passthrough) 기능
- 듀얼 프록시 모드 (Dual Proxy Modes): 워크스페이스별 LLM 로깅 프록시 (mitmproxy, 모든 트래픽 기록 및 AI 대화 캡처) 또는 보안 프록시 (Squid, 화이트리스트 전용 접근 제어)
- 서브도메인 포트 포워딩: (예:
projectid-5000.localhost)
- 실시간 컨테이너 관리: 시작/중지 제어를 통한 실시간 컨테이너 관리
- 선택적 비밀번호 보호: 워크스페이스 보안을 위한 선택적 비밀번호 보호 기능
🤖 AI 개발 도구
여러 AI 코딩 어시스턴트가 미리 구성된 작업 공간:
- Claude Code: 깊은 코드베이스 이해를 위한 Anthropic의 에이전트 도구 (CLI 및 VS Code 확장 프로그램)
- OpenAI Codex CLI: OpenAI의 터미널 기반 코딩 에이전트
- GitHub Copilot CLI: 터미널용 GitHub의 코딩 에이전트로, 모든 Copilot 플랜(Free 및 학생 포함)에 포함됩니다.
- OpenCode: 75개 이상의 모델 제공업체를 위한 오픈 소스 코딩 에이전트
- Crush: 세션 내 모델 전환 및 LSP 통합 기능을 갖춘 멀티 모델 AI
- Pi: 최소한의 다중 공급업체 코딩 에이전트
- Cline: VS Code 확장 프로그램: 다중 파일 편집 및 터미널 명령을 위한 자율 에이전트
- Kilo Code: VS Code 확장 프로그램: 채팅, 자동 완성 및 모드를 갖춘 오픈 소스 에이전트
사용자는 자체 구독 또는 API 키를 가져옵니다. update_ai_agents는 sudo 없이 CLI 도구를 업데이트하며, 아무것도 자동으로 업데이트되지 않으므로 워크숍의 모든 참가자는 동일한 버전을 유지합니다.
🔧 개발 준비 완료
- 빈 프로젝트(Empty Project) 또는 Git 클론(Git Clone): 새로 시작하거나 모든 HTTP/HTTPS Git 저장소를 작업 공간에 직접 복제할 수 있습니다.
- 개인 저장소 지원(Private Repository Support): 사용자 이름 및 액세스 토큰을 사용한 보안 인증.
- 지속적인 Git 자격 증명(Persistent Git Credentials): 클론 후 원활한 푸시/풀 작업 수행.
- 통합 Git 서버 (선택 사항)(Integrated Git Server): GitHub Actions 호환성을 갖춘 자체 호스팅 Forgejo.
- 자동 Git 저장소 생성(Automatic Git Repository Creation): 작업 공간 구성과 함께 원클릭 Git 저장소 설정.
- GitHub 통합(GitHub Integration): 원활한 워크플로우를 위한 사전 설치된 GitHub CLI.
📁 프로젝트 구성
- 스마트 프로젝트 그룹화(Smart Project Grouping) - 프로젝트를 사용자 지정 그룹(업무, 개인, 학습 등)으로 정리합니다.
- 드래그 앤 드롭 인터페이스(Drag & Drop Interface) - 시각적 피드백이 있는 직관적인 파일 관리자 스타일의 구성을 제공합니다.
- 사이드바 그룹 관리(Sidebar Group Management) - 탐색 사이드바에서 그룹을 생성, 이름 변경 및 삭제할 수 있습니다.
- 즉시 필터링(Instant Filtering) - 아무 그룹이나 클릭하면 프로젝트가 필터링되고, 다시 클릭하면 모든 항목이 표시됩니다.
- 그룹 배지(Group Badges) - 원클릭 필터링 기능을 갖춘 시각적인 프로젝트 그룹 표시기입니다.
- 자동 구성(Automatic Organization) - 프로젝트는 기본적으로 "미분류(Uncategorized)"에 속하며 언제든지 이동할 수 있습니다.
🆕 최신 업데이트
그룹 사용자 (Group Users) (최신)
- ✅ 사용자별 자체 로그인(Own Logins per Person) - 관리자가 사용자(Users 탭)를 생성하고, 각 사용자에게 하나 이상의 프로젝트 그룹을 할당합니다. 예: 교사 및 학급별로 각각 설정.
- ✅ 제한된 대시보드(Restricted Dashboard) - 그룹 사용자는 자신의 그룹에 속한 프로젝트만 볼 수 있으며, 해당 프로젝트를 열고, 시작하고, 중지하고, 이름을 변경할 수 있고 노트와 작업 공간 비밀번호를 편집할 수 있습니다. 그 외 모든 것은 관리자에게 남아있습니다.
- docs/user-guide.md → 그룹 사용자 및 docs/API.md → 로그인 및 역할 참고
보안 강화(Security Hardening)
- ✅ 관리자 로그인(Admin Login) - 대시보드와 API 사용 시 로그인이 필요합니다 (
ADMIN_PASSWORD, deploy.sh에 의해 생성됨).
- ✅ 네트워크 격리(Network Isolation) - 작업 공간은 API 서버에 접근할 수 없습니다. 보안 및 LLM 로깅 프록시(LLM Logging Proxy) 작업 공간은 별도의 네트워크를 가지므로 화이트리스트 우회가 불가능합니다.
- ✅ 작업 공간별 자체 Git 계정(Own Git Account per Workspace) - 각 작업 공간은 자체 Forgejo 사용자 및 토큰을 가지며, 비공개 저장소를 사용합니다. Forgejo 관리자 비밀번호는 절대 서버를 벗어나지 않습니다.
- ✅ 안전한 클론(Safer Clones) - 자격 증명이 클론 스냅샷에서 제거됩니다. 클론에는 비밀번호가 필요하며 자체 저장소를 가집니다.
- ✅ 강화된 컨테이너(Hardened Containers) - 작업 공간별 sudo 권한, 하드 CPU 제한, Docker의 기본 seccomp 프로파일, 선택적 디스크 할당량(disk quota)을 제공합니다.
- 기존 설치 환경 업데이트 전 docs/DEPLOYMENT.md → 업그레이드를 참고하세요.
사용자 정의 서브도메인 별칭(Custom Subdomain Aliases)
- ✅ 포트별 가독성 높은 URL: 모든 워크스페이스 포트를 짧은 서브도메인에 매핑할 수 있습니다 (예:
<uuid>-8000.example.com 대신 myapp.example.com).
- ✅ 자동 감지 포트 목록: UI에서 컨테이너가 수신 중인 TCP 포트와 자유 텍스트 입력 필드를 나열합니다.
- ✅ 선택적 기본 인증(Optional Basic Auth): 각 별칭을 사용자 이름/비밀번호로 보호할 수 있습니다 (추측하기 쉬운 이름이 UUID보다 더 위험할 수 있음).
- ✅ 영속성: 별칭은 워크스페이스 중지/재시작 후에도 유지됩니다. 삭제된 별칭은 인증으로 보호되는 프론트엔드를 노출하는 대신 깨끗한 404를 반환합니다.
- ✅ 전역 고유성 및 예약어: 13개의 예약 단어(
git, api, admin, …)가 차단됩니다.
워크숍 지원(Workshop Support)
- ✅ 워크스페이스 복제(Workspace Cloning): 워크숍을 위해 기본 워크스페이스를 N개의 동일한 사본으로 복제할 수 있습니다.
- ✅ 워크숍 랜딩 페이지: 참가자가 자동 워크스페이스 할당과 함께 자체 등록할 수 있는 기능을 제공합니다.
- ✅ 관리자 개요(Admin Overview): 클레임 관리, 워크스페이스 출시, CSV 내보내기 등의 관리가 가능합니다.
- ✅ 복제본별 전용 Git 저장소: 각 복제본은 소스의 히스토리와 함께 자체 Forgejo 사용자 및 비공개 저장소를 가집니다.
듀얼 프록시 모드(Dual Proxy Modes)
- ✅ LLM 로깅 프록시: mitmproxy가 모든 트래픽을 기록하고 AI API 대화를 캡처합니다.
- ✅ 보안 프록시: 평가를 위해 Squid 화이트리스트 전용 필터링이 가능합니다.
- ✅ 도메인 기록 및 화이트리스트 생성: 강사가 도메인을 기록하고 이를 학생의 화이트리스트로 적용할 수 있습니다.
- ✅ LLM 대화 내보내기: 캡처된 대화를 확인, 내보내고 문서화할 수 있습니다.
비밀번호 관리(Password Management)
- ✅ 비밀번호 설정/업데이트/제거: UI와 API를 통해 전체 라이프사이클 관리가 가능합니다.
- ✅ 실행 중 및 중지된 컨테이너 지원: 원활한 구성 업데이트가 가능합니다.
🚀 빠른 시작(Quick Start)
필수 조건 (Prerequisites)
- Docker (Docker Compose v1 또는 v2 포함)
- 컨테이너용으로 4GB 이상의 RAM 필요
- 최신 웹 브라우저 (Chrome/Chromium 권장)
- 선택 사항: AI/ML 가속을 위한 드라이버가 설치된 NVIDIA GPU
원 명령어 설치(One-Command Installation)
git clone <repository-url>
cd XaresAICoder
...
끝입니다! 배포 스크립트가 자동으로 다음 작업을 수행합니다:
- ✅ Docker Compose 버전 감지 (v1 또는 v2)
- ✅ 영구적인 Docker 네트워크 설정
- ✅ AI 도구가 포함된 사용자 지정 VS Code 이미지 빌드
- ✅ 환경 설정 구성
- ✅ 애플리케이션 배포 및 상태 확인(health-check)
플랫폼 접속하기
배포가 완료되면, 브라우저를 열고 다음 주소로 이동하세요:
관리자 비밀번호로 로그인하세요: deploy.sh는 첫 실행 시 비밀번호를 생성하며, 이 비밀번호를 한 번 출력하고 .env 파일에 ADMIN_PASSWORD로 저장합니다.
첫 프로젝트 만들기
빈 프로젝트
- 프로젝트 이름을 입력합니다.
- 메모리 할당량(1GB, 2GB 기본값, 4GB, 8GB, 또는 16GB RAM)과 CPU 코어 수(1-8)를 선택합니다.
- 선택 사항: 안전한 접속을 위해 "작업 공간 비밀번호 보호"를 체크합니다.
- 선택 사항: Git 설정을 자동으로 구성하려면 "Git 리포지토리 생성"을 체크합니다.
- "작업 공간 생성(Create Workspace)"을 클릭합니다.
Git 리포지토리에서 가져오기
- 프로젝트 이름을 입력합니다.
- "Git 리포지토리에서 클론하기(Clone from Git Repository)"를 체크합니다.
- Git 리포지토리 URL (예:
https://github.com/user/repo.git)을 입력합니다.
- 비공개 리포지토리의 경우:
- Git 사용자 이름 (GitHub/GitLab 사용자 이름)을 입력합니다.
- 액세스 토큰(Access Token) (GitHub Personal Access Token, GitLab 토큰 등)을 입력합니다.
- 필요한 메모리 할당량과 CPU 코어 수를 선택합니다.
- 선택 사항: 안전한 접속을 위해 "작업 공간 비밀번호 보호"를 체크합니다.
- "작업 공간 생성(Create Workspace)"을 클릭합니다.
✅ 결과: VS Code가 열리면서 리포지토리 파일이 편집할 준비가 완료되며, 모든 Git 작업(push, pull 등)이 원활하게 작동합니다!
프로젝트 정리하기
프로젝트를 생성한 후에는 직관적인 그룹화 시스템을 사용하여 프로젝트들을 정리할 수 있습니다:
프로젝트 그룹 사용하기
- 그룹 보기(View Groups): 'AI 도구(AI Tools)' 아래 사이드바에서 그룹을 확인할 수 있습니다.
- 그룹 생성(Create Groups): '그룹 추가(Add Group)'를 클릭하고 이름(예: "업무", "개인", "학습")을 입력합니다.
- 프로젝트 이동(Move Projects): 메인 영역의 아무 프로젝트나 드래그하여 사이드바의 그룹 위에 놓기만 하면 됩니다.
- 프로젝트 필터링(Filter Projects): 특정 그룹 이름을 클릭하면 해당 그룹에 속한 프로젝트만 표시됩니다.
- 전체 보기(View All): 같은 그룹을 다시 클릭하면 선택이 해제되고 모든 프로젝트가 표시됩니다.
- 그룹 관리(Manage Groups): ("분류되지 않음(Uncategorized)" 제외) 그룹 위에 마우스를 올리면 이름 변경/삭제 옵션이 나타납니다.
그룹 관리 기능
- 시각적 피드백(Visual Feedback): 프로젝트를 드래그할 때 그룹 위에서 하이라이트됩니다.
- 성공 알림(Success Notifications): 프로젝트가 이동했을 때 확인 메시지가 표시됩니다.
- 스마트 기본값(Smart Defaults): 새 프로젝트는 '분류되지 않음' 상태로 시작하며 언제든지 정리할 수 있습니다.
- 그룹 배지(Group Badges): 필터링을 하지 않을 경우, 프로젝트 목록에 속한 그룹이 표시됩니다.
- 안전 삭제(Safe Deletion): 그룹을 삭제하면 해당 그룹의 모든 프로젝트가 '분류되지 않음'으로 되돌아갑니다.
💡 GPU 지원: 호스트 시스템에 NVIDIA GPU가 있는 경우, ML/AI 개발을 위해 모든 워크스페이스에서 자동으로 사용할 수 있습니다. 다음 명령어로 테스트해 보세요:
ls -la /dev/nvidia*
nvidia-smi
AI 도구 설정
워크스페이스에 진입한 후, 다음 명령어를 실행하여 시작할 수 있습니다:
info
update_ai_agents
update_ai_agents pi
📚 문서(Documentation)
자세한 정보는 저희의 종합 문서를 참고해 주세요:
🔧 배포 옵션 (Deployment Options)
🐳 관리 명령어 (Management Commands)
크론(cron), 작업 공간 파일, 새 호스트로 이동에 대한 내용은 백업 및 복원을 참조하세요.
🌐 포트 포워딩 및 애플리케이션 접근 (Port Forwarding & Application Access)
XaresAICoder는 원활한 애플리케이션 접근을 위해 **서브도메인 기반 라우팅(subdomain-based routing)**을 사용합니다:
- Flask/Python:
http://projectid-5000.localhost/
- React/Node.js:
http://projectid-3000.localhost/
- Spring Boot:
http://projectid-8080.localhost/
VS Code는 포트를 자동으로 감지하여 원클릭 브라우저 접근을 제공합니다.
🔐 보안 (Security)
- 선택적 비밀번호 보호(Optional Password Protection): 개별 작업 공간을 비밀번호로 안전하게 보호할 수 있습니다 (설정, 업데이트, 제거).
- 컨테이너 격리(Container Isolation): 각 작업 공간은 독립된 Docker 컨테이너에서 실행됩니다.
- 리소스 제한(Resource Limits): CPU, 메모리, PID 및 파일 디스크립터 제한을 통해 리소스 고갈을 방지합니다.
- 네트워크 격리(Network Isolation): 작업 공간들이 서로 접근할 수 없습니다.
- 보안 프록시 모드(Security Proxy Mode): 작업 공간의 인터넷 접속을 화이트리스트 도메인으로만 제한합니다.
- LLM 로깅 프록시 모드(LLM Logging Proxy Mode): 감사 및 규정 준수를 위해 모든 AI API 트래픽을 기록합니다.
