설치 가이드 - SessionCast

개요

⚠️ 보안 및 책임 범위

Agent는 오픈소스입니다

SessionCast Agent는 사용자의 머신에서 실행되며, 터미널 세션에 대한 전체 접근 권한을 가집니다. 기술적으로 Agent는 다음을 수행할 수 있습니다:

화면 내용을 캡처하고 전송
터미널에 키 입력 전송
터미널에서 보이는 파일, 환경 변수, 자격 증명에 접근

이러한 이유로 Agent 소스 코드를 GitHub에 완전 공개했습니다. 사용자가 직접 코드를 검토하고, 감사하고, 수정할 수 있습니다. 우리는 투명성으로 신뢰를 증명합니다.

SessionCast는 "전달자"이지 "제어자"가 아닙니다

SessionCast는 터미널에서 실행 중인 AI CLI 도구(Claude Code, Gemini CLI, Codex CLI, Cursor 등)에게 명령을 전달합니다. AI 도구를 제어하거나, 수정하거나, 대체하지 않습니다.

우리가 하는 것: 사용자의 키 입력을 AI 코딩 에이전트가 실행 중인 터미널에 전달
우리가 하지 않는 것: AI의 응답 수정, 권한 우회, 도구의 동작 변경

자율 실행 모드(예: Claude의 --dangerously-skip-permissions, Codex의 full-auto 모드)를 활성화하여 시스템 손상, 파일 삭제, 의도하지 않은 변경이 발생한 경우, 이는 전적으로 사용자의 책임입니다. SessionCast는 단순히 입력한 내용을 전달할 뿐입니다.

사용자의 책임

배포 환경 및 데이터의 보안
AI CLI 도구 설정 및 권한 구성
SessionCast를 통해 실행된 명령의 결과
자체 호스팅 시: HTTPS, 방화벽, 인증 설정

전체 약관은 MIT 라이선스를 참조하세요.

SessionCast는 세 가지 주요 컴포넌트로 구성됩니다:

릴레이 서버

에이전트와 웹 클라이언트 사이의 WebSocket 통신을 중계하고 인증을 관리합니다.

웹 클라이언트

브라우저에서 터미널 세션을 보고 상호작용할 수 있는 React 기반 웹 애플리케이션입니다.

에이전트

로컬 머신에서 실행되어 tmux 세션을 캡처하고 릴레이 서버로 스트리밍합니다.

배포 방식 선택

로컬 배포 (내부용)

로컬 네트워크에서 개인 또는 내부 팀 용도로 SessionCast를 실행합니다. 테스트, 개발, 또는 홈 오피스 환경에 적합합니다.

사전 요구사항

Java 17 이상
Node.js 18 이상 (웹 클라이언트 빌드용)
Docker (권장) 또는 로컬 환경
Google Cloud Console의 OAuth 2.0 클라이언트 ID

Docker로 빠른 시작

Docker Compose

# 저장소 클론
git clone https://github.com/sessioncast/server.git
cd server

# .env 파일 생성
cat > .env << EOF
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
JWT_SECRET=your-jwt-secret-key-at-least-256-bits
FRONTEND_URL=http://localhost:3000
CORS_ORIGINS=http://localhost:3000
EOF

# Docker Compose로 실행
docker-compose up -d

수동 설치

1. 릴레이 서버

Bash

# 클론 및 빌드
git clone https://github.com/sessioncast/server.git
cd server
./gradlew build -x test

# 실행
java -jar build/libs/relay-0.0.1-SNAPSHOT.jar

2. 웹 클라이언트

Bash

# 클론 및 빌드
git clone https://github.com/sessioncast/web.git
cd web
npm install

# 설정
echo "VITE_API_URL=http://localhost:8080" > .env
echo "VITE_WS_URL=ws://localhost:8080/ws" >> .env

# 개발 서버 실행
npm run dev

Google OAuth 설정

Google Cloud Console로 이동
OAuth 2.0 클라이언트 ID 생성 (웹 애플리케이션 유형)
승인된 리디렉션 URI 추가: http://localhost:8080/login/oauth2/code/google
클라이언트 ID와 시크릿을 환경 변수에 복사

AWS 배포 (프로덕션)

안정적이고 확장 가능한 프로덕션 환경을 위해 AWS에 SessionCast를 배포합니다. HTTPS, 로드 밸런싱, 오토 스케일링을 포함합니다.

사전 요구사항

적절한 권한을 가진 AWS 계정
AWS CLI 구성됨
도메인 이름 (SSL 인증서용)
Google Cloud Console의 OAuth 2.0 클라이언트 ID

