English | 中文

RemoteConn

RemoteConn is a production-oriented remote access workspace built around shell + chat. It targets Web, mobile app, and Mini Program entry points, so AI-assisted server work can start from a phone and stay attached to the right project context.

The project focuses on three practical problems:

1. Keep an AI-capable shell available on mobile, not only on desktop IDEs.
2. Use voice input to reduce typing cost on phones.
3. Preserve task context, records, and server bindings so long-running work can continue without handoff friction.

Monorepo Structure

• apps/web: Vue 3 + TypeScript + xterm.js frontend
• apps/gateway: Node.js gateway for WSS -> SSH
• packages/shared: shared models, state machines, Codex orchestration, theme and security helpers
• packages/plugin-runtime: plugin runtime with validation, permission control, lifecycle hooks, isolation, and circuit breaking
• ios/plugin/RemoteConnSSHPlugin: Capacitor iOS SSH plugin skeleton

Implemented Capabilities

1. Server and credential management with restricted local storage
2. Terminal session state machine for connect, reconnect, auth pending, and error states
3. Bidirectional gateway forwarding for init/stdin/stdout/stderr/resize/control
4. Codex launch orchestration with remote environment checks
5. Session logging and redacted export
6. Theme system with contrast tuning
7. Plugin runtime foundation

Latest Status

Current README baseline: v3.0.1 on 2026-03-20.

Recent milestones:

• v3.0.1: Mini Program manual was expanded with image-based guidance, theme presets were aligned with Web to 21 sets, and the project docs were synchronized.
• v3.0.0: Terminal interaction stability was improved during Codex output, including caret stability and keyboard-focus handling.
• Cross-device sync currently covers settings, servers, and records. Sensitive server fields remain encrypted as secret_blob.

Known limitations still tracked in the project docs:

• Some Mini Program terminal performance issues can still appear during long AI output sessions.
• Voice playback extraction and turn detection are not yet considered stable enough for default use.

For the full Chinese product narrative and detailed historical notes, see README_cn.md, CHANGELOG.md, and release.md.

Operation Guide

This guide reuses the five annotated screenshots from the project introduction and keeps the same visual grouping so the main workflow can be understood directly from the README.

For the narrow vertical mobile layout version, see Mobile Operation Guide.

1. Server List And Configuration

1. The home page opens on the server list, which is the starting point of the product.
2. The top toolbar is used to add, delete, select, and search servers.
3. The main body of each server card opens the configuration page; the quick actions on the right can duplicate a profile, launch AI, or connect directly.
4. The bottom navigation switches between terminal, logs, records, settings, and about pages.
5. The configuration page is where you fill in the basic connection fields, authentication method, and project directory.
6. AI Working Directory defines the default project context for AI startup and is a key part of the collaboration flow.
7. If the target host is reached through a jump host, complete the jump-host fields and its separate authentication settings on the same page.
8. The recommended order is to save the profile first and then start the connection.

2. Terminal, AI, And Connection Diagnostics

1. After entering the terminal, you can run shell commands directly or switch to an AI workflow such as Codex from the top-left entry.
2. The top status bar continuously shows connection state, latency, and session overview, making it the primary feedback area for mobile troubleshooting.
3. Tapping Connected opens the session detail panel with the target host, connection state, and working directory.
4. Tapping Latency opens the diagnostics panel so you can inspect gateway response and network latency trends and judge link quality.

3. Voice Input And Shortcut Panel

1. The voice button at the bottom of the terminal page opens the voice input panel, supporting a "speak first, decide later" input flow.
2. The voice draft can be sent to the terminal directly or saved as a record together with category tags.
3. The keyboard button at the bottom opens the shortcut panel to restore terminal control keys that are missing on mobile.
4. The right-side shortcut panel includes arrow keys, Esc, Ctrl+C, Tab, and other high-frequency controls to reduce input friction on phones.

4. Settings Center

1. The settings page is grouped into UI / Terminal / Connection / Records, covering appearance, terminal behavior, connection policy, and data management.
2. The UI tab controls theme, colors, and language, which shape the overall experience.
3. The terminal tab controls font family, font size, line height, and terminal palette, directly affecting readability and typing efficiency.
4. The connection tab controls default authentication, reconnect strategy, background keepalive, sync switches, and AI defaults.
5. The records tab controls record retention and category management so the information lifecycle stays structured.

