Workroom

ChatGPT에서 대화하고, 선택한 로컬 프로젝트의 파일·작업·실행 결과를 관리하는 데스크톱 앱입니다. MCP 도구 서버를 제공하며 모델 API나 Codex CLI를 직접 실행하지 않습니다.

현재 소스 버전은 0.3.0-rc.3이며 macOS Apple Silicon과 Windows x64 프리뷰 빌드 경로를 제공합니다. 프리뷰는 macOS Developer ID·Apple 공증 또는 Windows Authenticode 서명을 받은 정식 배포본이 아닙니다. 토큰 추정 기능은 제거했습니다.

시작하기

소스 실행에는 Node.js 22.12 이상이 필요합니다.

npm ci
# Electron 설치 스크립트가 npm 정책에 의해 차단된 경우에만 실행합니다.
node node_modules/electron/install.js
npm run verify
npm start

개발 UI는 npm run dev, 실제 Electron UI/MCP 검증은 npm run smoke입니다. macOS DMG·ZIP은 npm run package:mac, Windows x64 NSIS 설치 프로그램·ZIP은 Windows에서 npm run package:win으로 생성합니다. macOS 모의 터널 UI 검증은 npm run smoke:tunnel입니다. 배포 절차를 먼저 확인하세요.

Related MCP server: Secure Local Workspace MCP

기본 작업 흐름

프로젝트 폴더를 연결하면 읽기 전용이며 접근 승인된 폴더가 없습니다. 작업 보드에서 폴더를 승인한 뒤 그 안의 파일을 읽거나 변경할 수 있습니다. /는 프로젝트 전체입니다. 변경에는 별도의 변경 허용 설정이 필요합니다.

macOS 자동 명령은 폴더 격리로 승인 폴더 밖 파일 읽기·쓰기를 제한합니다. Windows에서는 같은 격리를 제공하지 않아 자동 명령을 접수하지 않습니다. 건별 승인한 명령은 OS 사용자 권한으로 실행되며 프로젝트 밖 파일과 네트워크에도 접근할 수 있습니다. Windows에서는 PowerShell을 사용합니다. 재시작하면 변경 권한은 읽기 전용으로, 자동승인 모드는 전부 승인으로 돌아갑니다. 기존 all·edits 설정도 전부 승인으로 이전됩니다.

실행 기록에서 승인 대기(pending), 실행 대기(queued), 진행 중(running), 완료/실패/취소를 구분합니다. 자동 실행되는 요청은 최대 15초까지 결과를 기다려 한 번의 호출로 최종 상태를 반환하고, 승인 대기 요청은 즉시 반환합니다. 응답이 done일 때만 완료입니다. 그 밖의 상태면 ChatGPT가 job_get으로 실제 결과를 확인한 다음 task_update로 사실과 다음 단계를 저장해야 합니다.

일시 정지·권한 취소는 대기 요청을 취소하고 실행 중인 명령을 중지합니다. 이미 발생한 변경을 자동으로 되돌리지는 않습니다. 완료 기록 정리는 완료 요청과 활동 기록을 정리하되 중복 실행 방지용 해시는 유지합니다. 연결 해제는 앱 내 연결·작업 정보를 지우며 실제 프로젝트 폴더는 삭제하지 않습니다.

연결 방식

로컬 MCP 호스트

로컬 MCP를 지원하는 호스트에는 Workroom의 연결 주소 또는 생성된 STDIO 메타데이터를 등록합니다. 지원 메뉴와 방식은 사용하는 호스트·계정에 따라 다릅니다. STDIO 브리지는 앱에 포함된 Electron의 Node 실행 모드를 사용하며 모델을 실행하지 않습니다. 앱은 실행 중이어야 합니다.

로컬 연결 주소에는 접근 비밀값이 들어 있으므로 공개하거나 로그에 남기지 마세요. 앱을 다시 시작하면 비밀값이 바뀝니다. STDIO 브리지는 새 연결 파일을 읽고, HTTP 주소를 직접 등록한 호스트는 새 주소가 필요할 수 있습니다.

일반 ChatGPT의 비공개 터널 연결

앱의 ChatGPT 연결 화면에서 계정·워크스페이스에 제공되는 공식 연결 경로를 확인합니다. OpenAI Platform에서 사용할 워크스페이스와 연결된 터널을 만들고, 해당 터널을 사용할 권한이 있는 런타임 API 키를 준비합니다. Admin API 키나 다른 사람의 계정·키를 공유하지 않습니다.

tunnel-client를 설치한 뒤 설치 다시 확인을 누릅니다. macOS에서는 /opt/homebrew/bin/tunnel-client와 /usr/local/bin/tunnel-client를 확인합니다. Windows에서는 공식 배포의 tunnel-client.exe를 %APPDATA%\Workroom\bin\tunnel-client.exe에 둡니다. 터널 ID와 런타임 키를 입력하고 연결 상태를 확인한 다음, ChatGPT의 플러그인 연결 화면에서 Tunnel 방식과 터널 ID로 등록합니다. 127.0.0.1 주소나 API 키를 ChatGPT 등록 필드에 넣는 방식과 혼동하지 마세요.

