Runtime Setup

런타임 환경 구성 (Windows)

BADA Terminal과 Claude Code CLI를 정상 구동하기 위해 필요한 기본 런타임 환경을 설정합니다.

필수 런타임 종속성

소프트웨어	권장 버전	설치 유형	역할
Node.js	v20.x 또는 v22.x (LTS)	Installer (.msi) 또는 Binary (.zip)	애플리케이션 구동 및 PTY 브릿지 엔진
Git for Windows	v2.40.0 이상	Windows Installer (.exe)	작업 디렉토리 체크아웃 및 Worktree 격리 제어
Claude CLI	최신 공식 릴리스	글로벌 npm 모듈 (`@anthropic-ai/claude-code`)	PTY의 명령 처리를 맡는 AI 에이전트 브레인

환경 변수 (System Environment Variables)

BADA가 외부 바이너리를 올바르게 찾을 수 있도록 윈도우 환경 변수에 경로들을 마운트해야 합니다.

1. PATH 등록

제어판 > 시스템 및 보안 > 시스템 > 고급 시스템 설정 > 환경 변수 > 시스템 변수 > Path 에 아래 항목들이 포함되어야 합니다.

# Node.js 전역 모듈 경로
%APPDATA%\npm

# Git 바이너리 경로
C:\Program Files\Git\cmd

# Node.js 설치 경로 (기본 설정)
C:\Program Files\nodejs\

⚠️

PowerShell 권한 설정

BADA의 PTY 및 쉘 연동 스크립트가 PowerShell 세션에서 실행을 거부당하지 않도록 관리자 권한 콘솔에서 다음 명령어를 실행하여 실행 정책을 완화하십시오:
Set-ExecutionPolicy RemoteSigned -Scope LocalMachine

Development & Build

개발 및 빌드 환경 상세 설정

BADA Terminal 소스 코드를 편집하고 Electron 패키징 또는 C++ 네이티브 모듈 컴파일 환경을 구성합니다.

네이티브 C++ 바인딩을 위한 빌드 도구

BADA는 PTY 인터페이스를 위한 node-pty와 데이터베이스 핸들링을 위한 better-sqlite3 모듈을 사용합니다. 이 모듈들은 C++ 바인딩을 포함하므로 윈도우에서는 컴파일 환경이 필수적입니다.

1

Visual Studio Build Tools 설치

Visual Studio Build Tools 2022 이상 버전을 다운로드하고, 설치 시 반드시 "C++를 사용한 데스크톱 개발" 워크로드를 체크하여 C++ 컴파일러(MSVC) 및 MSBuild를 획득해야 합니다.

2

Python 설치 및 환경 변수 바인딩

node-gyp 컴파일에 사용되는 Python 3.10 또는 3.11을 설치합니다. 시스템 환경 변수에 PYTHON 키를 등록하고 설치된 python.exe의 절대경로를 값으로 바인딩합니다.

3

npm 글로벌 컴파일 셋팅

관리자 권한 콘솔에서 아래 명령을 통해 msvs 컴파일러 버전을 명시적으로 지정합니다.

npm config set msvs_version 2022

네이티브 모듈 및 Electron 리빌드 구동

개발 버전 구동 시, Node.js 기본 빌드 모듈을 Electron 런타임 아키텍처에 맞게 리빌드합니다.

# 패키지 설치
npm install

# electron-rebuild를 통한 C++ 바이너리 재생성
npm run rebuild

패키징 빌드

# NSIS 인스톨러 및 ZIP 파일 빌드
npx electron-builder --win --x64

Air-gap Packaging

에어갭(망분리) 오프라인 패키지 구성 가이드

인터넷 연결이 완전히 차단된 윈도우 서버 환경에 배포하기 위해 수집해야 할 파일 및 패키지 목록입니다.

오프라인 설치용 수집 패키지 목록

