Documentation

SessionForge Docs

Install the agent, connect your machines, and manage Claude Code sessions from anywhere.

Quick Start

Install the SessionForge agent on any machine in under a minute. Once running, your machine appears in the dashboard and you can open remote Claude Code sessions from any browser.

Linux / macOS — one-liner

curl -fsSL https://sessionforge.dev/agent | bash -s -- --key YOUR_KEY

Windows (PowerShell) — one-liner

iwr -useb https://sessionforge.dev/agent/install.ps1 | iex; Install-SessionForge -ApiKey 'YOUR_KEY'

Manual steps

1. Authenticate with your API key

sessionforge auth login --key sf_live_xxxxxxxxxxxx

2. Install as a background service (runs on startup)

sessionforge service install

3. Verify the agent is running

sessionforge status

Replace YOUR_KEY with an API key from Dashboard → API Keys. Keys are prefixed with sf_live_.

Agent CLI Reference

All commands are available via the sessionforge binary installed by the agent setup script.

Command	Description
`sessionforge auth login --key <key> [--server URL] [--name NAME]`	Authenticate this machine with an API key. Optionally set a custom server URL and display name.
`sessionforge auth logout`	Remove stored credentials from this machine.
`sessionforge status`	Show agent status, connected machine ID, and current sessions.
`sessionforge session list`	List all sessions on this machine with their IDs and states.
`sessionforge session start [--command claude] [--workdir .]`	Start a new session. Defaults to claude in the current directory.
`sessionforge session stop <SESSION_ID>`	Gracefully stop a running session.
`sessionforge session attach <SESSION_ID>`	Attach your terminal to an existing session (local TTY).
`sessionforge service install`	Install the agent as a system service (systemd / launchd / Windows Service).
`sessionforge service uninstall`	Remove the system service registration.
`sessionforge service start`	Start the system service.
`sessionforge service stop`	Stop the system service.
`sessionforge service restart`	Restart the system service.
`sessionforge service status`	Show the service health and uptime.
`sessionforge update`	Download and install the latest agent binary.

Dashboard

The SessionForge web dashboard gives you a single pane of glass over all your registered machines and their sessions.

Machines

Every device running the SessionForge agent appears as a Machine. The dashboard shows its online/offline status, operating system, and any active sessions. Machines stay registered even when offline and reconnect automatically when the agent restarts.

Sessions

Click any online machine to view its sessions. From there you can start a new session (choose a command and working directory), stop a running session, or open a session to interact with it. You can also start a session directly from a machine's detail page.

Terminal (xterm.js)

The in-browser terminal is a full xterm.js instance connected to a real PTY on the remote machine via WebSocket. It supports ANSI color codes, cursor movement, resize, and keyboard input — exactly as if you had an SSH session open. No client software required.

API Keys

Generate and revoke API keys from Settings → API Keys. Keys authenticate the agent and can also be used to call the REST API directly for automation.

API Keys

API keys authenticate the agent and authorize REST API access.

Creating a key

1Sign in to the dashboard at app.sessionforge.io.
2Navigate to Settings → API Keys.
3Click New Key, give it a name, and confirm.
4Copy the key immediately — it is shown only once.

Key format

sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are shown in full only at creation time. Store them in a secrets manager or environment variable. To rotate a key, create a new one and revoke the old one from the dashboard.

Supported Platforms

The SessionForge agent is distributed as a single static binary with no runtime dependencies.

OS	Architecture	Notes
Linux	`amd64`	Most cloud VMs and servers
Linux	`arm64`	AWS Graviton, Raspberry Pi 4+
macOS	`amd64`	Intel Macs (pre-2020)
macOS	`arm64`	Apple Silicon (M1, M2, M3, M4)
Windows	`amd64 (x64)`	Windows 10 / Server 2019 and later

Supported Sessions

Any of the following commands can be passed to --command when starting a session. The agent spawns the process in a PTY.

claudeClaude Code (default)

bashBash shell

zshZsh shell

shPOSIX shell

powershellPowerShell (Windows/cross-platform)

cmdWindows Command Prompt

The target command must be installed on the remote machine. The agent does not bundle interpreters or runtimes.

Session Handoff

Session Handoff lets Claude Code yield control of a live terminal to a human teammate — without stopping, restarting, or losing any session state. The original process keeps running; a team member simply opens a URL and gets full keyboard control of the same terminal. When they are done, control is returned and Claude can continue.

Prerequisites

✓

SessionForge session

Claude Code must be running inside a session started with sessionforge run

✓

/sf-pause skill

The /sf-pause Claude Code skill must be installed on the machine

Using /sf-pause

Inside a running Claude Code session, invoke /sf-pause. The skill calls the agent's local HTTP server, marks the session as adoptable, and Claude responds with a takeover URL.

# Inside the Claude Code session

/sf-pause

# Claude responds:

Session paused. Share this link with your teammate:

https://sessionforge.dev/sessions/ses_a1b2c3d4e5f6