런타임 키는 자식 프로세스 환경 변수로 전달하며 앱 자체 상태·작업 기록·원본 로그에 저장하지 않습니다. 입력란은 비우고 터널 ID만 보존합니다. 중지·재시작 후에는 키를 다시 입력해야 합니다. 로컬 서버 준비, 터널 준비, ChatGPT 플러그인 등록 성공은 서로 다른 상태입니다. 실제 계정에서 도구 호출까지 확인해야 연결 검증이 끝납니다.

계정별 개발자 모드와 메뉴는 달라질 수 있습니다. 상세한 현재 절차는 공식 플러그인 연결 문서와 Secure MCP Tunnel 안내를 확인하세요. 비공개 터널 연결은 공개 플러그인 제출용 배포 방식이 아닙니다.

제공하는 MCP 도구

file_propose·file_patch의 expectedHash는 현재 리비전입니다. 직전 읽기의 hash 또는 같은 파일에 마지막으로 완료된 변경의 resultHash를 사용합니다. 새 파일은 file_propose에 null을 사용하고 부모 폴더가 존재해야 합니다. file_patch의 각 oldText는 파일에서 정확히 한 번만 나와야 하고, 수정끼리 겹치면 안 되며, 모두 같은 리비전을 기준으로 합니다. 같은 requestId의 동일 요청은 재실행하지 않습니다. 서로 다른 요청에는 새 UUID를 사용하세요. 완료 원문을 정리해도 요청 해시·상태가 남습니다. 이전 버전의 원문 없는 요청은 동일성을 확인할 수 없어 자동 재시도를 거부할 수 있습니다.

보안과 데이터

파일 도구는 승인 루트, 상대 경로, 일반 단일 링크 파일만 처리합니다. 대표적인 자격증명 경로, .env*, 비밀키 파일, 특수 파일, 링크와 내부 임시 파일을 차단합니다. 이 파일 경계는 명령 실행의 OS 권한을 제한하지 않으며, 평범한 소스 파일의 비밀정보를 자동으로 모두 찾아내는 기능도 아닙니다.

MCP 서버는 loopback에만 바인딩하고 시작마다 새 비밀값을 사용합니다. 서버 요청 크기·시간·연결 수를 제한하고 최종 보안 헤더를 설정합니다. UI는 별도 프로토콜과 CSP, 샌드박스, 메인 프레임 IPC 검증을 사용합니다.

데이터는 macOS ~/Library/Application Support/Workroom, Windows %APPDATA%\Workroom에 저장합니다. macOS에서는 소유자 전용 파일 권한을 설정하고 Windows에서는 사용자 프로필 ACL을 상속합니다. 별도 암호화는 없습니다. 선택한 파일·작업·출력은 MCP 요청에 응답하면서 연결한 호스트로 전송될 수 있습니다. 로컬 저장과 외부 전송을 혼동하지 마세요.

프로젝트 100개, 작업 2,000개, 표시 요청 200개, 활동 기록 200개, 전체 상태 파일 32MiB로 제한합니다. 중복 실행 방지 기록은 10,000개까지 보관하고, 가득 차면 실행 기록에 없고 하루 이상 지난 가장 오래된 종료 기록부터 정리합니다. 명령은 120초, 총 출력 2MiB, 보관 출력 32,000자까지이며 전체 동시 실행 2개·프로젝트별 직렬 실행입니다. 앱이 로케일 없이 실행된 경우 macOS에서는 명령에 UTF-8 문자 로케일(LC_CTYPE=en_US.UTF-8)을 지정합니다. 대화형 입력과 영구 백그라운드 서버 실행 용도가 아닙니다.

자세한 범위와 한계는 보안 모델, 개인정보 안내, 변경 기록을 확인하세요. ChatGPT 화면·쿠키·로그인 세션·전체 대화 기록을 자동 수집하거나 모델의 제한·거절을 우회하는 기능은 없습니다.

배포 후보와 실제 검증

npm run verify는 타입검사·테스트·빌드입니다. npm run package:mac과 Windows에서의 npm run package:win은 UI 검사와 후보 패키지 검증을 묶어 실행합니다. 결과는 artifacts/release-audit/에 기록합니다. 현재 실행 중인 앱이 소스 수정만으로 자동 교체되지는 않습니다.

공개 배포용 npm run release:mac은 Developer ID 서명·공증 설정이 없으면 중단합니다. 준비된 스크립트와 실제 서명·공증·공개 게시 완료는 구분해야 합니다. 앱을 자동 게시하지 않습니다. 전체 절차와 남은 배포 요건은 docs/release.md, 실제 검사 기록은 docs/verification.md에 있습니다.