#📝️/✒️

Synology NAS에 브라우저 기반 VS Code + Claude CLI 구축하기

NAS에 Docker로 Web VS Code(code-server)를 설치하고, Claude Code CLI를 영구 설치하여 브라우저만 열면 AI 코딩 환경을 쓸 수 있게 만들었습니다. 태블릿, 노트북, 심지어 다른 사람 PC에서도 브라우저 하나면 됩니다.

완성된 모습

브라우저 (어디서든)
    → https://code.your-domain.com
    → VS Code 에디터 + 터미널
    → 터미널에서 claude 입력
    → AI 코딩 시작 (파일 수정이 에디터에 실시간 반영)

핵심은 VS Code 에디터 + Claude CLI 터미널이 같은 화면에서 작동한다는 것입니다. Claude가 수정한 파일이 에디터에 바로 반영되고, diff도 즉시 확인할 수 있습니다.

시스템 구성

┌──────────────────────────────────────────────────┐
│  Synology NAS (Docker)                           │
│                                                  │
│  ┌──────────────────────┐                        │
│  │  code-server         │ ← 브라우저 접속 (8080) │
│  │  (Web VS Code)       │                        │
│  │  + Claude CLI 내장   │                        │
│  └────────┬─────────────┘                        │
│           │ Volume Mount (공유)                   │
│  ┌────────┴─────────────┐                        │
│  │  claude-code         │ ← Discord Bot 연동     │
│  │  (API Server)        │                        │
│  └──────────────────────┘                        │
│           │                                      │
│     /workspace/                                  │
│     ├── research/   ← 연구 프로젝트              │
│     ├── obsidian/   ← 노트                       │
│     └── saas/       ← 웹 프로젝트                │
└──────────────────────────────────────────────────┘

두 컨테이너가 같은 호스트 폴더를 마운트하므로, 어느 쪽에서 수정해도 양쪽 모두 반영됩니다.

Step 1: 기본 code-server 설치

폴더 생성

sudo mkdir -p /volume1/docker/vscode

docker-compose.yml

version: "3.8"

services:
  code-server:
    image: codercom/code-server:latest
    container_name: code-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - /volume1/docker/vscode:/home/coder
    command:
      - code-server
      - --bind-addr
      - 0.0.0.0:8080
      - --auth
      - none
      - --proxy-domain
      - code.your-domain.com

cd /volume1/docker/vscode
sudo docker compose up -d

이 상태에서 http://NAS_IP:8080으로 접속하면 Web VS Code가 열립니다. 하지만 아직 Claude CLI가 없습니다.

Step 2: Claude CLI 영구 설치 (Dockerfile)

공식 이미지를 그대로 쓰면 컨테이너 재생성 시 npm install한 패키지가 모두 사라집니다. Dockerfile을 만들어 Claude CLI를 이미지에 포함시킵니다.

Dockerfile

FROM codercom/code-server:latest

# 필요 도구 설치 (root 권한)
USER root
RUN apt-get update && apt-get install -y \
    jq \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Claude CLI 설치
RUN npm install -g @anthropic-ai/claude-code

# 기본 사용자로 복귀
USER coder

docker-compose.yml 수정

image 대신 build를 사용하도록 변경하고, 작업 폴더 마운트를 추가합니다:

version: "3.8"

services:
  code-server:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: code-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - /volume1/docker/vscode:/home/coder
      # 작업 폴더 공유 (claude-code 컨테이너와 동일)
      - /path/to/research:/workspace/research
      - /path/to/obsidian:/workspace/obsidian
      - /path/to/saas:/workspace/saas
    command:
      - code-server
      - --bind-addr
      - 0.0.0.0:8080
      - --auth
      - none
      - --proxy-domain
      - code.your-domain.com

빌드 및 실행

cd /volume1/docker/vscode
sudo docker compose build
sudo docker compose up -d

설치 확인

sudo docker exec code-server claude --version

Step 3: 작업 폴더 공유 구조

이미 Discord Bot + Claude Code 시스템이 있다면, 같은 호스트 경로를 마운트하여 파일을 공유합니다.

호스트 (NAS)              claude-code         code-server
──────────────────────────────────────────────────────────
/path/to/research    →  /workspace/research  → /workspace/research
/path/to/obsidian    →  /workspace/obsidian  → /workspace/obsidian
/path/to/saas        →  /workspace/saas      → /workspace/saas

이 구조의 장점:

• Discord에서 /claude task:...로 수정한 파일을 Web VS Code에서 즉시 확인
• Web VS Code에서 수정한 파일에 대해 Claude CLI로 즉시 작업
• 어디서 수정하든 동일한 파일

Step 4: 역방향 프록시 설정 (HTTPS 접속)

Synology DSM의 역방향 프록시를 설정하면 HTTPS로 안전하게 접속할 수 있습니다.

Synology DSM 설정

1. 제어판 → 로그인 포털 → 고급 → 역방향 프록시
2. 새 규칙 생성:

3. 사용자 지정 헤더 탭에서 WebSocket 헤더 추가:
   • Upgrade: $http_upgrade
   • Connection: $connection_upgrade

WebSocket 헤더가 없으면 터미널이 제대로 동작하지 않습니다.

DNS 설정

도메인 DNS에서 code.your-domain.com을 NAS의 외부 IP (또는 DDNS)로 연결합니다.

Step 5: Claude CLI 사용법

