clt — 단일 명령으로 Harvard FASRC 클러스터에서 COMSOL 작업 실행

Mac에서 한 줄로 클러스터에 COMSOL 배치 작업을 실행합니다:

cluster file3.mph

(Touch ID 프롬프트 →) Windows 머신에서 file3.mph를 가져와 FASRC에 비밀번호 + 자동 생성된 2FA 코드로 로그인하고, 파일을 업로드하고, 비동기 Slurm 작업을 제출한 후 작업 ID를 반환합니다. 나중에:

cluster status          # queue overview
cluster logs            # tail the COMSOL batch log of the latest job
cluster fetch           # download out.mph + batch.log when it's done
cluster shell           # drop into an interactive shell (no re-login)
cluster code            # print the current 2FA code, e.g. for a manual login

모든 것은 단일 종속성 없는 Node 스크립트(cluster.js)와 macOS 내장 도구(ssh, scp, expect, security(Keychain))로 구성됩니다. npm 패키지가 없습니다.

작동 방식

Mac (cluster.js)
 ├─ Touch ID gate            (optional tiny Swift helper, compiled once)
 ├─ Keychain                 → FASRC password + TOTP seed
 ├─ TOTP in Node crypto      → the same 6-digit codes as the OpenAuth Java app
 ├─ ssh ControlMaster        → authenticate ONCE, reuse the session ~8h,
 │                             so scp/ssh/sbatch below run with zero prompts
 ├─ scp  winbox → Mac        (over an AnyDesk TCP tunnel or LAN, key auth)
 ├─ scp  Mac → cluster       (over the shared session)
 └─ ssh  sbatch              → COMSOL batch job runs asynchronously on Slurm

핵심은 FASRC "Java 2FA 앱"(OpenAuth/JAuth)이 일반 TOTP(Google Authenticator와 동일한 알고리즘)라는 점입니다. base32 시드만 있으면 약 15줄의 Node crypto로 유효한 코드를 생성하고, expect가 첫 로그인 시 ssh 프롬프트에 비밀번호와 코드를 입력합니다. ControlMaster가 해당 세션을 유지하여 이후에는 프롬프트가 나타나지 않습니다.

일회성 설정

0. 요구 사항

• Node ≥ 18이 설치된 macOS (brew install node 또는 nodejs.org)

• OpenAuth 2FA를 사용하는 FASRC 계정

• (선택 사항) Touch ID 게이트: Xcode Command Line Tools (xcode-select --install)

1. 명령 설치

cd clt
npm link          # or: alias cluster="node /path/to/clt/cluster.js" in ~/.zshrc

선택 사항 Touch ID 게이트(건너뛰면 스크립트가 프롬프트를 표시하지 않음):

swiftc -O touchid.swift -o touchid

2. ssh 구성 (필수)

~/.ssh/config에 다음을 추가하고(필요하면 생성), mkdir -p ~/.ssh/sockets를 실행하세요:

Host fasrc
  HostName login.rc.fas.harvard.edu
  User YOUR_FASRC_USERNAME
  ControlMaster auto
  ControlPath ~/.ssh/sockets/%r@%h-%p
  ControlPersist 8h
  ServerAliveInterval 60

Host winbox
  HostName 127.0.0.1        # via the AnyDesk TCP tunnel; or the LAN IP of the PC
  Port 2222                 # the tunnel's local port (drop this line if using LAN IP)
  User YOUR_WINDOWS_USERNAME

ControlMaster 블록이 모든 작업을 빠르게 만듭니다. 이 블록이 없으면 scp/ssh를 실행할 때마다 새 비밀번호 + OTP가 필요하며 도구가 실행을 거부합니다.

3. OpenAuth TOTP 시드 가져오기

OpenAuth Java 앱은 base32 비밀키로 시드됩니다. 두 가지 방법으로 얻을 수 있습니다:

• FASRC OpenAuth 셀프 서비스 페이지에 로그인하여 토큰을 (재)발급합니다. Java 앱 다운로드 옆에 전화 인증기 앱용 QR 코드/시크릿이 제공됩니다. 해당 base32 문자열을 복사하세요.

• 또는 이미 다운로드한 OpenAuth 번들 내부를 살펴보세요. 시드는 jar 옆에 있는 앱의 구성 파일에 저장되어 있습니다.

