Installation Guide - SessionCast

Overview

⚠️ Security & Responsibility

Agent is Open Source

The SessionCast Agent runs on your machine with full access to your terminal sessions. This means the Agent can technically:

Capture and transmit screen contents
Send keystrokes to your terminal
Access files, environment variables, and credentials visible in the terminal

For this reason, we have made the Agent fully open source. You can inspect, audit, and modify the code yourself. We prove our trustworthiness through transparency.

📦 View Agent Source Code on GitHub

SessionCast is a "Messenger", Not a "Controller"

SessionCast delivers your commands to AI CLI tools (Claude Code, Gemini CLI, Codex CLI, Cursor, etc.) running in the terminal. We do not control, modify, or replace any AI tool's behavior.

What we do: Relay your keystrokes to the terminal where your AI coding agent is running
What we don't do: Modify AI responses, bypass permissions, or alter tool behavior

If you enable autonomous modes (e.g., Claude's --dangerously-skip-permissions, Codex's full-auto mode) and it causes system damage, file deletion, or unintended changes, that is entirely your responsibility. SessionCast simply delivers what you type.

Your Responsibilities

Security of your deployment and data
AI CLI tool settings and permission configurations
Consequences of commands executed through SessionCast
Self-hosted deployments: HTTPS, firewalls, authentication

Please review the MIT License for full terms.

SessionCast consists of three main components:

Relay Server

Relays WebSocket communication between Agent and Web Client, managing authentication.

Web Client

React-based web application for viewing and interacting with terminal sessions in the browser.

Agent

Runs on your local machine to capture tmux sessions and stream them to the Relay Server.

Choose Your Deployment

Local Deployment (Internal Use)

Run SessionCast on your local network for personal use or internal team access. Best for testing, development, or home office setups.

Prerequisites

Java 17 or higher
Node.js 18 or higher (for Web Client build)
Docker (recommended) or local environment
OAuth 2.0 Client ID from Google Cloud Console

Quick Start with Docker

Docker Compose

# Clone the repository
git clone https://github.com/sessioncast/server.git
cd server

# Create .env file
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

# Run with Docker Compose
docker-compose up -d

Manual Setup

1. Relay Server

Bash

# Clone and build
git clone https://github.com/sessioncast/server.git
cd server
./gradlew build -x test

# Run
java -jar build/libs/relay-0.0.1-SNAPSHOT.jar

2. Web Client

Bash

# Clone and build
git clone https://github.com/sessioncast/web.git
cd web
npm install

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

# Run development server
npm run dev

Google OAuth Setup

Go to Google Cloud Console
Create OAuth 2.0 Client ID (Web application type)
Add authorized redirect URI: http://localhost:8080/login/oauth2/code/google
Copy Client ID and Secret to your environment

AWS Deployment (Production)

Deploy SessionCast to AWS for reliable, scalable production use. Includes HTTPS, load balancing, and auto-scaling options.

Prerequisites

AWS Account with appropriate permissions
AWS CLI configured
Domain name (for SSL certificate)
OAuth 2.0 Client ID from Google Cloud Console

Architecture Overview

AWS Architecture

┌─────────────────────────────────────────────────────────┐
│                      Route 53                           │
│                    (DNS + SSL)                          │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│              Application Load Balancer                   │
│                   (HTTPS:443)                            │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┴─────────────┐
        │                           │
┌───────▼───────┐           ┌───────▼───────┐
│   ECS Fargate │           │   S3 + CF     │
│ (Relay Server)│           │ (Web Client)  │
└───────────────┘           └───────────────┘

Step 1: Create ECR Repository

AWS CLI

# Create ECR repository
aws ecr create-repository --repository-name sessioncast-server

# Login to 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

# Build and push
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

Step 2: Create ECS Cluster

AWS CLI

# Create cluster
aws ecs create-cluster --cluster-name sessioncast-cluster

# Create task definition (save as 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"}
      ]
    }
  ]
}

# Register task
aws ecs register-task-definition --cli-input-json file://task-definition.json

Step 3: Deploy Web Client to S3 + CloudFront

AWS CLI

# Create S3 bucket
aws s3 mb s3://sessioncast-web-client

# Build web client
cd web
npm run build

# Upload to S3
aws s3 sync dist/ s3://sessioncast-web-client --delete

# Create CloudFront distribution (use AWS Console or CLI)
# Point to S3 bucket with OAI for security

Step 4: Configure SSL with ACM

AWS CLI

# Request certificate (must be in us-east-1 for CloudFront)
aws acm request-certificate \
  --domain-name your-domain.com \
  --validation-method DNS \
  --region us-east-1

# Validate via Route 53 DNS records

Security Best Practices

Store secrets in AWS Secrets Manager
Use IAM roles with minimal permissions
Enable VPC for ECS tasks
Configure WAF for additional protection

