Go Green Transit — User Guide¶

Desktop FTP / SFTP / WebDAV / S3 / Azure Blob / GCS client, with a local bridge on 127.0.0.1:7878 for other Go Green tools to consume.

This guide covers only how to use the app. For API details see API.md; for the architecture see IMPLEMENTATION.md.

1. Window layout¶

Top to bottom:

Native OS menubar — File, Edit, View, Transfer, Server, Bookmarks, Help. Rendered by Windows, always at the top of the window.
Brand row — Go Green Paperless Initiative logo · GoGreen Transit · one-liner · bridge status chip on the right.
Session tabs strip — each connected protocol has its own tab with a coloured chip, the host label, and a close × . + opens a new empty session slot.
Protocol accent palette — six swatches (SFTP, FTP, WebDAV, S3, Azure, GCS). Click any to preview how the UI retints for that protocol, including the workspace layout (see §5).
Shell — the main console card:
Shell-head: protocol badge · live/disconnected meta
Action bar: Connect… / Sites… / Disconnect / Upload / Download / New folder / Rename / Delete / Verify hash / Compare dirs / Refresh, plus a channel/type/TLS mode-rail
Workspace: Local pane · Transit lane · Remote pane (or just Remote pane for object-store protocols)
Queue pill strip: active + queued + done + failed transfers
Wire protocol console: live tx/rx/sys log
Status bar: connection · bridge · sessions · concurrency · throughput · p50/p95 latency · activity lights
Design-note footnote at the very bottom.

2. Connecting to a server¶

Three entry points, all equivalent:

Path	When to use
Action bar → Connect… (SFTP / FTP / FTPS / WebDAV / SMB)	Opens Quick Connect modal
Action bar → Connect… (S3 / Azure / GCS / Dropbox / Drive / OneDrive)	If a saved site exists for that family, connects to it directly. If 2+ saved sites exist, a chooser modal appears. If none, the button is hidden — use Sites… to set one up.
File menu → Quick connect… (Ctrl+Q)	Always opens the modal (power-user free-form path)
Action bar → Sites… (or File → Site Manager… (Ctrl+S))	Manage saved sites — search/filter, hover/select rows, double-click to connect

Quick Connect¶

Opens with the protocol already selected based on whichever protocol is currently active:

If you're already on an SFTP tab, the modal pre-selects SFTP
If you clicked the "Amazon S3" palette swatch, the modal pre-selects Amazon S3 and defaults port 443

Fill in host / username / password / port (port defaults per protocol: 22 for SFTP, 21 for FTP, 443 for everything else) and hit Connect.

On success:

A session tab appears in the tabs strip
The UI retints to the protocol's accent colour
The remote pane lists the default directory
The connection auto-saves to Sites with name <user>@<host> — on next launch it appears in the Sites list with password stored in the OS keychain. No plaintext on disk.

FTP family — Encryption + Logon Type fields¶

For protocol = FTP or FTPS or SFTP the Site Form shows two top-level dropdowns (FileZilla parity), positioned right after the Port field:

Encryption (FTP and FTPS only — SFTP shows an "always-encrypted" info row instead):

Mode	Behaviour
Use explicit FTP over TLS if available (FTP default)	Try AUTH TLS; fall back to plain if the server refuses
Require explicit FTP over TLS (FTPS default)	Fail if AUTH TLS handshake doesn't succeed
Require implicit FTP over TLS (port 990)	TLS handshake before any FTP command; default port 990
Only use plain FTP (insecure)	Refuse TLS even if offered. Tooltip warns.

Logon Type (FTP / FTPS):

Normal — username + password
Anonymous — auto-fills anonymous / anonymous@example.com
Ask for password — clears the stored password; a prompt fires at connect time

Logon Type (SFTP):

Normal — username + password
Ask for password
Key file — exposes a file picker (or paste the path) for an OpenSSH private key, plus an optional passphrase. Backed by russh-keys authenticate_publickey.

