Claude Notebook: Jupyter Notebook를 활용한 셀프 호스팅 Claude Code Remote 대안

소개
- 이 접근 방식의 장점
주요 기능
사전 요구사항
Step 1: Claude Code 시작
Step 2: Jupyter Notebook 설치
Step 3: Jupyter Notebook 설정
- 비밀번호 설정
- 외부 접근 설정
Step 4: Claude Notebook 연결
- Jupyter 확장으로 등록
Step 5: Jupyter Notebook 시작
Step 6: Claude Notebook 사용
- 워크스페이스 탐색
- 터미널 관리
Step 7: 터미널에서 Claude Code 실행
- 멀티 세션 워크플로우
요약

소개

Claude Code는 Anthropic의 CLI 기반 에이전트 코딩 도구입니다. Anthropic은 원격으로 Claude Code에 접근할 수 있는 관리형 솔루션인 Claude Code Remote를 제공하지만, 이는 일반 브라우저가 아닌 전용 앱을 통해 작동합니다. 제 경험상, 원격 환경이 여전히 실행 중임에도 연결이 끊기는 경우가 있어 긴 코딩 세션에서 불편할 수 있습니다.

일반적인 해결 방법은 tmux 등의 터미널 멀티플렉서를 사용하여 세션을 유지하는 것입니다. 이 방법이 작동하기는 하지만, 특히 원격 접근을 위한 설정이 번거로울 수 있습니다.

여기서 Jupyter Notebook이 등장합니다. Jupyter는 기본적으로 웹 접근 가능한 터미널을 제공하므로, 추가 인프라 없이 브라우저를 통해 Claude Code를 실행할 수 있습니다. 하지만 기본 Jupyter 인터페이스는 여러 터미널 세션을 관리하거나 워크스페이스 파일을 탐색하는 데 최적화되어 있지 않습니다. 프로젝트를 쉽게 탐색하고 터미널을 나란히 관리할 수 있는 커스터마이즈 가능한 인터페이스가 필요했습니다.

그래서 Claude Notebook을 만들었습니다. Jupyter Notebook 위에 Notion 스타일의 파일 브라우저와 터미널 관리 UI를 추가하는 Jupyter 확장입니다. Jupyter Notebook과 Claude Notebook을 결합하면, 어디서든 브라우저를 통해 워크스페이스와 여러 Claude Code 세션을 관리할 수 있는 인터페이스를 얻을 수 있습니다.

Claude Notebook의 Notion 스타일 파일 브라우저 — 폴더 아이콘, 트리 탐색, 파일 미리보기로 워크스페이스를 탐색합니다.

멀티 세션 사이드바, xterm.js 터미널, Claude Code 상호작용을 위한 iMessage 스타일 채팅 뷰가 포함된 터미널 관리자.

이 접근 방식의 장점

셀프 호스팅: 자신의 머신을 소유하고, 데이터는 자신의 머신에 남습니다.
안정적인 연결: Jupyter 터미널은 서버에서 유지됩니다 — Claude Code Remote처럼 연결이 끊기지 않습니다.
멀티 세션: 여러 터미널을 열고, 각각 별도의 Claude Code 인스턴스를 실행하여 다른 작업을 수행할 수 있습니다.
워크스페이스 개요: Claude Notebook이 Jupyter 위에 Notion 스타일의 파일 브라우저를 추가하여 터미널 세션과 함께 프로젝트 파일을 탐색하고 읽을 수 있습니다.
추가 인프라 불필요: Claude가 설치된 PC만 있으면 됩니다.

팁: 전체 설정 과정을 Claude Code CLI 자체를 사용하여 완료하는 것을 권장합니다. Claude가 패키지 설치, 설정 파일 편집, 문제 해결을 모두 터미널에서 도와줄 수 있습니다. 아래 단계는 이 워크플로우를 염두에 두고 설계되었습니다.

주요 기능

Claude Notebook은 워크스페이스와 터미널을 관리하기 위한 종합적인 기능을 제공합니다:

파일 브라우저: 구문 강조, 마크다운 렌더링, 이미지 미리보기, 인라인 편집이 가능한 Notion 스타일 인터페이스
CSV 뷰어: 컬럼 정렬, 필터링, 컬럼 크기 조절, 행 색상 지정, 셀 복사가 가능한 인터랙티브 테이블
터미널 관리자: 여러 영구 터미널 세션 생성, 이름 변경, 설정, 전환
채팅 모드: 터미널 출력을 ANSI 컬러 지원 대화 버블로 렌더링하는 iMessage 스타일 채팅 뷰
파일 업로드: 파일/폴더 드래그 앤 드롭 업로드 — 파일명 충돌 자동 처리
서버 설정: 터미널 이름, 시작 명령, 채팅 모드 설정, CSV 설정이 서버에 영구 저장
모바일 지원: 터치 최적화 UI, 접이식 사이드바, 터미널 복사 지원의 완전 반응형 디자인

