Usage Guide

Learn how to use SessionCast effectively.

Getting Started

Basic Workflow

1

Create tmux Session

Create a tmux session on your local machine.

tmux new -s workspace
2

Verify Agent

If the Agent is running, sessions are detected automatically.

# Check Agent logs
tail -f ~/sessioncast-agent.log

# Verify session registration message
# Look for "Session 'workspace' registered" output
3

Access via Web

Open SessionCast in your browser and sign in with your Google account.

4

Select and Use Session

Click on a session from the list to view the terminal.

tmux Sessions

Creating Sessions

Basic tmux Commands 
# Create new session
tmux new -s session-name

# Create session in background
tmux new -d -s session-name

# Add window to session
tmux new-window -t session-name

# List sessions
tmux ls

Session Naming Convention

In SessionCast, sessions are identified using the machineId/tmuxSession format:

  • my-workstation/dev - dev session on my-workstation machine
  • server-01/monitoring - monitoring session on server-01 machine

Auto-Discovery Mode

Setting autoDiscovery: true allows the Agent to automatically detect all tmux sessions:

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

Excluding from Auto-Discovery

To exclude specific sessions, prefix the session name with _ (underscore):

tmux new -s _private-session

Web Interface

Login

SessionCast uses Google OAuth 2.0:

  1. Click the "Sign in with Google" button on the web page
  2. Select and authenticate your Google account
  3. You'll be automatically redirected to the session list

Domain Restriction

If the administrator has set ALLOWED_DOMAINS, only emails from those domains can access.

Session List

After login, only sessions registered with your Agent Token are displayed:

  • Session Label: Configured label or tmux session name
  • Machine ID: The machine where the session is running
  • Status: Connected/Disconnected

Terminal View

Clicking a session displays the terminal screen:

  • Real-time Display: Current state of the tmux session
  • Auto-resizing: Terminal adjusts to browser window size
  • Color Support: Color output via ANSI escape codes

Keyboard Input

Basic Input

Click the terminal area to enable keyboard input:

  • Regular text input
  • Execute commands with Enter key
  • Arrow keys, Backspace, Delete and other special keys

Control Key Combinations

Key Function
Ctrl + C Interrupt current process (SIGINT)
Ctrl + D Send EOF / Exit shell
Ctrl + Z Suspend process (SIGTSTP)
Ctrl + L Clear screen
Ctrl + A Move to beginning of line
Ctrl + E Move to end of line

tmux Prefix Key

The default tmux prefix key is Ctrl + B:

Key Sequence Function
Ctrl+B → c Create new window
Ctrl+B → n Next window
Ctrl+B → p Previous window
Ctrl+B → % Split vertically
Ctrl+B → " Split horizontally
Ctrl+B → d Detach from session

Note

Some browser shortcuts may conflict. For example, Ctrl+W closes the browser tab. These keys may not be passed to the terminal.

Session Management

Creating Sessions from Web

You can create new tmux sessions from the Web UI:

  1. Click "New Session" button on the session list screen
  2. Select a machine
  3. Enter session name
  4. Click "Create" button

The Agent receives the request and creates the tmux session locally.

Terminating Sessions

Ways to terminate a session:

  • Web UI: Click delete button in session list
  • Terminal: exit command or Ctrl+D
  • tmux command: tmux kill-session -t session-name

Refreshing Session List

The session list updates automatically, but to refresh manually:

  • Click refresh button on the session list screen
  • Browser refresh (F5)

Troubleshooting

Session Not Showing in List

Checklist:

  1. Check if Agent is running 
    ps aux | grep sessioncast-agent
  2. Check Agent logs 
    tail -f ~/sessioncast-agent.log
  3. Verify tmux session exists 
    tmux ls
  4. Verify Agent Token is correct
  5. Verify logged-in email matches Token owner

Empty Screen

Cause:

Newly created tmux sessions may show an empty screen if no commands have been executed yet.

Solution:

  1. Attach to the session directly from terminal and run a command 
    tmux attach -t session-name
  2. Or press any key in the web interface to trigger a screen refresh

Keyboard Input Not Working

Checklist:

  1. Click the terminal area to ensure it has focus
  2. Check WebSocket connection status in browser developer tools
  3. Check Agent logs for key input messages

Frequent Disconnections

Possible Causes:

  • Unstable network connection
  • Proxy/firewall blocking WebSocket
  • Server resource shortage

Solution:

  1. Check network connection status
  2. Verify WebSocket is allowed in proxy settings
  3. Check server logs: 
    journalctl -u sessioncast -f

Restarting the Agent

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
Manual Execution 
# Kill existing process
pkill -f sessioncast-agent

# Restart
nohup java -jar ~/sessioncast-agent.jar > ~/sessioncast-agent.log 2>&1 &