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
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. Browseapp/lib/providers/ and app/lib/services/ for the rest.
Navigation
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 throughflutter_rust_bridge:
packages/yourssh_rdpwraps IronRDP. The first connection to an unpinned host stops before credentials are sent, so the user can pin the certificate first.packages/yourssh_vncis the VNC client.
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.Host-key verification
Host-key verification
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).Credential storage
Credential storage
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.Sync encryption
Sync encryption
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.
CLI endpoint
CLI endpoint
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.Plugin sandbox
Plugin sandbox
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
showYsToastfor toasts andshowYsDialogorshowYsConfirmfor dialogs. - Use
YsColorstokens, notColor(0x...)literals in widgets. tool/check_ui_lint.shenforces this in CI. See Contributing.
Where to go next
Build from source
Toolchain, run, test and CI.
Plugin system
Dart and JavaScript plugins.