모바일 반응형 디자인 — 파일 브라우저와 터미널 관리자가 작은 화면에 자연스럽게 적응합니다.

사전 요구사항

이 가이드는 다음이 설치된 머신(로컬 PC, 클라우드 VM 등)을 전제로 합니다:

Claude Code CLI 설치 및 인증 완료 (claude 명령어 사용 가능)
Python 3 설치
Tornado 설치 (pip install tornado) — Claude Notebook의 서버 확장에 필요
네트워크 접근 가능 (로컬 네트워크 또는 포트 포워딩)

Claude Code가 아직 설치되지 않은 경우, 공식 설치 가이드를 참조하세요.

⚠️ 보안 경고: 시작하기 전에 주의하세요 — Jupyter Notebook이 인터넷에 노출되면 전체 Claude Code 환경도 접근 가능해집니다. Jupyter에 접근한 누구든 터미널을 열고 Claude Code 세션에 접근하는 것을 포함하여 머신에서 명령을 실행할 수 있습니다. 항상 강력한 비밀번호를 사용하고, 프로덕션 환경에서는 HTTPS를 활성화하며, 방화벽 규칙이나 VPN으로 접근을 제한하는 것을 고려하세요. 자세한 내용은 Jupyter 보안 문서를 참조하세요.

Step 1: Claude Code 시작

머신에서 터미널을 열고 Claude Code를 시작합니다:

claude

여기서부터 Claude에게 나머지 단계 — Jupyter 설치, 설정, Claude Notebook 셋업 — 을 도와달라고 요청할 수 있습니다. 예를 들어, Claude에게 이렇게 말할 수 있습니다:

“Jupyter Notebook 6을 설치하고 8888 포트에서 원격 접근이 가능하도록 설정해줘.”

Claude가 패키지 설치와 설정을 처리해 줄 것입니다. 물론, 아래의 수동 단계를 따를 수도 있습니다.

Step 2: Jupyter Notebook 설치

Jupyter Notebook v6 (클래식 노트북 서버)를 사용합니다. 이는 내장 터미널과 잘 확립된 서버 확장 시스템을 제공합니다. 개인적으로 v6을 가장 자주 사용하며, v7은 아직 Claude Notebook과 충분히 테스트되지 않았으므로 이 가이드는 v6을 기반으로 합니다.

Claude Notebook은 패키지 버전을 명시적으로 관리하기 위한 requirements 파일을 제공합니다. 모든 의존성을 한번에 설치할 수 있습니다:

cd ~/workspace
git clone https://github.com/Harry24k/claude-notebook.git
cd claude-notebook
pip install -r requirements.txt

또는 Jupyter를 수동으로 설치하려면:

pip install notebook==6.*

설치를 확인합니다:

jupyter notebook --version

6.x.x로 시작하는 버전이 표시되어야 합니다.

Step 3: Jupyter Notebook 설정

Jupyter 설정 파일이 없다면 생성합니다:

jupyter notebook --generate-config

이렇게 하면 ~/.jupyter/jupyter_notebook_config.py가 생성됩니다. 파일을 열고 다음 옵션을 설정합니다.

비밀번호 설정

먼저 해시된 비밀번호를 생성합니다:

jupyter notebook password

프롬프트가 나타나면 원하는 비밀번호를 입력합니다. 해시가 ~/.jupyter/jupyter_server_config.json (또는 jupyter_notebook_config.json)에 저장됩니다.

외부 접근 설정

~/.jupyter/jupyter_notebook_config.py를 편집합니다:

# 모든 IP에서 연결 허용 (원격 접근에 필요)
c.NotebookApp.ip = '0.0.0.0'

# 포트 설정 (기본값 8888)
c.NotebookApp.port = 8888

# 워크스페이스를 루트 디렉토리로 설정
c.NotebookApp.notebook_dir = '/path/to/your/workspace'

# 자동 브라우저 열기 비활성화 (헤드리스 서버에 유용)
c.NotebookApp.open_browser = False

/path/to/your/workspace를 실제 워크스페이스 경로(예: ~/workspace)로 변경하세요.

중요: Jupyter의 notebook_dir은 Claude Code를 실행하는 디렉토리와 일치해야 합니다. 이렇게 하면 Claude Notebook에서 보는 파일이 Claude Code가 작업하는 파일과 동일하게 유지됩니다.

Step 4: Claude Notebook 연결

Step 2에서 이미 Claude Notebook을 클론했다면 해당 디렉토리로 이동합니다. 아직이라면 지금 클론합니다:

cd ~/workspace
git clone https://github.com/Harry24k/claude-notebook.git

Jupyter 확장으로 등록

claude-notebook 디렉토리에서 서버 확장을 등록합니다:

cd claude-notebook
jupyter serverextension enable --py jupyter_ext --sys-prefix

이렇게 하면 노트북 서버가 시작될 때 Claude Notebook의 핸들러를 로드하도록 Jupyter에 지시합니다. 추가 설정은 필요 없습니다 — Claude Notebook이 Jupyter의 notebook_dir을 워크스페이스 경로로 자동 사용합니다.

Step 5: Jupyter Notebook 시작

노트북 서버를 실행합니다:

jupyter notebook

다음과 같은 출력이 나타납니다:

[I NotebookApp] Claude Notebook extension loaded at /claude-notebook
[I NotebookApp] Serving notebooks from local directory: /path/to/your/workspace
[I NotebookApp] Jupyter Notebook is running at:
[I NotebookApp] http://0.0.0.0:8888/

이제 네트워크의 모든 장치에서 브라우저를 열고 다음으로 이동합니다:

http://<your-machine-ip>:8888

Step 3에서 설정한 비밀번호로 로그인합니다.

Step 6: Claude Notebook 사용

Jupyter가 실행 중이면 다음에서 Claude Notebook에 접근할 수 있습니다:

http://<your-machine-ip>:8888/claude-notebook

워크스페이스 탐색

메인 페이지는 워크스페이스를 위한 Notion 스타일의 파일 브라우저를 제공합니다:

사이드바에서 폴더 구조 탐색
파일을 클릭하면 구문 강조와 함께 내용 표시
마크다운 파일은 전체 서식이 적용되어 렌더링
CSV 파일은 정렬, 필터링, 행 색상 지정이 가능한 인터랙티브 테이블 뷰어로 표시
텍스트 파일을 인라인으로 편집하고 워크스페이스에 저장
파일 및 폴더를 드래그 앤 드롭으로 업로드
GitHub 리포지토리와 연결된 폴더는 빠른 접근을 위한 링크 아이콘 표시

터미널 관리

사이드바 헤더의 터미널 아이콘을 클릭하면 터미널 관리 페이지가 열립니다:

+ 버튼으로 새 터미널 세션 생성 — 이름, 시작 명령, 채팅 모드 설정
여러 활성 터미널 간 전환
설정 모달로 터미널 이름 변경 및 구성
채팅 모드: Claude Code 출력을 대화 버블로 렌더링하는 iMessage 스타일 채팅 뷰 토글
파일 업로드: 터미널 명령에 파일 첨부
더 이상 필요 없는 터미널 종료

각 터미널은 Jupyter의 내장 터미널 인프라를 기반으로 하는 전체 셸 세션입니다.

Step 7: 터미널에서 Claude Code 실행

여기서 모든 설정이 합쳐집니다. 모든 터미널 세션에서 간단히 실행합니다:

claude

Claude Code가 인터랙티브 모드로 시작되며, 워크스페이스에 대한 전체 접근 권한을 가집니다. 이제 로컬에서와 동일하게 Claude Code를 사용할 수 있습니다 — 파일 읽기, 코드 작성, 명령 실행 — 모두 브라우저를 통해.

멀티 세션 워크플로우

이 설정의 진정한 강점은 여러 Claude Code 인스턴스를 동시에 실행할 수 있다는 것입니다:

터미널 1을 만들고 “프론트엔드”로 이름 변경 — claude를 실행하고 UI 작업
터미널 2를 만들고 “백엔드”로 이름 변경 — claude를 실행하고 API 작업
터미널 3을 만들고 “테스트”로 이름 변경 — claude를 실행하고 테스트 작성

각 터미널은 독립적인 Claude Code 세션을 유지합니다. 자유롭게 전환할 수 있으며, Claude Notebook의 파일 브라우저로 코드베이스 전체의 변경 사항을 실시간으로 모니터링할 수 있습니다.

요약

구성요소	역할
Claude Code CLI	AI 코딩 에이전트 — 설정 어시스턴트 역할도 겸함
Jupyter Notebook	인증, 터미널, 확장 시스템을 제공하는 웹 서버
Claude Notebook	파일 브라우저와 터미널 관리 UI를 추가하는 Jupyter 확장

이 세 가지 구성요소를 결합하면, 연결 안정성 문제 없이 Claude Code Remote의 실용적인 대안으로 작동하는 셀프 호스팅 브라우저 접근 가능 코딩 환경을 얻을 수 있습니다. Claude가 설치된 단일 머신 외에 추가 인프라가 필요 없으며, Claude Notebook은 Jupyter에서 직접 워크스페이스 경로를 읽으므로 추가 설정이 필요 없습니다.

Claude Notebook에 포함된 requirements 파일을 사용하여 패키지 버전을 명시적으로 관리하고, Jupyter를 외부 네트워크에 노출할 때 보안에 세심한 주의를 기울이는 것을 권장합니다.

프로젝트 확인: [GitHub]