This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Deep Link Support for Electerm

Language / 语言: English | 中文

English

Electerm now supports deep li### From JavaScript

// Open link programmatically
window.location.href = 'ssh://user@server.com?title=My%20Server'

// Or open in new context
window.open('telnet://192.168.1.100:23', '_blank')

Test Links

Here are some test links you can click to verify deep link functionality:

Creating Desktop Shortcuts

Prerequisites

Before using deep links, you need to register the deeplink in the settings.

Supported Protocols

ssh:// - SSH connections
telnet:// - Telnet connections
rdp:// - Remote Desktop Protocol connections
vnc:// - VNC connections
serial:// - Serial port connections
spice:// - SPICE (Simple Protocol for Independent Computing Environments) connections
electerm:// - Electerm custom protocol (can specify connection type via type parameter)

URL Format

SSH, Telnet, RDP, and VNC

protocol://[username[:password]@]host[:port][?title=name&key=value]

Examples:

# Basic telnet connection
telnet://192.168.2.31:34554

# SSH with username
ssh://user@example.com

# SSH with username and port
ssh://admin@192.168.1.100:2222

# SSH with username, password, and custom title
ssh://user:pass@example.com:22?title=Production%20Server

# RDP connection
rdp://administrator@windows-server.local:3389

# VNC connection
vnc://192.168.1.50:5900

# SPICE connection
spice://192.168.1.60:5900

# Electerm custom protocol
electerm://user@server.com:22?type=ssh&title=My%20Server
electerm://192.168.1.100:5900?type=spice

Serial Port

serial://PORT?baudRate=RATE&dataBits=BITS&stopBits=BITS&parity=PARITY

Examples:

# Basic serial connection (default: 115200 baud, 8N1)
serial://COM1

# Custom serial settings
serial://COM3?baudRate=9600&dataBits=8&stopBits=1&parity=none

# Linux/macOS serial port
serial:///dev/ttyUSB0?baudRate=115200

Electerm Custom Protocol

The electerm:// protocol is a special protocol that allows you to specify the connection type via the type parameter.

electerm://[username[:password]@]host[:port]?type=PROTOCOL&key=value

Examples:

# SSH connection via electerm protocol
electerm://user@server.com:22?type=ssh&title=My%20Server

# SPICE connection via electerm protocol
electerm://192.168.1.60:5900?type=spice&title=My%20SPICE

# VNC connection via electerm protocol
electerm://192.168.1.50:5900?type=vnc

# Telnet connection via electerm protocol
electerm://192.168.2.31:34554?type=telnet

The type parameter defaults to ssh if not specified.

Query Parameters

You can add additional parameters to customize connections:

Parameter	Description	Example
`title`	Custom tab title	`?title=My%20Server`
`name`	Alias for title	`?name=Database`
`privateKey`	Path to SSH private key	`?privateKey=/path/to/key`
`key`	Alias for privateKey	`?key=~/.ssh/id_rsa`
`type`	Connection type for `electerm://` protocol	`?type=spice`

Usage Examples

From HTML

<!-- Click to open telnet connection -->
<a href="telnet://192.168.2.31:34554">Connect to Device</a>

<!-- SSH to production server -->
<a href="ssh://deploy@prod-server.com?title=Production">Production Server</a>

<!-- RDP to Windows machine -->
<a href="rdp://admin@192.168.1.10:3389">Windows Desktop</a>

From Command Line

# macOS/Linux
open "telnet://192.168.2.31:34554"
xdg-open "ssh://user@server.com"

# Windows
start "telnet://192.168.2.31:34554"

# Or directly with electerm
electerm "ssh://user@example.com:22"

From JavaScript

// Open link programmatically
window.location.href = 'ssh://user@server.com?title=My%20Server'

// Or open in new context
window.open('telnet://192.168.1.100:23', '_blank')

Creating Desktop Shortcuts

macOS

Create a file server.command:

#!/bin/bash
open "ssh://user@server.com?title=My%20Server"

Make it executable: chmod +x server.command

Windows

Create a file server.bat:

@echo off
start "" "ssh://user@server.com?title=My Server"

Linux

Create a file server.desktop:

[Desktop Entry]
Type=Application
Name=My Server
Exec=xdg-open "ssh://user@server.com?title=My Server"
Terminal=false

URL Encoding

Remember to URL-encode special characters in parameters:

Space → %20
@ → %40
: → %3A
/ → %2F

Example:

ssh://user@host.com?title=Production%20Server%20%231

Platform-Specific Notes

macOS

Deep links work automatically after building the app
Protocol handlers are registered via CFBundleURLTypes in Info.plist (handled by electron-builder)
Registration makes Electerm available as a handler but doesn't force it as the default
Users can choose their preferred app in System Preferences

Windows

Protocol handlers are registered during installation via NSIS installer
First-time users may see a security prompt asking for permission
If another app (like PuTTY) is already the default for ssh://, Windows will let users choose
Users can change the default app in Settings → Apps → Default apps

Linux

Protocol handlers are registered via .desktop file
May need manual setup depending on the desktop environment
Doesn't override existing handlers; users can select from available handlers

Important Note

Protocol registration is NON-INTRUSIVE: Electerm registers itself as an available handler but doesn't forcefully take over from existing applications. Users always have control over which app handles these protocols through their system settings.

Working Without Protocol Registration

You can use deep links even without registering Electerm as the default handler:

Using Command Line

# macOS - explicitly specify electerm
open -a electerm "telnet://192.168.2.31:34554"

# Linux - with full path
/usr/bin/electerm "ssh://user@host:22"

# Windows - with full path
"C:\Program Files\electerm\electerm.exe" "telnet://192.168.2.31:34554"

Right-Click in Browser

Right-click on a protocol link
Select "Open with..."
Choose Electerm (even if not the default)

Disabling Protocol Registration

If you prefer not to register Electerm for these protocols, you can:

Comment out registerDeepLink() in src/app/lib/create-app.js
Uninstall and reinstall without protocol handlers
Use system settings to remove Electerm as a handler

The deep link parsing and handling will still work; only the automatic protocol association is disabled.

Development and Testing

To test deep links in development mode, set the environment variable:

ELECTERM_REGISTER_PROTOCOLS=1 npm start

Then test with:

# macOS/Linux
open "telnet://localhost:23"

# Windows
start "telnet://localhost:23"

Security Considerations

⚠️ Warning: Be careful when sharing URLs with passwords embedded:

# NOT RECOMMENDED - password visible in URL
ssh://user:mypassword@server.com

# RECOMMENDED - let user enter password
ssh://user@server.com

For better security:

Use SSH keys instead of passwords
Don't embed credentials in URLs that might be logged or shared
Use query parameters only for non-sensitive information like titles

Troubleshooting

Links not working

Make sure Electerm is installed (not just running from source)
On Windows, reinstall to re-register protocol handlers
On Linux, check that the .desktop file is properly installed
Check Electerm logs for parsing errors

Opening in wrong application

Check default application settings in your OS
Right-click a link and select "Open with Electerm"
Set Electerm as default for these protocols in system settings

URL parsing errors

Check that the URL is properly formatted
Use URL encoding for special characters
Check Electerm logs for detailed error messages

Implementation Details

Deep link support is implemented via:

src/app/lib/deep-link.js - Core deep link handling
src/app/lib/create-app.js - Protocol registration and event handlers
build/electron-builder.json - Protocol declarations for electron-builder

The implementation handles:

Protocol URL parsing and validation
Cross-platform protocol registration
Single instance behavior (focuses existing window)
Graceful fallback if parsing fails

Deep Link Support for Electerm (CN)

Electerm 现在支持深度链接（协议 URL），允许从浏览器、其他应用程序或脚本直接打开连接。此功能允许您创建可点击的链接，自动在 Electerm 中打开连接。