대화형 모드

cd /workspace/saas
claude

Claude가 시작되면 자연어로 대화하며 코딩합니다. 수정된 파일이 VS Code 에디터에 실시간 반영됩니다.

Plan Mode (계획 → 승인 → 실행)

# 방법 1: Shift+Tab 두 번
# 방법 2: /plan 명령어

Plan Mode에서 Claude는 읽기 전용으로 코드베이스를 분석하고 계획서를 작성합니다. 사용자가 승인하면 그때 실행합니다. 대규모 리팩토링이나 새 기능 추가 시 유용합니다.

단발성 실행 (-p 모드)

claude -p "package.json 분석해줘" --max-turns 3

질문 하나에 답변 하나만 받고 끝나는 모드. 스크립트나 자동화에 적합합니다.

Step 6: Discord 알림 연동 (Hooks)

Web VS Code에서 Claude를 돌려놓고 다른 일을 하다가, 작업 완료나 승인 요청이 필요할 때 Discord로 알림을 받을 수 있습니다.

Hook 설정

code-server 컨테이너 내부의 Claude 설정에 hooks를 추가합니다:

// /home/coder/.claude/settings.json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://YOUR_BOT_HOST:3001/hook-notify -H 'Content-Type: application/json' -d '{\"type\":\"permission\",\"message\":\"승인이 필요합니다\"}'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST http://YOUR_BOT_HOST:3001/hook-notify -H 'Content-Type: application/json' -d '{\"type\":\"complete\",\"message\":\"작업 완료\"}'"
          }
        ]
      }
    ]
  }
}

알림 흐름

VS Code 터미널에서 Claude 실행 중...

→ 작업 완료 (Stop 이벤트)
    → Hook: curl → Discord Bot
    → Discord 채널에 "✅ 작업 완료" 알림

→ 승인 필요 (Notification 이벤트)
    → Hook: curl → Discord Bot
    → Discord 채널에 "⚠️ 승인이 필요합니다" 알림

Claude에게 큰 작업을 시키고 다른 일을 하다가, 스마트폰 Discord 알림으로 결과를 확인하면 됩니다.

데이터 영구 보존 정리

/home/coder가 호스트에 볼륨 마운트되어 있으므로 Claude 설정, 세션 데이터, VS Code 확장 프로그램 설정 모두 컨테이너 재생성 후에도 유지됩니다.

Claude CLI 업데이트

새 버전이 나오면 이미지를 다시 빌드합니다:

cd /volume1/docker/vscode
sudo docker compose build --no-cache
sudo docker compose up -d

--no-cache 옵션으로 처음부터 다시 빌드하여 최신 Claude CLI를 설치합니다. /home/coder 볼륨의 설정과 세션은 그대로 유지됩니다.

트러블슈팅

Claude CLI가 없다고 나올 때

# 이미지에 포함되었는지 확인
sudo docker exec code-server which claude
sudo docker exec code-server claude --version

# 없으면 재빌드
cd /volume1/docker/vscode
sudo docker compose build
sudo docker compose up -d

/workspace가 안 보일 때

sudo docker exec code-server ls /workspace/

research, obsidian, saas 등이 보여야 합니다. 안 보이면 docker-compose.yml의 volumes 확인 후 docker compose up -d로 재시작합니다.

터미널이 HTTPS에서 동작하지 않을 때

역방향 프록시에 WebSocket 헤더가 설정되었는지 확인합니다. code-server 터미널은 WebSocket을 사용하므로, Upgrade와 Connection 헤더가 없으면 터미널 연결이 끊어집니다.

전체 활용 시나리오

시나리오 1: VS Code에서 Plan Mode 코딩

1. 브라우저에서 code.your-domain.com 접속
2. 터미널에서 cd /workspace/saas && claude
3. Shift+Tab 두 번 → Plan Mode
4. "인증 시스템 리팩토링해줘" 입력
5. Claude가 계획서 작성 → 검토 → 승인
6. Claude가 코드 수정 → VS Code에서 diff 확인
7. 완료 시 Discord에 알림 (Hook)

시나리오 2: 두 환경 동시 사용

VS Code: /workspace/saas에서 코딩 중
Discord: /claude task:obsidian 논문 정리해줘
→ 같은 파일시스템, 서로 독립적으로 작업

시나리오 3: 태블릿에서 가벼운 코딩

iPad 브라우저 → code.your-domain.com
→ 키보드 연결하면 데스크탑과 동일한 환경
→ Claude CLI도 그대로 사용 가능

마무리

이 시스템의 장점:

• 브라우저만 있으면 끝: 어떤 기기든 브라우저가 있으면 AI 코딩 환경 접속
• 에디터 + AI 통합: Claude가 수정한 파일이 VS Code에 즉시 반영, diff 확인 가능
• 파일 공유: Discord Bot과 같은 workspace를 공유하여 어디서든 작업 연속성 유지
• 영구 설치: Dockerfile로 Claude CLI가 이미지에 포함, 재시작해도 유지
• Discord 알림: 작업 완료/승인 요청을 모바일에서 즉시 확인

NAS 하나에 브라우저 기반 VS Code + AI 코딩 에이전트를 구축한 사례였습니다. code-server(Web VS Code) + @anthropic-ai/claude-code(Claude CLI) 조합으로, 로컬 설치 없이도 어디서든 AI 코딩이 가능합니다.