PuTTrY

npm version License: MIT Node.js TypeScript

A secure, browser-based terminal that keeps your server sessions alive across devices and networks. Work seamlessly across your phone, laptop, and desktop without restarting your processes.

Table of Contents

Project Website

For more information about PuTTrY, visit the official website at puttry.io, which features:

What is PuTTrY?

PuTTrY is a single-user, web-based terminal emulator that runs on your server, allowing you to access and control your terminal sessions from any browser. Unlike traditional SSH clients, PuTTrY decouples the terminal interface from your SSH credentials—your server sessions persist independently of which device you’re using, and your security is managed centrally at the backend.

Single-User Per Instance

PuTTrY is designed to be run by a single user in their home directory. Each terminal session created via PuTTrY inherits the permissions of the user who started it—exactly the same as SSH. If multiple users on the same server want to use PuTTrY, each must run their own separate instance in their respective home directory. Multiple PuTTrY instances on the same server require different host ports. PuTTrY supports secure guest access via Guest Links, allowing colleagues to observe or request control of terminal sessions without sharing your credentials. Its core design is as a personal terminal for one user across many devices.

Perfect For

About the name: PuTTrY is a homage to PuTTY, the pioneering SSH client created in the late 1990s that revolutionized terminal access for countless users. While PuTTrY takes a fundamentally different approach—shifting from desktop client to web-based backend—we honor the technical innovation and reliability that made PuTTY indispensable for decades. Some people still use PuTTY today. This project builds on the foundation of solutions that worked seamlessly across generations of computing.

Web Interface Overview

The left screenshot shows the sidebar expanded, allowing you to manage terminal sessions—rename tabs, reorder them, and switch between active sessions. The right screenshot shows the sidebar collapsed for maximum terminal viewing area when you need full screen real estate.

PuTTrY Web Interface - Terminal Sessions PuTTrY Web Interface - Authentication

Works Great on Mobile Too

PuTTrY is fully optimized for mobile browsers. Both screenshots illustrate mobile shell interactions—direct terminal access and interactive CLI applications.

PuTTrY Mobile - Floating Keyboard PuTTrY Mobile - Full Terminal Session

Why Web-Based Over SSH?

SSH is a battle-tested tool that’s been securing remote access for decades. But it’s not designed for effortless access from anywhere—it requires upfront setup and key management on every device you want to use.

Session Continuity Across Devices

SSH ties your terminal to your client machine. Each connection is independent—if you close your laptop, your SSH session dies, even if your background process is still running on the server.

With PuTTrY, your terminal session lives on the server, independent of which device you’re using:

The process keeps running. The shell state persists. Only your browser window changes.

Quick, Device-Agnostic Login

SSH requires setup before your first connection: generate keys, distribute public keys, configure ~/.ssh/config, handle different key locations on different machines. It’s powerful, but not quick.

PuTTrY gets you connected with one password, anywhere. Your phone, a tablet, a borrowed laptop, a machine you’ve never used before—just open a browser and authenticate. No keys to distribute. No setup per device.

Mobile-Friendly

SSH on mobile is awkward:

PuTTrY is designed for the browser. Authenticate once, get a session token in a cookie, and continue working. Your session password lives on the server, not on your device.

Network Security and Infrastructure Flexibility

Exposing SSH to the internet for external access is a significant security concern. SSH servers are frequently targeted by automated attacks, and managing firewall rules and key distribution at scale creates operational risk.

PuTTrY, running as a standard web backend, can be protected using the same mature infrastructure security tooling available for any modern web application:

You don’t need to expose a new port to the internet or manage a separate SSH hardening strategy. PuTTrY integrates into your existing web security infrastructure.

For comprehensive guidance on HTTPS, certificate management, VPN tunneling, reverse proxies, and other deployment strategies, see Network and Infrastructure Security.

Getting Started

Prerequisites

Before installing PuTTrY, ensure you have:

Step 1: Install

Install PuTTrY globally using npm:

npm install -g @chfischerx/puttry

Note: The -g flag is required. The install snippet shown on the npmjs.com package page omits it — using npm i @chfischerx/puttry without -g installs the package locally and the puttry command will not be available in your shell.

Run the interactive configuration wizard to set up PuTTrY for your environment:

puttry configure

This walks you through setting up:

Note: Configuration is optional—PuTTrY works with defaults out of the box. However, running puttry configure first ensures the setup matches your environment.

Settings can be changed anytime via the Web UI settings panel or the puttry config set command.

Step 3: Start

Start the PuTTrY server:

puttry start

PuTTrY will display:

Open the URL in your browser to access the web interface. You’re ready to create terminal sessions!

User Guide

Once PuTTrY is running, the User Guide walks you through every feature of the web interface:

Start with the User Guide to learn how to use PuTTrY effectively.

Configuration Reference

Configuration Files and Directories

On first run, PuTTrY creates a .puttry directory in your home folder containing:

Web Settings

Manage your PuTTrY instance directly in the browser. The left screenshot shows general settings like port and password configuration. The right screenshot shows authentication options including TOTP 2FA and passkey setup for securing your instance.

PuTTrY Settings - Security Configuration PuTTrY Settings - 2FA Configuration

Port Configuration

Each PuTTrY instance requires a unique port. If multiple users on the same server want to run PuTTrY, each must run their own separate instance in their respective home directory with a different port number.

For example:

You can set the port during puttry configure or later with puttry config set PORT 5175.

Environment Variables

You can customize PuTTrY’s behavior by setting environment variables. A full list of supported environment variables is available in .env.example.

For a complete production deployment guide including systemd setup, full environment variable reference, monitoring, and backup strategies, see docs/PRODUCTION.md.

CLI Commands