先决条件

在使用深度链接之前，您需要在设置中注册深度链接。

支持的协议

ssh:// - SSH 连接
telnet:// - Telnet 连接
rdp:// - 远程桌面协议连接
vnc:// - VNC 连接
serial:// - 串口连接
spice:// - SPICE（独立计算环境简单协议）连接
electerm:// - Electerm 自定义协议（可通过 type 参数指定连接类型）

URL 格式

SSH、Telnet、RDP 和 VNC

protocol://[username[:password]@]host[:port][?title=name&key=value]

例子：

# 基本 telnet 连接
telnet://192.168.2.31:34554

# 带用户名的 SSH
ssh://user@example.com

# 带用户名和端口的 SSH
ssh://admin@192.168.1.100:2222

# 带用户名、密码和自定义标题的 SSH
ssh://user:pass@example.com:22?title=Production%20Server

# RDP 连接
rdp://administrator@windows-server.local:3389

# VNC 连接
vnc://192.168.1.50:5900

# SPICE 连接
spice://192.168.1.60:5900

# Electerm 自定义协议
electerm://user@server.com:22?type=ssh&title=My%20Server
electerm://192.168.1.100:5900?type=spice

串口

serial://PORT?baudRate=RATE&dataBits=BITS&stopBits=BITS&parity=PARITY

例子：

# 基本串口连接（默认：115200 波特率，8N1）
serial://COM1

# 自定义串口设置
serial://COM3?baudRate=9600&dataBits=8&stopBits=1&parity=none

# Linux/macOS 串口
serial:///dev/ttyUSB0?baudRate=115200

Electerm 自定义协议

electerm:// 协议是一个特殊协议，允许您通过 type 参数指定连接类型。

electerm://[username[:password]@]host[:port]?type=PROTOCOL&key=value

例子：

# 通过 electerm 协议建立 SSH 连接
electerm://user@server.com:22?type=ssh&title=My%20Server

# 通过 electerm 协议建立 SPICE 连接
electerm://192.168.1.60:5900?type=spice&title=My%20SPICE

# 通过 electerm 协议建立 VNC 连接
electerm://192.168.1.50:5900?type=vnc

# 通过 electerm 协议建立 Telnet 连接
electerm://192.168.2.31:34554?type=telnet

如果未指定 type 参数，默认为 ssh。

查询参数

您可以添加额外参数来自定义连接：

参数	描述	例子
`title`	自定义标签标题	`?title=My%20Server`
`name`	title 的别名	`?name=Database`
`privateKey`	SSH 私钥路径	`?privateKey=/path/to/key`
`key`	privateKey 的别名	`?key=~/.ssh/id_rsa`
`type`	`electerm://` 协议的连接类型	`?type=spice`

使用例子

从 HTML

<!-- 点击打开 telnet 连接 -->
<a href="telnet://192.168.2.31:34554">连接到设备</a>

<!-- SSH 到生产服务器 -->
<a href="ssh://deploy@prod-server.com?title=Production">生产服务器</a>

<!-- RDP 到 Windows 机器 -->
<a href="rdp://admin@192.168.1.10:3389">Windows 桌面</a>

从命令行

# macOS/Linux
open "telnet://192.168.2.31:34554"
xdg-open "ssh://user@server.com"

# Windows
start "telnet://192.168.2.31:34554"

# 或直接使用 electerm
electerm "ssh://user@example.com:22"

从 JavaScript

// 以编程方式打开链接
window.location.href = 'ssh://user@server.com?title=My%20Server'

// 或在新上下文中打开
window.open('telnet://192.168.1.100:23', '_blank')

测试鏈接

以下是一些您可以点击的测试链接，以验证深度链接功能：

创建桌面快捷方式

macOS

创建文件 server.command：

#!/bin/bash
open "ssh://user@server.com?title=My%20Server"

使其可执行：chmod +x server.command

Windows

