소개

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

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

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

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

이 접근 방식의 장점

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

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

사전 요구사항

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

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

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

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

Step 1: Claude Code 시작

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

claude

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

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

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

Step 2: Jupyter Notebook 설치

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

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

cd ~/workspace
git clone https://github.com/Harry24k/workspace-viewer.git
cd workspace-viewer
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를 실행하는 디렉토리와 일치해야 합니다. 이렇게 하면 workspace-viewer에서 보는 파일이 Claude Code가 작업하는 파일과 동일하게 유지됩니다.

Step 4: workspace-viewer 연결

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

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

Jupyter 확장으로 등록

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

cd workspace-viewer
jupyter serverextension enable --py jupyter_ext --sys-prefix

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

Step 5: Jupyter Notebook 시작

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

jupyter notebook

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

[I NotebookApp] Workspace Viewer extension loaded at /workspace-viewer
[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: workspace-viewer 사용

Jupyter가 실행 중이면 다음에서 workspace-viewer에 접근할 수 있습니다:

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

워크스페이스 탐색

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

  • 사이드바에서 폴더 구조 탐색
  • 파일을 클릭하면 구문 강조와 함께 내용 표시
  • 마크다운 파일은 전체 서식이 적용되어 렌더링
  • GitHub 리포지토리와 연결된 폴더는 빠른 접근을 위한 링크 아이콘 표시

터미널 관리

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

  • + 버튼으로 새 터미널 세션 생성
  • 여러 활성 터미널 간 전환
  • 터미널 이름을 더블클릭하여 이름 변경 (예: “프로젝트 A”, “디버그 세션”)
  • 더 이상 필요 없는 터미널 종료

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

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

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

claude

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

멀티 세션 워크플로우

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

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

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

요약

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

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

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

프로젝트 확인: [GitHub]