Quick Connect doesn't show the Encryption dropdown — the bridge defaults to auto mode for FTP, so connect-time auto-detection handles it. Use Site Manager → New site for the full controls.

Cloud protocols (S3 / Azure / GCS / Dropbox / Google Drive / OneDrive)¶

Every cloud protocol's section in the Site Form has an ⓘ info icon next to its title. Click it for a full step-by-step setup walkthrough specific to that provider, with a "Copy to clipboard" button so you can keep the steps next to your dev console while filling out the form. The notes below summarize what each form needs.

Local sync mode — the easiest path (Dropbox / OneDrive / Google Drive)¶

If you have the desktop client of Dropbox / OneDrive / Google Drive installed, FTProxy auto-detects the local sync folder when you open the Site Form for that provider. The form defaults to Use local sync mode with the path pre-filled — zero OAuth, zero dev-console registration, zero token rotation. Reads and writes are instant (filesystem speed); the desktop client uploads to the cloud asynchronously.

Detection methods: - Dropbox — reads %LOCALAPPDATA%\Dropbox\info.json (Win) or ~/.dropbox/info.json (Mac/Linux). Survives custom folder locations (e.g. D:\Dropbox). - OneDrive — reads Windows registry HKCU\Software\Microsoft\OneDrive\Accounts\*\UserFolder (covers Personal + Business accounts with their actual paths). Falls back to ~/OneDrive and ~/OneDrive - <Org> siblings on other platforms. - Google Drive — scans drive letters (Windows) for <drive>:\My Drive. Works whether the user picked Streaming mode (default G:\) or Mirror mode.

Switching to OAuth mode: if the desktop client doesn't have what you need (selective sync excludes a folder, you want files-on-demand without local cache, you need team-shared spaces) — the Site Form's mode toggle has a second radio "Connect via API (OAuth)" that uses the provider's REST API with an OAuth refresh-token flow.

OAuth (per-user) mode¶

Protocol	Required extras	Auth model	Status
Amazon S3	Bucket. Optional: region, endpoint, path-style (for MinIO / R2 / DO Spaces / Wasabi). Username = access key id; password = secret key.	Static keys	Working
Azure Blob	Container. Optional: endpoint suffix. Username = storage account; password = account key.	Static keys	Working
Azure Files	Storage account name + access key + share name. The bridge constructs `\\<account>.file.core.windows.net\<share>` and dispatches to SMB transport (mounts via OS-native SMB client).	Storage account key	Working
Google Cloud	Bucket. Service-account JSON pasted into the "Service-account JSON" field (not a path — actual contents). Host / username / password are ignored.	Service account	Working
Dropbox	Register a Scoped App at https://www.dropbox.com/developers/apps with files.metadata + files.content + account_info.read scopes. Add `http://localhost:53682/oauth/callback` to Redirect URIs. Paste App key + App secret into Site Form, click "Sign in with Dropbox".	OAuth 2.0 + refresh-token (long-term, auto-rotates)	Working
Google Drive	Cloud Console Desktop OAuth client + Drive API enabled. Paste client id, click "Sign in with Google".	OAuth 2.0 + PKCE + refresh-token	Working
OneDrive	Azure AD app registration with Files.ReadWrite delegated permission. Paste Application (client) ID, click "Sign in with Microsoft".	OAuth 2.0 + PKCE + refresh-token	Working — small files via PUT, large files via Graph's createUploadSession + chunked PUTs

Signing in to Google Drive / OneDrive (one-time setup)¶

Both providers require you to register your own OAuth client. There's no shared client ID FTProxy can ship — Google and Microsoft TOS forbid it. Once registered, the Site Form's "Sign in" button drives the rest.

