Skip to content

S3 and Local File Manager

The S3 service is a keyboard-driven, dual-pane file manager for AWS S3, S3-compatible object stores, and the local filesystem. Each pane owns its own source and current path, so local-to-S3, S3-to-local, and S3-to-S3 workflows use the same navigation and transfer surface.

1. Sources and navigation

Each pane can use local, an explicit [connections.*] entry, or an auto-discovered AWS profile. Shift+S cycles only the focused pane through resolver order. The opposite pane and its selection remain unchanged.

Tab and Shift+Tab move between the left pane, right pane, and service rail. Enter descends into the selected directory, bucket, or prefix; Backspace ascends one level. See Keybindings for the complete active map.

2. File operations

c copies the selected row or marked rows to the opposite pane through the streaming CrossFsCopy engine. Copying a directory works only when the destination is the local pane: CrossFsCopy publishes a directory transactionally, which LocalFS supports and S3FS does not, so a folder-to-S3 copy is rejected before any bytes move. Copy the files themselves, or use the AWS CLI, to upload a tree. d deletes the selected rows. Both operations require confirmation, reject a parent-link row, and publish progress through the Transfers overlay. Persistent marks, range extension, and modifier-click selection let one operation address multiple entries.

p copies the full path of the entry under the cursor; P copies the pane's current directory path. Both are also command-palette entries (Copy cursor entry path, Copy pane path), listed only while the file manager is the active service. The pane's top border is a click target for the same copy, and a truncated name or path is revealed in full rather than silently clipped.

The confirmation names the channel that actually took the text. Where a clipboard helper is available (pbcopy, clip, wl-copy, xclip, xsel) the toast confirms the copy. Where there is none — an ssh session, a container, a stripped-down host — the only write is the terminal's own OSC 52 escape, which no terminal acknowledges and some (macOS Terminal.app always, iTerm2 unless enabled) discard; the toast says so rather than claiming a copy that may not have happened.

S3 multipart copies and uploads are cancelled and aborted explicitly. Active transfers write diagnostic journal records under <cache-dir>/transfers/; terminal success, failure, skip, and cancellation remove their journal. Move, rename, and new-folder commands remain deferred.

3. Architecture

S3Service composes a DualPaneVM from two PaneVM instances. Providers implement the shared FileSystemProvider protocol: S3FS for AWS or S3-compatible sources and LocalFS for the workstation. CrossFsCopy owns staging, commit, rollback, conflict handling, progress, and cancellation. Textual widgets render VM state and route commands; they do not call providers directly.

The source resolver supplies exact connection identity, region, endpoint, addressing style, and credential references. The S3 provider uses the aioboto3/botocore public client contract recorded in the Consumed Contract Ledger.

4. Safety and limits

  • S3-compatible connections share the S3 implementation but may require path-style addressing or vendor-specific endpoint configuration.
  • A directory listing is limited to 10,000 entries. S3 traversal is also limited to 100 continuation pages; narrow the current path when either safety budget is exceeded.
  • One copy or move batch is limited to 1,000 selected entries. The limit is checked before durable transfer journals are created.
  • Quick Look reads at most the first 64 KB of a selected file.
  • Transfer journals are diagnostics, not automatic replay instructions.
  • The application never infers a destructive operation from navigation or selection alone.

Connection examples and provider configuration guidance are in Connections. Transfer recovery and local S3Mock recipes are in the Cookbook.

5. Verification and demo

Demo mode seeds deterministic S3-compatible sources while leaving the local pane attached to the real local filesystem. The unit suite covers provider operations, multipart lifecycle, selection, transfer rollback, and service composition. In-process integration and end-to-end journeys cover copy, delete, source switching, cancellation, and S3-compatible behavior.