创建文件 server.bat：

@echo off
start "" "ssh://user@server.com?title=My Server"

Linux

创建文件 server.desktop：

[Desktop Entry]
Type=Application
Name=My Server
Exec=xdg-open "ssh://user@server.com?title=My Server"
Terminal=false

URL 编码

记住对参数中的特殊字符进行 URL 编码：

空格 → %20
@ → %40
: → %3A
/ → %2F

例子：

ssh://user@host.com?title=Production%20Server%20%231

平台特定说明

macOS

构建应用后，深度链接自动工作
协议处理程序通过 Info.plist 中的 CFBundleURLTypes 注册（由 electron-builder 处理）
注册使 Electerm 可用作为处理程序，但不强制其为默认
用户可以在系统偏好设置中选择首选应用

Windows

协议处理程序通过 NSIS 安装程序在安装期间注册
首次用户可能会看到安全提示，要求权限
如果另一个应用（如 PuTTY）已经是 ssh:// 的默认，Windows 将让用户选择
用户可以在设置 → 应用 → 默认应用中更改默认应用

Linux

协议处理程序通过 .desktop 文件注册
根据桌面环境可能需要手动设置
不覆盖现有处理程序；用户可以从可用处理程序中选择

重要说明

协议注册是非侵入性的：Electerm 将自己注册为可用处理程序，但不会强制从现有应用程序接管。用户始终可以通过系统设置控制哪个应用处理这些协议。

无需协议注册工作

即使不将 Electerm 注册为默认处理程序，您也可以使用深度链接：

使用命令行

# macOS - 明确指定 electerm
open -a electerm "telnet://192.168.2.31:34554"

# Linux - 带完整路径
/usr/bin/electerm "ssh://user@host:22"

# Windows - 带完整路径
"C:\Program Files\electerm\electerm.exe" "telnet://192.168.2.31:34554"

在浏览器中右键单击

右键单击协议链接
选择 "Open with..."
选择 Electerm（即使不是默认）

禁用协议注册

如果您不想为这些协议注册 Electerm，您可以：

在 src/app/lib/create-app.js 中注释掉 registerDeepLink()
卸载并重新安装而不带协议处理程序
使用系统设置删除 Electerm 作为处理程序

深度链接解析和处理仍将工作；只有自动协议关联被禁用。

开发和测试

要在开发模式下测试深度链接，请设置环境变量：

ELECTERM_REGISTER_PROTOCOLS=1 npm start

然后测试：

# macOS/Linux
open "telnet://localhost:23"

# Windows
start "telnet://localhost:23"

安全考虑

⚠️ 警告： 在共享包含密码的 URL 时要小心：

# 不推荐 - URL 中可见密码
ssh://user:mypassword@server.com

# 推荐 - 让用户输入密码
ssh://user@server.com

为了更好的安全性：

使用 SSH 密钥而不是密码
不要在可能被记录或共享的 URL 中嵌入凭据
仅对非敏感信息（如标题）使用查询参数

中文

故障排除

链接不工作

确保 Electerm 已安装（不是从源代码运行）
在 Windows 上，重新安装以重新注册协议处理程序
在 Linux 上，检查 .desktop 文件是否正确安装
检查 Electerm 日志以查找解析错误

在错误应用程序中打开

检查操作系统中的默认应用程序设置
右键单击链接并选择 "Open with Electerm"
在系统设置中将 Electerm 设置为这些协议的默认

URL 解析错误

检查 URL 是否正确格式化
对特殊字符使用 URL 编码
检查 Electerm 日志以获取详细错误消息

实现细节

深度链接支持通过以下实现：

src/app/lib/deep-link.js - 核心深度链接处理
src/app/lib/create-app.js - 协议注册和事件处理程序
build/electron-builder.json - electron-builder 的协议声明

实现处理：

协议 URL 解析和验证
跨平台协议注册
单实例行为（聚焦现有窗口）
如果解析失败，则优雅回退