🚀 SessionCast Cloud (Beta)

The easiest way to get started! No server setup required - just install the CLI, login with your browser, and start streaming your terminal sessions.

Step 1: Install CLI

Bash

# Install SessionCast CLI globally
npm install -g sessioncast-cli

Step 2: Login (Browser-based)

Login with your Google account - your browser will open automatically:

Bash

# Browser will open for authentication
sessioncast login

# ✓ You are now logged in to SessionCast

Step 3: Run Agent

Bash

# Start the agent
sessioncast agent

# Open your browser and go to:
# https://app.sessioncast.io

✨ That's it!

Your tmux sessions will automatically appear in the web console. No manual token configuration required!

Optional: Check Status

Bash

# Check login status
sessioncast status

# Logout if needed
sessioncast logout

✨ Free Plan Included

Start with the Free plan - includes 1 agent connection and basic features. Upgrade anytime for more agents and advanced features.

Agent Setup

The Agent runs on your local machine and streams tmux sessions to the server.

Prerequisites

Node.js 18 or higher
tmux installed (Linux/macOS) or itmux (Windows)
Linux, macOS, or Windows

Install Agent

Bash

# Install SessionCast CLI globally
npm install -g sessioncast-cli

Login (Recommended for SaaS)

For SessionCast Cloud, use browser-based login - no manual token needed:

Bash

# Login via browser (opens automatically)
sessioncast login

# Check login status
sessioncast status

Manual Configuration (Self-hosted)

For self-hosted deployments, create ~/.sessioncast.yml:

~/.sessioncast.yml

# Machine identifier (unique per machine)
machineId: my-workstation

# Relay server WebSocket URL
relay: wss://your-server.com/ws   # or ws://localhost:8080/ws for local

# Agent token for authentication
token: agt_your_secure_token_here

Security Warning

Agent Token is sensitive. Never commit to public repositories.

Run Agent

Bash

# Run directly
sessioncast agent

# Or run in background
nohup sessioncast agent > ~/sessioncast-agent.log 2>&1 &

Auto-start on 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>

Load Service

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

Windows Setup (with itmux)

Windows doesn't have native tmux support. SessionCast uses itmux (Cygwin + tmux bundle) for Windows compatibility.

Step 1: Install itmux

PowerShell

# Option 1: Download from GitHub
# https://github.com/phayte/itmux/releases
# Extract to C:\itmux

# Option 2: Using Chocolatey
choco install itmux

# Option 3: Using Scoop
scoop install itmux

Step 2: Set Environment Variable

PowerShell (Admin)

# Set ITMUX_HOME environment variable
[Environment]::SetEnvironmentVariable("ITMUX_HOME", "C:\itmux", "User")

# Verify installation
$env:ITMUX_HOME = "C:\itmux"
& "$env:ITMUX_HOME\bin\bash.exe" -c "tmux -V"

Step 3: Install and Run SessionCast

PowerShell

# Install SessionCast CLI
npm install -g sessioncast-cli

# Login
sessioncast login

# Start agent (will use itmux automatically)
sessioncast agent

Windows Path Detection

SessionCast automatically searches for itmux in these locations:

ITMUX_HOME environment variable
%USERPROFILE%\itmux
C:\itmux
C:\Program Files\itmux

Use with Your AI CLI

Just run your AI coding agent inside a tmux session. SessionCast will stream it to your phone automatically.

Bash

# Start a tmux session and run your AI CLI
tmux new -s dev

🟠 Claude Code

claude "fix failing tests"

🔵 Gemini CLI

gemini "analyze this project"

🟢 Codex CLI

codex "refactor auth module"

🟣 Cursor

cursor "add JWT auth"

⚪ Ollama

ollama run llama3

Then open app.sessioncast.io on your phone. That's it!

Works with Any Terminal Tool

SessionCast streams your tmux session as-is. It works with any CLI tool — not just AI coding agents.

Configuration Reference

Relay Server Environment Variables

Variable	Description	Default
`GOOGLE_CLIENT_ID`	Google OAuth 2.0 Client ID	Required
`GOOGLE_CLIENT_SECRET`	Google OAuth 2.0 Client Secret	Required
`JWT_SECRET`	JWT signing key (minimum 256 bits)	Required
`FRONTEND_URL`	Web Client URL	http://localhost:3000
`CORS_ORIGINS`	Allowed CORS origins (comma-separated)	http://localhost:3000
`ALLOWED_DOMAINS`	Allowed email domains (comma-separated)	All domains allowed

Agent Configuration (YAML)

Property	Description	Required
`machineId`	Unique machine identifier	Yes
`relay`	Relay Server WebSocket URL	Yes
`token`	Agent authentication token	Yes
`autoDiscovery`	Auto-detect tmux sessions	No (default: false)
`sessions`	Manual session configuration list	No