참고: 재발급하면 기존 Java 앱의 코드가 작동을 멈춥니다. 새 시드가 유일한 올바른 시드가 됩니다(cluster code를 생성기로 사용하거나 전화 앱에도 로드하세요).

4. Windows 머신: 내장 OpenSSH 서버

AnyDesk 자체에는 스크립팅 가능한 파일 전송 기능이 없으므로 Windows의 내장 OpenSSH 서버(Windows 10/11 선택적 기능 — 타사 소프트웨어 불필요)에서 scp로 파일을 가져옵니다. Windows 머신의 관리자 PowerShell에서:

Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic

그런 다음 Mac의 공개 키를 설치하여 scp에 비밀번호가 필요 없도록 합니다(Mac에서 cat ~/.ssh/id_ed25519.pub; 키가 없으면 먼저 ssh-keygen -t ed25519 실행). 주의: Windows 계정이 관리자인 경우 키는 특수 파일에 저장됩니다:

Add-Content -Path C:\ProgramData\ssh\administrators_authorized_keys -Value "ssh-ed25519 AAAA...your key..."
icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"

(관리자가 아닌 계정의 경우 일반적인 C:\Users\사용자명\.ssh\authorized_keys 위치입니다.)

5. Mac에서 Windows에 연결

다음 중 하나를 선택하세요:

• AnyDesk TCP 터널 (현재 워크플로와 일치): Mac의 AnyDesk에서 Windows PC의 세션 설정을 열고 TCP 터널링 → 로컬 포트 2222 → 원격 127.0.0.1:22. 터널은 AnyDesk 세션이 연결된 동안에만 존재합니다. AnyDesk 세션에 연결되어 있으면 괜찮습니다. AnyDesk 라이선스에 TCP 터널링이 포함되어 있는지 확인하세요.

• 동일 네트워크 / VPN: winbox 블록에서 HostName을 PC의 IP로 설정하고 Port 2222 줄을 삭제하세요. 연구실 기기가 동일 네트워크를 공유하는 경우 가장 간단합니다.

• Windows를 완전히 건너뜀: COMSOL 폴더를 OneDrive(Harvard 제공)에 넣고 Mac에 동기화한 후 cluster ~/OneDrive/.../file3.mph로 로컬 복사본을 사용하고 PC에 접근하지 않습니다.

테스트: ssh winbox로 비밀번호 없이 PC에 로그인되어야 합니다.

6. 시크릿 저장 및 구성

cluster setup

호스트 별칭, Slurm 기본값, FASRC 비밀번호, TOTP 시드를 묻습니다. 시크릿은 macOS 키체인에 저장됩니다(디스크에 저장되지 않으며 이 저장소에도 저장되지 않음). 설정이 끝나면 생성된 2FA 코드가 출력됩니다. 신뢰하기 전에 Java 앱과 일치하는지 확인하세요.

그런 다음 클러스터에서 (cluster shell을 통해 한 번) 확인:

• module avail comsol — 정확한 모듈 이름을 ~/.config/clt/config.json에 설정

• 그룹에 COMSOL 라이선스가 있는지 확인하고 연구실에 적합한 파티션을 선택

사용법

cluster file3.mph                    # fetch from Windows, upload, submit
cluster ./local/file3.mph            # a file that exists locally skips the Windows fetch
cluster file3.mph -study std2        # extra args are passed to `comsol batch`
cluster status                       # your whole queue
cluster status 12345678              # one job, incl. finished (sacct)
cluster logs file3                   # tail batch.log
cluster fetch file3                  # → ./file3-out.mph + ./file3-batch.log

작업 파일은 클러스터의 ~/comsol_jobs/<이름>-<타임스탬프>/에 저장됩니다(in.mph, out.mph, batch.log, slurm-<ID>.log). 작업 완료 시 이메일을 받으려면 cluster setup에서 이메일을 설정하세요. 제출된 작업 기록은 ~/.config/clt/jobs.json에 저장됩니다.

MCP 서버 (AI 기반 COMSOL)

mcp/server.mjs는 전체 파이프라인을 MCP 도구로 노출하므로 Claude(또는 모든 MCP 클라이언트)가 COMSOL을 종단 간 실행할 수 있습니다: run_code (생성된 Java = 전체 COMSOL API), run_model, job_status, job_log, wait_for_job, fetch_artifacts, cancel_job, lab_fairshare. .mcp.json을 통해 프로젝트 전체에 등록됩니다. 이 저장소에서 Claude Code 세션을 열면 도구를 사용할 수 있습니다.

