SessionCast CLI

Node.js agent and CLI for SessionCast - a real-time terminal sharing platform.

Features

$3

- Auto-discovery: Automatically detects and connects tmux sessions
- Real-time screen capture: Streams terminal output with gzip compression
- Circuit breaker: Prevents reconnection storms with exponential backoff
- Interactive control: Supports keyboard input, resize, and session management
- File viewer: Cmd+Click on file paths to view files in browser

$3

- sessioncast login - Browser-based OAuth login (recommended)
- sessioncast login - Authenticate with API key or agent token
- sessioncast logout - Clear stored credentials
- sessioncast status - Check authentication status
- sessioncast agents - List registered agents
- sessioncast list [agent] - List tmux sessions
- sessioncast send - Send keys to a session
- sessioncast agent - Start the agent

Installation

``bash
npm install -g sessioncast-cli
`

$3

- Node.js 18+
- tmux (Linux/macOS) or itmux (Windows)

$3

Quick Install (PowerShell - Recommended):
`powershell


Download and extract itmux to C:\itmux

Invoke-WebRequest -Uri "https://github.com/itefixnet/itmux/releases/download/v1.1.0/itmux_1.1.0_x64_free.zip" -OutFile "$env:TEMP\itmux.zip"
Expand-Archive -Path "$env:TEMP\itmux.zip" -DestinationPath "C:\itmux" -Force

Install SessionCast CLI

npm install -g sessioncast-cli
`

Manual Installation:
1. Download itmux v1.1.0
2. Extract to one of these locations:
- C:\itmux (recommended)
- %USERPROFILE%\itmux
- Or set ITMUX_HOME environment variable
3. Verify: C:\itmux\bin\bash.exe should exist
4. Install CLI: npm install -g sessioncast-cli

Quick Start

1. Get your agent token from app.sessioncast.io

2. Create config file ~/.sessioncast.yml:

`yaml
machineId: my-machine
relay: wss://relay.sessioncast.io/ws
token: agt_your_agent_token_here
`

3. Start the agent:

`bash
sessioncast agent
`

4. View your sessions at app.sessioncast.io

Configuration

Create ~/.sessioncast.yml or ~/.tmux-remote.yml:

`yaml
machineId: my-machine
relay: wss://relay.sessioncast.io/ws
token: agt_your_agent_token_here

Optional: API configuration

api:
enabled: true
agentId: "your-agent-uuid"

exec:
enabled: true
shell: /bin/bash
workingDir: /home/user
defaultTimeout: 30000

llm:
enabled: false
`

$3

- SESSIONCAST_CONFIG - Custom config file path
- TMUX_REMOTE_CONFIG - Alternative config file path

Usage

$3

`bash


Run agent (foreground)

sessioncast agent

Run agent (background)

nohup sessioncast agent > /tmp/sessioncast-agent.log 2>&1 &
`

$3

`bash


Send text to a session

sessioncast send my-machine/dev "ls -la"

Send special keys

sessioncast send my-machine/dev "Enter"
`

Architecture

`
┌─────────────┐ WebSocket ┌─────────────┐ WebSocket ┌─────────────┐
│ Agent │ ◄─────────────────► │ Relay │ ◄────────────────► │ Viewer │
│ (Node.js) │ screen/keys │ (Server) │ screen/keys │ (Web) │
└─────────────┘ └─────────────┘ └─────────────┘
│
│ tmux
▼
┌─────────────┐
│ tmux │
│ sessions │
└─────────────┘
``

Circuit Breaker

The agent implements a circuit breaker pattern to prevent reconnection storms:

- Max reconnect attempts: 5
- Base delay: 1 second
- Max delay: 30 seconds (with exponential backoff + jitter)
- Circuit breaker duration: 2 minutes cooldown after max attempts

Requirements

- Node.js >= 18
- tmux installed on the host machine

License

MIT License - see LICENSE for details.

Support

- Homepage: https://sessioncast.io
- Email: devload@sessioncast.io