Waiting for adoption... (run /sf-resume to cancel)

The session keeps running while paused. Claude stops issuing commands but the PTY and its process tree remain fully intact.

Taking over from the dashboard

Any member of the same organization can adopt the session. In the Sessions list, adoptable sessions display a Shared badge. Clicking Adopt opens the session terminal — a full xterm.js instance connected to the live PTY with complete keyboard control. No special setup is required on the viewer's side.

Team members can also reach the session directly via the takeover URL that Claude provided.

Resuming

To revoke adoption and return control to Claude, use either method:

From Claude (inside the session):

/sf-resume

From the dashboard:

Click the Stop Sharing toggle in the session terminal header.

Use cases

Code review — Let a teammate inspect Claude's work mid-session before it continues.
Debugging — Hand off to a senior engineer when Claude is stuck on a tricky issue.
Approval gates — Claude pauses before a destructive operation; a human reviews and resumes.
Pair programming — Switch between Claude and a human driving the same live terminal.

Org admins can share or revoke any session directly from the dashboard without needing to invoke /sf-pause inside the session. This is useful for emergency handoffs or sessions where Claude is unresponsive.

Requirements

Prerequisites for running the SessionForge agent on each supported platform.

Operating System

Platform	Minimum Version
Windows	Windows 10 version 1809 or later
macOS	macOS 10.15 Catalina or later
Ubuntu / Debian	Ubuntu 18.04+ / Debian 10+
Other Linux	Most modern distros with glibc 2.17+

Windows — Terminal Environment

For the best experience on Windows, you need one of the following (in order of preference):

✓

WSL2 (recommended)

Full PTY support, best terminal compatibility. Install with: wsl --install

✓

Git for Windows (Git Bash)

Good fallback — provides a POSIX-compatible shell without WSL. Download from git-scm.com.

Without WSL2 or Git Bash, the agent falls back to raw pipe mode (no terminal features). Claude Code must be installed and on PATH — or inside WSL if using the WSL tier. For a complete walkthrough, see the Windows Setup Guide →

macOS / Linux

✓

Claude Code

npm install -g @anthropic-ai/claude-code

✓

Node.js

v18 or later (required by Claude Code)

Network

Outbound only

The agent makes outbound HTTPS connections to sessionforge.dev on port 443. No inbound ports need to be opened. Firewall rules that allow general outbound HTTPS will work without any changes.

Permissions

Windows

The agent installs as a Windows Service running under LocalSystem. Administrator access is required for the initial install. Day-to-day operation requires no elevated privileges.

macOS

Runs as the current user via launchd. No root required for install or operation.

Linux

Runs as the current user via systemd user units, or as a system service with sudo. No root required for the user-mode install.

Troubleshooting

Common issues and how to resolve them.

Windows

Session starts but no output appears

The agent is running in pipe-only mode because no terminal environment was found. Install WSL or Git Bash to enable full PTY support.

Check which tier is active:

sessionforge status

Install WSL (requires restart):

wsl --install

Service won't start

Check the agent log for the specific error. The most common cause is Claude Code not being found on PATH inside WSL.

Agent log location:

C:\Users\<you>\.sessionforge\agent.log

Access denied installing the service

Service installation on Windows requires Administrator privileges. Right-click PowerShell and select Run as Administrator, then re-run the install command.

macOS / Linux

command not found: claude

Claude Code is not installed or its global bin directory is not on your PATH.

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Add npm global bin to PATH (add to your shell profile):

export PATH="$(npm prefix -g)/bin:$PATH"

Permission denied on service install

For system-wide systemd service installation, sudo is required. Alternatively, use the user-mode install which runs under your own account with no elevated privileges.

sudo sessionforge service install

General

Machine shows offline in dashboard

The agent service has stopped. Check its status and restart it.

sessionforge service status sessionforge service start

Authentication failed / auth error

Your API key may have been revoked or expired. Generate a new key in Settings → API Keys and re-authenticate:

sessionforge auth login --key sf_live_xxxxxxxxxxxx

Session hangs and never closes

Force-stop the session by ID. You can find the session ID on the Sessions page in the dashboard, or via the CLI.

sessionforge session stop <SESSION_ID> --force

Need help?

SessionForge Docs

#Quick Start

Linux / macOS — one-liner

Windows (PowerShell) — one-liner

Manual steps

#Agent CLI Reference

#Dashboard

Machines

Sessions

Terminal (xterm.js)

API Keys

#API Keys

Creating a key

Key format

#Supported Platforms

#Supported Sessions

#Session Handoff

Prerequisites

Using /sf-pause

Taking over from the dashboard

Resuming

Use cases

#Requirements

Operating System

Windows — Terminal Environment

macOS / Linux

Network

Permissions

#Troubleshooting

Windows

macOS / Linux

General

Quick Start

Agent CLI Reference

Dashboard

API Keys

Supported Platforms

Supported Sessions

Session Handoff

Requirements

Troubleshooting