서버에는 제한 사항이 적용됩니다(최대 4개의 동시 작업, ≤16 CPU, ≤64 GB, ≤48시간, 허용된 파티션). lab_fairshare는 AI가 준수하도록 지시받은 healthy 플래그를 반환합니다. node mcp/smoke.mjs로 모든 것을 확인하세요. 이 스크립트는 hello-world 모델을 도구를 통해 실행하고 물리 결과를 분석 답과 비교합니다. 모델 작성 관용구 및 알려진 COMSOL API 함정은 references/에 있습니다.

연구실 구성원을 위한 포크

이 저장소에는 개인 데이터가 전혀 포함되지 않습니다. 구성은 ~/.config/clt/에, 시크릿은 각 사용자의 키체인에 저장됩니다. 연구실 동료는 저장소를 클론하고, npm link를 실행하고, 두 개의 ssh 구성 블록을 추가한 후, 자신의 자격 증명으로 cluster setup을 실행하기만 하면 됩니다. TOTP 시드를 공유하거나 어디에도 커밋하지 마세요.

새 클론에 대한 빠른 시작:

git clone <this repo> && cd clt
npm install          # MCP server deps (the CLI itself needs none)
npm link             # provides the `cluster` command
swiftc -O touchid.swift -o touchid    # optional Touch ID gate
cluster setup        # host aliases, Slurm defaults, secrets -> Keychain
cluster login        # verify; then `cluster help`

연구 데이터를 저장소 밖에 유지

references/lab/은 gitignore 처리되어 있으며 COMSOL 모델 내보내기 파일이 있는 곳입니다. 내보내기 파일에는 게시되지 않은 지오메트리와 물리, 실제 이름을 포함한 절대 경로가 포함되어 있으므로 게시해서는 안 됩니다. references/에 추적되는 파일은 일반적이고 게시 가능한 예제(HelloBox, SweepBox, Inspect)와 CONVENTIONS.md(생성된 모델이 작동하도록 하는 축적된 COMSOL API 지식)입니다. 푸시하기 전에 git status로 잘못된 .mph, .java 내보내기 또는 결과 CSV가 있는지 확인하세요.

보안 참고 사항 (솔직하게)

• TOTP 시드를 동일한 Mac의 비밀번호 옆에 저장하면 2FA가 "잠금 해제된 Mac의 소유"로 축소됩니다. 이는 원격 자격 증명 도용으로부터 보호하지만, 키보드 앞에 있는 사람으로부터는 보호되지 않습니다. FileVault를 켜두세요.

• Touch ID 게이트는 이 스크립트에 대한 편의 잠금 장치일 뿐이며 암호화가 아닙니다. 시크릿은 키체인으로 보호됩니다. 모든 시크릿 읽기 시 macOS 확인 대화상자를 강제하려면 신뢰하는 앱 없이 항목을 다시 생성하세요: security add-generic-password -U -T "" -a $USER -s clt-cluster-password -w

• 자체 OTP 자동화가 FASRC의 허용 가능 사용 정책에 부합하는지 확인하세요. 이는 개인별 편의 자동화이며 시드는 개인 정보로 유지되어야 합니다.

문제 해결

• login failed — 수동으로 ssh fasrc를 실행하여 실제 프롬프트를 확인하고 cluster code를 Java 앱과 비교하세요. Mac의 시계가 맞지 않으면 TOTP 코드가 잘못됩니다(시스템 설정 → 일반 → 날짜 및 시간 → 자동 설정).

• no ControlMaster socket — Host fasrc 블록에 ControlMaster 줄이 누락되었거나 ~/.ssh/sockets가 존재하지 않습니다.

• Windows 가져오기 실패 — AnyDesk 세션(및 터널)이 켜져 있습니까? ssh winbox가 작동합니까? .mph 파일 이름에 공백이 있으면 지원되지 않습니다. 이름을 바꾸세요.

• 작업이 즉시 종료됨 — cluster logs는 일반적으로 라이선스 또는 모듈 오류를 표시합니다. 모듈 이름과 그룹의 COMSOL 라이선스를 확인하세요.