아키텍처 개요

AWS 아키텍처

┌─────────────────────────────────────────────────────────┐
│                      Route 53                           │
│                    (DNS + SSL)                          │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│              Application Load Balancer                   │
│                   (HTTPS:443)                            │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┴─────────────┐
        │                           │
┌───────▼───────┐           ┌───────▼───────┐
│   ECS Fargate │           │   S3 + CF     │
│  (릴레이 서버) │           │ (웹 클라이언트)│
└───────────────┘           └───────────────┘

1단계: ECR 저장소 생성

AWS CLI

# ECR 저장소 생성
aws ecr create-repository --repository-name sessioncast-server

# ECR 로그인
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com

# 빌드 및 푸시
docker build -t sessioncast-server .
docker tag sessioncast-server:latest \
  YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/sessioncast-server:latest
docker push YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/sessioncast-server:latest

2단계: ECS 클러스터 생성

AWS CLI

# 클러스터 생성
aws ecs create-cluster --cluster-name sessioncast-cluster

# 태스크 정의 생성 (task-definition.json으로 저장)
{
  "family": "sessioncast-server",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "containerDefinitions": [
    {
      "name": "server",
      "image": "YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/sessioncast-server:latest",
      "portMappings": [{"containerPort": 8080}],
      "environment": [
        {"name": "GOOGLE_CLIENT_ID", "value": "your-client-id"},
        {"name": "GOOGLE_CLIENT_SECRET", "value": "your-secret"},
        {"name": "JWT_SECRET", "value": "your-jwt-secret"},
        {"name": "FRONTEND_URL", "value": "https://your-domain.com"}
      ]
    }
  ]
}

# 태스크 등록
aws ecs register-task-definition --cli-input-json file://task-definition.json

3단계: S3 + CloudFront에 웹 클라이언트 배포

AWS CLI

# S3 버킷 생성
aws s3 mb s3://sessioncast-web-client

# 웹 클라이언트 빌드
cd web
npm run build

# S3에 업로드
aws s3 sync dist/ s3://sessioncast-web-client --delete

# CloudFront 배포 생성 (AWS 콘솔 또는 CLI 사용)
# 보안을 위해 OAI와 함께 S3 버킷을 연결

4단계: ACM으로 SSL 설정

AWS CLI

# 인증서 요청 (CloudFront용으로 us-east-1에서 요청 필요)
aws acm request-certificate \
  --domain-name your-domain.com \
  --validation-method DNS \
  --region us-east-1

# Route 53 DNS 레코드로 검증

보안 모범 사례

시크릿은 AWS Secrets Manager에 저장
최소 권한의 IAM 역할 사용
ECS 태스크에 VPC 활성화
추가 보호를 위해 WAF 구성

🚀 SessionCast Cloud (베타)

가장 쉬운 시작 방법! 서버 설정 없이 CLI 설치 후 브라우저로 로그인하면 터미널 세션 스트리밍을 바로 시작할 수 있습니다.

1단계: CLI 설치

Bash

# SessionCast CLI를 전역으로 설치
npm install -g sessioncast-cli

2단계: 로그인 (브라우저 기반)

Google 계정으로 로그인 - 브라우저가 자동으로 열립니다:

Bash

# 브라우저가 열리며 인증 진행
sessioncast login

# ✓ You are now logged in to SessionCast

3단계: Agent 실행

Bash

# 에이전트 시작
sessioncast agent

# 브라우저에서 접속:
# https://app.sessioncast.io

✨ 끝!

tmux 세션이 웹 콘솔에 자동으로 표시됩니다. 수동 토큰 설정이 필요 없습니다!

선택사항: 상태 확인

Bash

# 로그인 상태 확인
sessioncast status

# 필요시 로그아웃
sessioncast logout

✨ Free 플랜 포함

Free 플랜으로 시작하세요 - 1개 에이전트 연결과 기본 기능이 포함됩니다. 더 많은 에이전트와 고급 기능을 위해 언제든지 업그레이드하세요.

에이전트 설정

에이전트는 로컬 머신에서 실행되어 tmux 세션을 서버로 스트리밍합니다.

사전 요구사항

Node.js 18 이상
tmux 설치됨 (Linux/macOS) 또는 itmux (Windows)
Linux, macOS, 또는 Windows

에이전트 설치

Bash

# SessionCast CLI를 전역으로 설치
npm install -g sessioncast-cli

로그인 (SaaS 권장)

SessionCast Cloud 사용 시 브라우저 기반 로그인 - 수동 토큰 설정 불필요:

Bash

# 브라우저로 로그인 (자동으로 열림)
sessioncast login

# 로그인 상태 확인
sessioncast status

수동 설정 (자체 호스팅)

자체 호스팅 배포 시 ~/.sessioncast.yml 파일을 생성하세요:

~/.sessioncast.yml

# 머신 식별자 (머신당 고유)
machineId: my-workstation

# 릴레이 서버 WebSocket URL
relay: wss://your-server.com/ws   # 로컬의 경우 ws://localhost:8080/ws

# 에이전트 인증 토큰
token: agt_your_secure_token_here

보안 주의

에이전트 토큰은 민감한 정보입니다. 공개 저장소에 절대 커밋하지 마세요.

에이전트 실행

Bash

# 직접 실행
sessioncast agent

# 또는 백그라운드에서 실행
nohup sessioncast agent > ~/sessioncast-agent.log 2>&1 &

macOS 자동 시작 (launchd)

~/Library/LaunchAgents/com.sessioncast.agent.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.sessioncast.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/sessioncast</string>
        <string>agent</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

서비스 로드

launchctl load ~/Library/LaunchAgents/com.sessioncast.agent.plist

Windows 설정 (itmux 사용)

Windows에는 네이티브 tmux가 없습니다. SessionCast는 Windows 호환성을 위해 itmux (Cygwin + tmux 번들)를 사용합니다.

1단계: itmux 설치

PowerShell

# 옵션 1: GitHub에서 다운로드
# https://github.com/phayte/itmux/releases
# C:\itmux에 압축 해제

# 옵션 2: Chocolatey 사용
choco install itmux

# 옵션 3: Scoop 사용
scoop install itmux

2단계: 환경 변수 설정

PowerShell (관리자)

# ITMUX_HOME 환경 변수 설정
[Environment]::SetEnvironmentVariable("ITMUX_HOME", "C:\itmux", "User")

# 설치 확인
$env:ITMUX_HOME = "C:\itmux"
& "$env:ITMUX_HOME\bin\bash.exe" -c "tmux -V"

3단계: SessionCast 설치 및 실행

PowerShell

# SessionCast CLI 설치
npm install -g sessioncast-cli

# 로그인
sessioncast login

# 에이전트 시작 (itmux 자동 사용)
sessioncast agent

Windows 경로 자동 감지

SessionCast는 다음 위치에서 itmux를 자동으로 검색합니다:

ITMUX_HOME 환경 변수
%USERPROFILE%\itmux
C:\itmux
C:\Program Files\itmux

AI CLI와 함께 사용

사용 중인 AI 코딩 에이전트를 tmux 세션 안에서 실행하세요. SessionCast가 자동으로 스마트폰에 스트리밍합니다.

Bash

# tmux 세션을 시작하고 AI CLI를 실행하세요
tmux new -s dev

🟠 Claude Code

claude "테스트 실행하고 수정해줘"

🔵 Gemini CLI

gemini "이 프로젝트 분석해줘"

🟢 Codex CLI

codex "인증 모듈 리팩토링해줘"

🟣 Cursor

cursor "JWT 인증 추가해줘"

⚪ Ollama

ollama run llama3

그런 다음 스마트폰에서 app.sessioncast.io를 열면 끝!

모든 터미널 도구와 호환

SessionCast는 tmux 세션을 있는 그대로 스트리밍합니다. AI 코딩 에이전트뿐만 아니라 터미널에서 실행되는 모든 CLI 도구와 함께 사용할 수 있습니다.

설정 레퍼런스

릴레이 서버 환경 변수

변수	설명	기본값
`GOOGLE_CLIENT_ID`	Google OAuth 2.0 클라이언트 ID	필수
`GOOGLE_CLIENT_SECRET`	Google OAuth 2.0 클라이언트 시크릿	필수
`JWT_SECRET`	JWT 서명 키 (최소 256 bits)	필수
`FRONTEND_URL`	웹 클라이언트 URL	http://localhost:3000
`CORS_ORIGINS`	허용된 CORS origins (쉼표 구분)	http://localhost:3000
`ALLOWED_DOMAINS`	허용된 이메일 도메인 (쉼표 구분)	모든 도메인 허용

에이전트 설정 (YAML)

속성	설명	필수 여부
`machineId`	고유한 머신 식별자	예
`relay`	릴레이 서버 WebSocket URL	예
`token`	에이전트 인증 토큰	예
`autoDiscovery`	tmux 세션 자동 감지	아니오 (기본값: false)
`sessions`	수동 세션 설정 목록	아니오