인터넷이 연결된 일반 PC에서 다음 바이너리 및 모듈들을 미리 다운로드하여 이동식 매체(USB 등)로 수집해야 합니다.

1. 인프라 실행 및 컴파일러 바이너리

Node.js LTS MSI Installer: node-v20.11.0-x64.msi
Git for Windows Installer: Git-2.43.0-64-bit.exe
Python Windows Installer: python-3.11.8-amd64.exe
VS Build Tools 2022 오프라인 레이아웃 패키지:
인터넷 컴퓨터에서 다음 명령어로 약 3~4GB 분량의 오프라인 미디어를 만듭니다.
```
vs_BuildTools.exe --layout C:\VSBuildToolsLayout --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --lang ko-KR
```

2. Claude Code CLI 글로벌 캐시 패키징

글로벌 설치 모듈을 오프라인 서버로 옮기기 위해 인터넷 컴퓨터에서 tarball 파일로 패키징합니다.

# 글로벌 캐싱 다운로드 및 패키징
npm pack @anthropic-ai/claude-code

생성된 anthropic-ai-claude-code-x.x.x.tgz 파일을 배포 매체에 수집합니다.

3. BADA 소스코드 및 Prebuilt 모듈 번들링

C++ 컴파일러 빌드가 막힐 경우를 방지하여, 인터넷 PC에서 C++ 네이티브 모듈 빌드가 완성된 node_modules를 ZIP 형태로 일괄 묶어 준비합니다.

# 윈도우 OS의 인터넷 PC에서 소스 다운로드 및 컴파일 완료 후 압축
npm install
npm run rebuild
tar -czf bada-node-modules.tar.gz node_modules/

Installation Workflow

에어갭 윈도우 서버 설치 및 실행 절차

오프라인 서버에 수집한 패키지를 정렬하고 환경을 최종 셋업하여 구동하는 로드맵입니다.

오프라인 설치 시나리오 1: BADA 전용 빌드 패키지 배포 (권장)

가장 단순하고 오류가 없는 방법으로, 개발 컴퓨터에서 완전히 컴파일 및 번들링된 배포판 설치 파일(BADA Terminal Setup X.X.X.exe) 또는 ZIP 포터블 번들을 망분리 서버로 직접 복사해 실행하는 것입니다.

1

배포판 복사 및 실행

C:\Users\jkb\Desktop\claude-cli-v2 등의 경로에 BADA Terminal Setup.exe 파일을 이동시키고 더블클릭하여 설치를 마칩니다.

2

Git portable / Git for Windows 설치

워크플로우 격리를 위해 서버 내부에서 Git 명령이 동작해야 합니다. Git-2.43.0-64-bit.exe를 실행하여 설치하고 cmd 경로를 PATH에 등록합니다.

오프라인 설치 시나리오 2: 서버 소스 컴파일 및 기동

서버 내부에서 자체 컴파일 및 핫 패치를 동반한 셋업을 원할 경우의 수동 복구 흐름입니다.

1

인프라 파일 순차 설치

1) Node.js MSI 실행
2) Git EXE 실행
3) Python AMD64 실행 및 Add python.exe to PATH 체크 필수!

2

C++ 빌드 도구 오프라인 구축 (VS Build Tools)

이동해 온 레이아웃 디렉토리에서 오프라인 모드로 실행합니다.

vs_BuildTools.exe --nocache --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended

3

Claude Code CLI 오프라인 설치

수집한 tgz 파일을 글로벌 모듈 경로로 설치합니다.

npm install -g .\anthropic-ai-claude-code-x.x.x.tgz --offline

4

BADA 소스코드 복사 및 모듈 해제

BADA 소스 디렉토리를 복사하고, 미리 압축해 온 bada-node-modules.tar.gz를 소스 루트에 압축 해제합니다. 또는 직접 컴파일을 수행합니다.

# 압축 해제
tar -xzf bada-node-modules.tar.gz

# 또는 오프라인 컴파일 실행
npm install --offline
npm run rebuild