## 시작하기

### 기본 워크플로우

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 &
```