PuTTrY includes a built-in CLI tool for server management and configuration:

puttry <command>

Server Management

Password Management

TOTP Management

Passkey Management

Configuration

Help

Managing Terminal Sessions

Creating and Deleting Sessions

PuTTrY allows you to create multiple independent terminal sessions via the Web UI. Each session is a separate terminal session running on your server. You can create, switch between, and delete sessions as needed—perfect for organizing work across different tasks.

Parallel Browser Connections

Multiple browsers (or tabs) can connect to the same terminal session simultaneously:

Write Lock and Control

PuTTrY implements a per-shell write lock to coordinate input:

This design prevents simultaneous keyboard input from multiple sources from corrupting shell state or producing unpredictable results.

PuTTrY supports secure guest access via Guest Links—one-time invite URLs that allow colleagues to observe your terminal sessions without requiring your credentials.

From the top toolbar, click the guest icon (👥) to open the Guest Links panel:

  1. Enter a descriptive name for the invite (e.g., “Debug session”, “Support access”)
  2. Click Create Link
  3. Copy the generated invite URL and share it with your colleague

Each link is unique and one-time use—once redeemed, the guest gains access to your terminal sessions. The link itself expires if not redeemed, and you can revoke it at any time from the Guest Links panel.

PuTTrY - Guest Links Panel

Guest View and Control Flow

When a colleague opens your Guest Link:

  1. Observer mode (read-only): They see all your terminal sessions and can watch output in real-time, but cannot type or send input
  2. Requesting control: If they want to interact with a session, they can click the session and select “Request Control”
  3. Approval dialog: You see a notification and a dialog asking you to approve or deny the request
  4. Control granted: If approved, the guest receives write access to that session. If denied, they remain in read-only mode

The same write lock mechanism applies: only one browser (guest or owner) can control a session at a time. The guest can take the lock, and you can reclaim it at any time.

Revoking Guest Access

From the Guest Links panel, you can:

Guest sessions expire automatically after 4 hours of inactivity.

Security Notes

File Manager

PuTTrY includes an integrated file manager for uploading and downloading files directly from your browser without needing to use command-line tools like scp or rsync.

Upload

Drag and drop or open a file picker to upload files from your local machine:

PuTTrY File Manager - Upload Interface

Download (File Browser)

Navigate your server’s files directly from the browser:

PuTTrY File Manager - File Explorer

Security

All file operations are restricted to your home directory ($HOME). Path traversal attacks are blocked server-side—you cannot navigate to parent directories or access files outside your home folder. Your file permissions are respected: PuTTrY uses your user’s Unix permissions to determine what you can read and write.

Security Architecture

How PuTTrY Secures Access

SSH’s security model is sound, but managing keys across multiple machines creates friction and sprawl. Every device that needs access requires its own key configuration, and revoking access means key rotation everywhere.

PuTTrY uses a simpler model: one password per PuTTrY instance, managed on the backend.

Session Password

Your PuTTrY instance is protected by a session password—a persistent credential that grants access to the PuTTrY backend itself. This password:

Once authenticated, your browser receives a session token (stored in a cookie). You stay logged in across multiple browser tabs, devices, and sessions—until you explicitly log out or your token expires.

Multi-Factor Authentication (2FA)

For additional security, you can require 2FA on top of your session password:

TOTP (Time-Based One-Time Password)

Passkey

Why This Works Better Than Key Distribution

Your security is managed centrally on the server, not scattered across machines.

For detailed security architecture information (authentication mechanisms, session management, web application security mitigations, threat model, and on-disk security), see Security Architecture.

Network and Infrastructure Security

PuTTrY’s built-in authentication (session password, 2FA, and passkeys) protects your instance at the application level. However, your server must accept incoming network connections to be reachable from browsers. Depending on your deployment scenario—personal use on a private network, shared infrastructure, or internet-facing production—you’ll need different infrastructure-level security measures.

Key considerations:

For comprehensive guidance on HTTPS setup, certificate management, VPN tunneling, reverse proxy configuration, and bastion host architecture, see Network and Infrastructure Security.

Technical Architecture

PuTTrY is built on a foundation of battle-tested technologies:

For detailed technical documentation on shell process management, WebSocket communication patterns, buffer management, and write locking, see Technical Architecture.

Development

PuTTrY is built with modern full-stack tooling: React with TypeScript on the frontend, Express on the backend, and a custom Vite plugin that integrates both seamlessly in development.

Quick start:

npm install
npm run dev

The dev server runs on http://localhost:5175 with hot module reloading (HMR) for both frontend and backend. React components update instantly; server code changes may require a refresh. The Vite plugin mounts Express as middleware and handles WebSocket upgrades for real-time terminal I/O.

Key development workflows:

Project structure:

The custom Vite plugin (vite-plugin.ts) handles the Express integration and WebSocket upgrades for /sync (session coordination) and /terminal/:sessionId (PTY I/O).

For comprehensive development documentation including setup, project structure, build processes, debugging techniques, and performance considerations, see Development.

Contributing

PuTTrY is currently feature complete for its intended purpose: remote shell access and file transfer via a browser. The goal is to keep it slim and focused — not to grow it into a general-purpose platform.

That said, contributions are welcome in the areas that matter most:

Before Opening a Pull Request

  1. Open an issue first if you’re working on anything beyond a small bugfix, so there’s alignment before effort is spent.
  2. Run tests with npm test and make sure they all pass.
  3. Keep changes focused — small, targeted PRs are much easier to review than large ones.

Feedback, suggestions, and ideas are always welcome even without a code contribution.

Connect

Follow me on LinkedIn for updates on PuTTrY and other projects.

License

MIT — see LICENSE for details.