Skip to main content
YourSSH is a Flutter app for macOS, Windows, Linux and Android. The desktop app is the main product; a smaller mobile UI (SSH only) ships on Android. This page is a map of the code, not a class reference. Follow the links to the source when you need detail.
The repository’s CLAUDE.md is the detailed, always-current reference for every subsystem. Use this page to find your way, then read CLAUDE.md for the specifics.

Monorepo layout

The three forks (dartssh2, xterm, flutter_pty) and every yourssh_* package are wired in through dependency_overrides in app/pubspec.yaml. A change in packages/ shows up in the app immediately; there is nothing to publish. Each fork carries specific patches, listed in CLAUDE.md. If you change a fork, explain in your pull request why the fix can’t live in app/.

Data flow

main.dart creates the services and long-lived providers once, connects them with callbacks (key lookup, host-key verification, sync on change), then mounts MainScreen under a MultiProvider. Widgets read state from providers and never talk to services directly.

Providers and services

These are the ones you meet first. Browse app/lib/providers/ and app/lib/services/ for the rest. MainScreen (app/lib/screens/main_screen.dart) renders a top tab bar and a left sidebar, both under app/lib/screens/shell/. The sidebar maps each NavSection (hosts, keychain, port forwarding, SFTP, known hosts, recordings, audit, settings, plugins) to a top-level screen under app/lib/widgets/. The host editor is a single side panel, HostDetailPanel, with an SSH / RDP / VNC switch at the top.

Remote desktop

RDP and VNC run in Rust and are loaded as native libraries through flutter_rust_bridge:
  • packages/yourssh_rdp wraps IronRDP. The first connection to an unpinned host stops before credentials are sent, so the user can pin the certificate first.
  • packages/yourssh_vnc is the VNC client.
The libraries load lazily on the first RDP or VNC connection. They are not tracked in git; see Build from source.

Plugins

Two kinds coexist: Dart plugins compiled into the app, and JavaScript plugins loaded from disk at runtime. See Plugin system.

Security-relevant design

These behaviours are part of the product’s security model. Keep them intact when you change nearby code.
KnownHostsProvider pins one key per host, port and key type. An unknown endpoint is accepted on first use after the user confirms it. If a host already pinned under one key type presents a key of a new type, the app shows a blocking “Host key type changed” prompt, so a man-in-the-middle can’t slip past by offering a different algorithm. RDP works the same way with certificate fingerprints, checked before any credentials are sent. The dialogs live in tofu_dialogs.dart and focus the safe choice by default. The dartssh2 fork also implements strict key exchange (the Terrapin mitigation).
StorageService writes passwords, key passphrases and the sync passphrase to the system credential store first (macOS Keychain or Windows Credential Manager). Only if that fails does it fall back to SharedPreferences, and the fallback is visible in Settings and the notification bell. On every launch the app tries to move leftover plaintext secrets into the store, confirming each write before it removes the old copy.
Cloud sync is opt-in. A 12-character sync code is the only secret: it derives the AES-256-GCM key through PBKDF2-HMAC-SHA256, and the Supabase row id is a one-way hash of it, so the code is never stored server-side. A pulled payload is applied only if its authenticated inner timestamp is newer than the last push and the last applied payload, which prevents rollback. LAN sync uses a random 32-byte key carried in a QR code, and the one-shot server closes after one transfer. Terminal sharing encrypts every message with a key derived from the share code.
The yourssh command talks to the running app over a Unix socket (macOS, Linux) or a named pipe (Windows). The run directory is private to the user, the app rejects any peer with a different user id or SID, and a fresh random token is written at every launch and compared in constant time. A lock file makes the app single-instance. The yourssh://connect/... URL scheme only opens saved hosts.
JavaScript plugins run in an isolated QuickJS context with declared permissions, user consent bound to file hashes, execution limits and a circuit breaker. Details are in Plugin system.

Design system

The app is dark only. packages/yourssh_ui wraps forui (the “Amber Brand” theme) and re-exports it, so app code imports package:yourssh_ui/yourssh_ui.dart and gets the F* widgets, Lucide icons and the Ys* tokens (YsColors, YsSpace, YsRadius) and components (YsHostCard, YsFileTable, YsStatusBar, YsTab, YsPluginHost). The rules for contributors:
  • Build new or rebuilt UI from forui widgets or Ys* components, not hand-styled Material.
  • Use showYsToast for toasts and showYsDialog or showYsConfirm for dialogs.
  • Use YsColors tokens, not Color(0x...) literals in widgets.
  • tool/check_ui_lint.sh enforces this in CI. See Contributing.

Where to go next

Build from source

Toolchain, run, test and CI.

Plugin system

Dart and JavaScript plugins.