Google Drive: 1. Go to https://console.cloud.google.com/apis/credentials 2. Create / pick a project, enable the Google Drive API 3. Create credentials → OAuth client ID → application type Desktop app 4. Copy the client id (looks like …apps.googleusercontent.com) 5. In FTProxy: File → Site Manager → New site → protocol Google Drive → paste the client id → click Sign in with Google → complete the browser flow. Token is stored in your OS keychain.

OneDrive: 1. Go to https://portal.azure.com → Azure Active Directory → App registrations → New registration 2. Pick "Mobile and desktop applications", add http://127.0.0.1 as a redirect URI (any port — FTProxy binds a dynamic loopback) 3. API permissions → Microsoft Graph → Delegated → Files.ReadWrite and offline_access 4. Copy the Application (client) ID 5. In FTProxy: New site → protocol Microsoft OneDrive → paste the client id → Sign in with Microsoft → complete the browser flow.

WebDAV¶

Set Host to the full base URL of the user's WebDAV root (e.g. https://cloud.example.com/remote.php/dav/files/alice/). Username / password are HTTP Basic.

SMB / CIFS — Windows file shares & NAS¶

Transit speaks SMB by mounting the share through your operating system's native SMB client — no Samba dependency, no virtual-FS driver, no admin elevation on Windows.

Site Form fields - Protocol = SMB / CIFS — Windows file share / NAS - Host — accepts three forms: - \\server\share (full UNC) - smb://server/share (URL form, gets normalized) - bare server plus the Share extras field (separate share name) - Username / Password — NTLM credentials. Leave both blank for anonymous mounts. For Active Directory shops use either DOMAIN\user in Username, or set the Domain extras field and put just the user in Username. - Share (extras) — only needed if Host is just the server name. - Domain (extras) — Windows AD domain prefix. - Drive letter (extras, Windows only) — Z etc. Empty = first free letter from Z down to G is picked automatically. - Pre-mounted path (extras) — if you already mounted the share at, say, Z:\ outside Transit, paste it here and Transit attaches to it without running another net use.

What happens on Connect

Platform	Stack used	Required package
Windows	Windows SMB redirector (`net use`)	ships with the OS
macOS	Apple's own SMB client (`mount_smbfs`)	ships with macOS
Linux	kernel `cifs.ko` (`mount -t cifs`)	`cifs-utils` (`sudo apt install cifs-utils` once on minimal installs)

On Disconnect Transit unmounts (net use … /delete / umount) so the drive letter / mount point is released.

Tip: for a one-off browse without saving credentials, use the 📁 Places button on the Local pane → Map network drive… modal. That's the same code path; the share appears as a regular local drive in your Local pane until you eject it.

3. Working with files¶

Dual-pane (FTP / SFTP / WebDAV)¶

Left pane = your machine. Right pane = the server.

Single-click a directory to enter it (including .. to go up)
Single-click a file to select it (row turns accent)
Ctrl-click / Shift-click to multi-select (including multi-selecting directories — modifier keys suppress single-click-navigate)
Double-click a file to download (on remote) or upload (on local)
Drag a row from one pane into the other to transfer
Right-click a row for the context menu (see §6)
Click a breadcrumb in the path bar to jump up; double-click the path bar itself to type a full path and hit Enter
Click the column headers (Name / Size / Modified / Perms / Owner / Verify) to sort; click again to reverse

Single-pane (S3 / Azure / GCS)¶

Only the remote object-store is shown. To upload:

↑ Upload selected in the action bar opens an OS file picker
Or drag-drop files from Windows Explorer / your desktop onto the pane
↓ Download fetches a selected object to the OS download folder

Right-click a row for Copy S3 URI / Copy Azure URL / Copy gs:// URI — pastes a canonical URI for the object.

Transit lane (dual-pane only)¶

Between the panes. Upload arrow (↑) and download arrow (↓) act on currently-selected rows — same as the corresponding action-bar buttons.

Queue¶

