chandler

A remote shell tool that lets you connect from your Mac to your PC and run commands like git, npm, etc.

Installation

npm install -g chandler

Or use with npx (no installation required):

npx chandler

Requirements

• mDNS support for auto-discovery:
  • macOS: Built-in (Bonjour)
  • Windows: Requires Bonjour Print Services or iTunes installed
  • Linux: Requires Avahi daemon (sudo apt-get install avahi-daemon on Ubuntu/Debian)

Usage

Start a host (on your PC or Mac)

npx chandler host

This will start a WebSocket server, advertise it via mDNS, and display connection options:

✓ Chandler host started
Listening on: 0.0.0.0:4818
Local IP: 192.168.1.100
Hostname: my-computer
✓ Broadcasting via mDNS (auto-discovery enabled)

🔐 Connection PIN: 1234
Share this PIN with clients to allow connections

Connection options:
  Auto-discover: npx chandler connect
  Direct: npx chandler connect 192.168.1.100:4818

Waiting for connections...

The host generates a random 4-digit PIN that clients must enter to connect. After 10 failed authentication attempts, the server automatically shuts down for security.

Connect to the host

Option 1: Auto-discovery (recommended)

Just run the connect command without an address, and Chandler will find available hosts:

npx chandler connect

You'll see a menu to select from discovered hosts:

🔍 Searching for Chandler hosts on the network...

✓ Found: my-computer at 192.168.1.100:4818

? Select a host to connect to: ›
❯ 🪟 my-computer (192.168.1.100:4818 - win32)
  🍎 laptop (192.168.1.101:4818 - darwin)

Connecting to 192.168.1.100:4818...
✓ Connected to host
Waiting for authentication request...

🔐 Enter PIN to connect: ****
✓ Authentication successful!
Type your commands below. Press Ctrl+C to exit.

Option 2: Direct connection

If you know the IP address and port:

npx chandler connect 192.168.1.100:4818

Once connected, you can run any shell commands on the remote machine:

git status
npm install
ls -la

Forward a host port back to your local machine

While you are connected to a host, you can create a session-scoped TCP tunnel from the remote shell itself:

chandler forward 3000

That command runs on the host, asks the active Chandler session to open a local listener on the client machine, and prints the actual local bind:

✓ 127.0.0.1:3000 -> host 127.0.0.1:3000

If the same local port is already taken on the client, Chandler falls back to an ephemeral port:

chandler forward 3000
# ✓ 127.0.0.1:49152 -> host 127.0.0.1:3000

You can also request a specific local port:

chandler forward 3000 8080

List or close tunnels from the same remote shell session:

chandler tunnels
chandler unforward 8080

Notes:

• Tunnels bind only to 127.0.0.1 on the client machine.
• Tunnels proxy TCP traffic to 127.0.0.1:<remotePort> on the host machine.
• Tunnels exist only for the current chandler connect session and are removed when the session disconnects.

Options

Host command:

• -p, --port <port> - Port to listen on (default: 4818)

npx chandler host --port 3000

Session tunnel commands:

• forward <remotePort> [localPort] - Forward host 127.0.0.1:<remotePort> to a client-local port
• tunnels - List active tunnels for the current Chandler session
• unforward <localPort> - Close a tunnel by its client-local port

How it works

Chandler creates a WebSocket connection between two machines:

1. The host machine starts a WebSocket server and spawns a shell
2. The host advertises itself via mDNS/Bonjour for auto-discovery
3. The client discovers available hosts or connects directly
4. All input from the client is sent to the remote shell
5. All output from the remote shell is sent back to the client
6. It acts as a reverse proxy for shell commands

Features

• Auto-discovery: Hosts are automatically discovered on the local network using mDNS
• PIN Authentication: Secure connections with a randomly generated 4-digit PIN
• Cross-platform: Works on Windows, macOS, and Linux
• Interactive selection: Choose from multiple discovered hosts with a TUI
• Direct connection: Can connect directly if you know the IP and port
• Real-time: Streams shell output in real-time
• Security: Automatic shutdown after 10 failed authentication attempts

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev -- host
npm run dev -- connect 192.168.1.100:4818

License

ISC