사용 가이드

SessionCast를 효과적으로 사용하는 방법을 알아봅니다.

시작하기

기본 워크플로우

1

tmux 세션 생성

로컬 머신에서 tmux 세션을 생성합니다.

tmux new -s workspace
2

Agent 확인

Agent가 실행 중이면 자동으로 세션이 감지됩니다.

# Agent 로그 확인
tail -f ~/sessioncast-agent.log

# 세션 등록 메시지 확인
# "Session 'workspace' registered" 출력 확인
3

웹에서 접속

브라우저에서 SessionCast 웹에 접속하고 Google 계정으로 로그인합니다.

4

세션 선택 및 사용

세션 목록에서 원하는 세션을 클릭하면 터미널이 표시됩니다.

tmux 세션

세션 생성

tmux 기본 명령어 
# 새 세션 생성
tmux new -s session-name

# 백그라운드로 세션 생성
tmux new -d -s session-name

# 세션에 창(window) 추가
tmux new-window -t session-name

# 세션 목록 확인
tmux ls

세션 이름 규칙

SessionCast에서 세션은 machineId/tmuxSession 형식으로 식별됩니다:

  • my-workstation/dev - my-workstation 머신의 dev 세션
  • server-01/monitoring - server-01 머신의 monitoring 세션

Auto-Discovery 모드

autoDiscovery: true를 설정하면 Agent가 자동으로 모든 tmux 세션을 감지합니다:

# ~/.tmux-remote.yml
machineId: my-workstation
relay: wss://your-server.com/ws
token: agt_your_token
autoDiscovery: true

Auto-Discovery 제외

특정 세션을 제외하려면 세션 이름 앞에 _ (언더스코어)를 붙이세요:

tmux new -s _private-session

웹 인터페이스

로그인

SessionCast는 Google OAuth 2.0을 사용합니다:

  1. 웹 페이지에서 "Sign in with Google" 버튼 클릭
  2. Google 계정 선택 및 인증
  3. 자동으로 세션 목록 페이지로 이동

도메인 제한

관리자가 ALLOWED_DOMAINS를 설정한 경우, 해당 도메인의 이메일만 접속할 수 있습니다.

세션 목록

로그인 후 자신의 Agent Token으로 등록된 세션만 표시됩니다:

  • 세션 라벨: 설정된 라벨 또는 tmux 세션 이름
  • 머신 ID: 세션이 실행 중인 머신
  • 상태 표시: 연결됨/연결 해제됨

터미널 뷰

세션을 클릭하면 터미널 화면이 표시됩니다:

  • 실시간 화면: tmux 세션의 현재 상태
  • 자동 리사이징: 브라우저 창 크기에 맞게 터미널 크기 조절
  • 컬러 지원: ANSI 이스케이프 코드를 통한 컬러 출력

키보드 입력

기본 입력

터미널 영역을 클릭한 후 키보드 입력이 가능합니다:

  • 일반 텍스트 입력
  • Enter 키로 명령 실행
  • 방향키, Backspace, Delete 등 특수 키

Control 키 조합

키 기능
Ctrl + C 현재 프로세스 중단 (SIGINT)
Ctrl + D EOF 전송 / 쉘 종료
Ctrl + Z 프로세스 일시 중지 (SIGTSTP)
Ctrl + L 화면 지우기
Ctrl + A 줄 시작으로 이동
Ctrl + E 줄 끝으로 이동

tmux 프리픽스 키

tmux의 기본 프리픽스 키는 Ctrl + B입니다:

키 조합 기능
Ctrl+B → c 새 창(window) 생성
Ctrl+B → n 다음 창으로 이동
Ctrl+B → p 이전 창으로 이동
Ctrl+B → % 수직 분할
Ctrl+B → " 수평 분할
Ctrl+B → d 세션에서 분리 (detach)

주의사항

일부 브라우저 단축키와 충돌할 수 있습니다. 예: Ctrl+W는 브라우저에서 탭을 닫습니다. 이러한 키는 터미널로 전달되지 않을 수 있습니다.

세션 관리

웹에서 세션 생성

Web UI에서 새로운 tmux 세션을 생성할 수 있습니다:

  1. 세션 목록 화면에서 "New Session" 버튼 클릭
  2. 머신 선택
  3. 세션 이름 입력
  4. "Create" 버튼 클릭

Agent가 요청을 받아 로컬에서 tmux 세션을 생성합니다.

세션 종료

세션을 종료하는 방법:

  • 웹 UI: 세션 목록에서 삭제 버튼 클릭
  • 터미널: exit 명령 또는 Ctrl+D
  • tmux 명령: tmux kill-session -t session-name

세션 목록 새로고침

세션 목록은 자동으로 업데이트되지만, 수동으로 새로고침하려면:

  • 세션 목록 화면에서 새로고침 버튼 클릭
  • 브라우저 새로고침 (F5)

문제 해결

세션이 목록에 표시되지 않음

확인사항:

  1. Agent가 실행 중인지 확인 
    ps aux | grep sessioncast-agent
  2. Agent 로그 확인 
    tail -f ~/sessioncast-agent.log
  3. tmux 세션이 존재하는지 확인 
    tmux ls
  4. Agent Token이 올바른지 확인
  5. 웹에서 로그인한 이메일이 Token의 owner와 일치하는지 확인

화면이 비어있음

원인:

새로 생성된 tmux 세션은 아직 어떤 명령도 실행되지 않아 빈 화면일 수 있습니다.

해결:

  1. 터미널에서 직접 세션에 접속하여 명령 실행 
    tmux attach -t session-name
  2. 또는 웹에서 아무 키나 입력하여 화면 갱신 유도

키 입력이 전달되지 않음

확인사항:

  1. 터미널 영역을 클릭하여 포커스가 있는지 확인
  2. 브라우저 개발자 도구에서 WebSocket 연결 상태 확인
  3. Agent 로그에서 키 수신 메시지 확인

연결이 자주 끊김

가능한 원인:

  • 네트워크 불안정
  • 프록시/방화벽 WebSocket 차단
  • 서버 리소스 부족

해결:

  1. 네트워크 연결 상태 확인
  2. 프록시 설정에서 WebSocket 허용 확인
  3. 서버 로그 확인: 
    journalctl -u sessioncast -f

에이전트 재시작

macOS (launchd) 
launchctl unload ~/Library/LaunchAgents/com.sessioncast.agent.plist
launchctl load ~/Library/LaunchAgents/com.sessioncast.agent.plist
Linux (systemd) 
sudo systemctl restart sessioncast-agent
수동 실행 
# 기존 프로세스 종료
pkill -f sessioncast-agent

# 재시작
nohup java -jar ~/sessioncast-agent.jar > ~/sessioncast-agent.log 2>&1 &