Pill strip below the workspace. Each in-flight transfer gets a pill showing direction arrow · filename · percent / status. When the queue finishes, summary on the right reads N items · N active · N done · N failed (green / red tinted).

4. Protocol accent palette¶

The six swatches below the session tabs let you preview any protocol's look without actually connecting. Clicking a swatch:

Changes the accent colour everywhere (action bar primary button, remote pane glyphs, breadcrumbs, queue pills, wire console)
Flips the layout between dual-pane (SFTP/FTP/WebDAV) and single-pane (S3/Azure/GCS)
When you actually connect, the live session's protocol overrides the preview

5. Layout per protocol¶

Protocols	Layout	Why
SFTP, FTP, WebDAV	Dual-pane (local + transit lane + remote)	Filesystem ↔ filesystem workflow
S3, Azure Blob, GCS, Dropbox, Google Drive, OneDrive	Single-pane (remote only)	Object stores / personal cloud — upload is "pick a file", not "sync a tree"

Switching tabs flips the layout live — no reload.

Local pane: - Open (if directory) - ↑ Upload selected - New folder - Rename · Delete - Compare dirs · Refresh

Remote pane (FTP / SFTP / WebDAV): - Open / ↓ Download / Save as… - New folder · Rename · Delete - Verify hash · Compare dirs - Copy remote path - Refresh

Remote pane (S3 / Azure / GCS): - Open / ↓ Download / Save as… - New folder · Rename · Delete - Verify hash - Copy S3 URI / Copy Azure URL / Copy gs:// URI - Refresh

7. Keyboard shortcuts¶