5. Records And About

1. The records page is used to capture issues, ideas, TODOs, and context fragments.
2. The top area supports search and category filtering so content can be found quickly.
3. Record cards support actions such as copy, mark, and delete.
4. The bottom area provides pagination, add, and export operations.
5. The about page centralizes the brand, version, and product information entry points.
6. It collects the user guide, feedback channel, privacy policy, change log, and about content in one place.
7. Its role is to act as the final landing page for product documentation inside the app, so users can find a consistent explanation without leaving the product.

Quick Start

npm install
npm run dev:gateway
npm run dev:web

Default endpoints:

• Web: http://localhost:5173
• Gateway: http://localhost:8787
• Gateway WS: ws://localhost:8787/ws/terminal

Environment Variables

Gateway

cp apps/gateway/.env.example apps/gateway/.env

Recommended runtime config:

PORT=8787
HOST=0.0.0.0
GATEWAY_TOKEN=replace-with-strong-random-token
CORS_ORIGIN=https://your-domain.com
DEBUG_IO_HEX=0
ASR_INCLUDE_RAW_RESULT=0
ASR_EMPTY_TEXT_WARN_LIMIT=3

Web

cp apps/web/.env.example apps/web/.env

Build-time config:

VITE_GATEWAY_URL=wss://your-domain.com
VITE_GATEWAY_TOKEN=replace-with-strong-random-token
VITE_ENABLE_PLUGIN_RUNTIME=false

Notes:

• VITE_GATEWAY_TOKEN must match GATEWAY_TOKEN.
• VITE_ENABLE_PLUGIN_RUNTIME=false is the recommended initial production posture if plugin support is not needed yet.
• If you expose the service through Nginx or Caddy on 443/80, the internal gateway can still listen on 8787.

Quality Commands

npm run typecheck
npm run lint
npm run test

Gateway Operations

Unified script: scripts/gatewayctl.sh

# First-time deployment
scripts/gatewayctl.sh ensure-env
scripts/gatewayctl.sh install-service $USER
scripts/gatewayctl.sh deploy

# Daily operations
scripts/gatewayctl.sh status
scripts/gatewayctl.sh logs 200
scripts/gatewayctl.sh logs-clear
scripts/gatewayctl.sh restart
scripts/gatewayctl.sh health

# Foreground local run
scripts/gatewayctl.sh run-local

• Linux uses systemd.
• macOS uses launchd at ~/Library/LaunchAgents/com.remoteconn.gateway.plist.

Logs

launchctl print gui/$(id -u)/com.remoteconn.gateway | rg -n "stdout path|stderr path"
tail -f /Users/gavin/Library/Logs/com.remoteconn.gateway.out.log

Benchmarks

Gateway SSH2 baseline:

npm --workspace @remoteconn/gateway run bench

Example with explicit parameters:

BENCH_SSH_HOST=127.0.0.1 \
BENCH_SSH_PORT=22 \
BENCH_SSH_USER="$USER" \
BENCH_PRIVATE_KEY=~/.ssh/id_ed25519 \
BENCH_ITERATIONS=30 \
BENCH_PAYLOAD_KB=1024 \
npm --workspace @remoteconn/gateway run bench

TTYD baseline:

ttyd -v

BENCH_SSH_HOST=127.0.0.1 \
BENCH_SSH_PORT=22 \
BENCH_SSH_USER="$USER" \
BENCH_SSH_IDENTITY=~/.ssh/id_ed25519 \
BENCH_ITERATIONS=30 \
BENCH_PAYLOAD_KB=1024 \
npm --workspace @remoteconn/gateway run bench:ttyd

Related Documents

• docs/server-management-ux-iteration-2026-02-25.md
• docs/terminal-voice-input-plan-2026-02-26.md
• docs/web-storage-layering-guideline-2026-02-25.md
• docs/touch-focus-state-machine-plan-2026-02-23.md
• CHANGELOG.md
• release.md