Key	Action
`U`	Upload selected
`D`	Download selected
`R` or `F5`	Refresh both panes
`Ctrl+Q`	Quick Connect (via native menu)
`Ctrl+S`	Site Manager (via native menu)
`Ctrl+R`	Reload the UI
`Ctrl+Shift+R`	Hard Reload — clears WebView2 caches before reloading (use this if v## marker in the wire console looks stale)
`Ctrl+Shift+I`	Toggle DevTools (debug builds)
`Esc`	Close any open dropdown / context menu

8. Menus¶

File¶

Quick connect · Site Manager · Disconnect · Reconnect last · Copy current connection to Site Manager · Import sites from FileZilla XML · Import sites from WinSCP · Import sites from PuTTY · Import sites from CoreFTP · Export sites to JSON · Exit.

Every "Import sites from …" lives under File in 0.7.3+. The WinSCP / PuTTY entries used to live under Bookmarks; if you have muscle memory for that, they moved.

Edit¶

Settings · Clear private data (queue history) · native Undo / Redo / Cut / Copy / Paste / Select All.

View¶

Refresh both panes (F5) · Compare directories · Toggle wire console · Toggle protocol palette · Reload (Ctrl+R) · Hard Reload (Ctrl+Shift+R) clears WebView2 cache + sessionStorage before reloading · DevTools (Ctrl+Shift+I).

Transfer¶

Process queue · Retry all failed · Cancel all in-flight · Clear finished.

Server¶

Disconnect · Reconnect last · Run command… (SFTP only) · Benchmark connection… · Jobs… · Job history…

Jobs… opens the unified jobs dashboard. A Job is a named, ordered list of steps the runner walks end-to-end on a schedule. Two views:
📅 Calendar (default) — month grid with a chip per scheduled firing. Today's day cell is outlined in accent. Chip color tells you the type at a glance (green = upload, blue = download, purple = mirror, orange = batch, grey = disabled). Click a chip for run-now / edit / details. Click an empty day to create a new job pre-dated to that day.
☰ List — flat list of every Job with run-now / edit / delete.
+ New schedule opens the schedule builder:
Job name + Steps (folder-sync / file-sync / wait / webhook).
Recurrence: Once · Daily · Weekly · Monthly · Custom-cron.
Time of day (HH:MM picker). Weekly adds day-of-week checkboxes; Monthly adds day-of-month spinner.
Start on date (don't fire before this) and Stop after date (optional — stop firing after this).
Live cron preview shows what's being generated.
Job history… lists every run (scheduled or "Run now") with status icons, timestamps, duration, and a N↑ N↓ N✗ stats line. Failed rows expand to show the error. Refresh + Clear-all + per-row delete.

Step types: - Folder sync — recursive transfer against a saved site (whole directory tree). Use for "back up C:\reports to S3 every night". - File sync — explicit list of files (e.g. report.pdf, data.xlsx). Use for "sync these 2 specific files daily, not the whole folder". Direction limited to upload/download (no mirror). - Wait — pure delay. Useful between steps to let the previous step's writes settle. - Webhook — fire-and-forget HTTP call with optional JSON body. Useful for kicking deploys, posting to Slack/Discord, etc.

The Site Manager's per-site form has a 📅 Schedule a job for this site → button that opens the Job builder pre-filled with one folder-sync step targeting that site.

Bookmarks¶

Add current path · Manage bookmarks. (Sites imports moved to File in 0.7.3.)

Help¶

About FTProxy · Show bridge URL + token.

9. Settings (Edit → Settings…)¶

Field	Effect
Default local path	Starting directory for new sessions
Concurrent transfers	Semaphore size (max in-flight)
Verify after upload	FTP HASH / XMD5 / SHA integrity check
Default FTP transfer type	Binary (default) or ASCII
Play completion sound	Audible chime on transfer complete
Theme	Dark (locked on currently — light disabled)
SFTP host-key verification	Strict (pin on first connect) or Off (legacy TOFU)
Log level	error / warn / info (default) / debug / trace — needs restart

10. The local bridge¶

Every FTProxy window also runs a localhost REST + WebSocket bridge on 127.0.0.1:7878, bearer-token protected, for other local Go Green products (OpenSentinel.ai, etc.) to drive file transfers programmatically.

Token location: OS keychain. Retrieve via Help → Show bridge URL + token or from the /health endpoint.
Public endpoint: GET /health (no auth).
Everything else takes Authorization: Bearer <token>.

See API.md for the full endpoint reference.

11. Troubleshooting¶

UI looks stale / old version after a rebuild. WebView2 caches the embedded frontend. Use View → Reload (Ctrl+R) to force a refresh. Verify the build marker in the Wire console matches the current UI build: … entry.

Connect fails with "Bridge unavailable". The Tauri window couldn't reach its own bridge. Close the window and relaunch. If persistent, netstat -ano | findstr 7878 — something else may be bound.

SFTP "host key mismatch" modal. Server rotated keys (or MITM). Verify the fingerprint out-of-band, paste it in the modal, click Trust new key to update known_hosts.json.

Transfer shows "550 err" (FTP). Server refused. Usually permission denied or path doesn't exist. Check the remote pane's permissions column.

S3 / Azure / GCS lists only the first 1000 objects. Pagination of prefixes past 1000 is a deliberately deferred feature — see tasks/todo.md.

Tabs wrap to a second line. Resize the window wider — the tabs strip scrolls horizontally when narrow but wraps down on very small windows.

12. Where to find things¶

File	What it is
`CHANGELOG.md`	Every release's bullet list
`API.md`	Bridge REST + WebSocket reference
`INTEGRATION.md`	Embedding FTProxy's bridge into other tools
`IMPLEMENTATION.md`	Architecture and design notes
`CLAUDE.md`	AI-assist guidance for contributors
`tasks/todo.md`	Deferred / in-progress items
`tasks/lessons.md`	Non-obvious gotchas from the build
`tasks/ui-restyle-progress.md`	Mock-workspace port history
`CREDENTIALS.md`	How to obtain keys / tokens / OAuth IDs for every supported protocol
`dist/mock-workspace.html`	Visual reference (dual-pane)
`dist/mock-remote-pane.html`	Visual reference (single-pane / S3)