Download files from a remote environment (signed download for any readable file)

[Ephraim-9]

Problem

I run T3 Code on a VPS and use it from a browser. The agent produces files there all the time (archives, logs, generated docs, build outputs), and today there is no way to get them onto the device I'm sitting at. The Files panel can browse and preview, and a file's path can be copied, but nothing hands the actual bytes to the client. The workaround is leaving T3 Code for scp/SFTP, which is slow and error-prone when it's needed many times a day.

This is the remote case of #5532 (closed without a change). On a remote or tunneled environment there is no fallback at all, because the file lives on another machine.

Proposal

A Download action for any regular file the environment host can read, reachable from the places a file already appears:

• Files panel: row context menu
• File preview: header button
• Chat file chips: context menu
• Diff panel file headers: context menu

How it works, deliberately small:

• New file-download member of the existing AssetResource union (packages/contracts/src/assets.ts). It carries an absolute path.
• The server issues a signed, expiring asset URL for it, reusing the existing assets.createUrl RPC and asset route. The claim pins the canonical path; resolving re-canonicalizes and rejects a mismatch, a missing file, a directory, or a tampered token. Files are served with Content-Disposition: attachment under their real name, with no preview-type limit.
• Authorization is the existing AuthFilesystemReadScope, the same scope that already gates reading files, so no new permission.
• Browsers follow the signed URL directly, so the file streams to disk instead of being buffered in memory. Desktop (Electron) goes through a Blob because its custom app scheme would otherwise hand the navigation to an external browser, so large files there are memory-bound.
• The menu item is added in the shared fileContextMenu.ts, so the entry points above stay consistent.

Explicitly out of scope: folder/zip download, a mobile Download button, and anything beyond reading files the environment can already read.

Implementation

I have this working as two commits on top of current main, with server tests for the claim/resolve rules and a web test for the menu logic: https://github.com/Ephraim-9/t3code/tree/feat/download-host-files

I have not opened a PR, since CONTRIBUTING.md requires explicit maintainer approval of direction and scope for new features first. Happy to open one, rework it (for example, narrowing the entry points), or drop it, whichever you prefer.

Verified in a real browser against a VPS-hosted environment: Download streams the file to disk under its real name. Not yet checked on desktop or mobile clients; I'd add before/after screenshots to a PR if this is approved.

[Ephraim-9]

bumping this with a real use case. i run T3 on a VPS and there’s no way to grab files the agent makes (zips, apks, logs) from inside the UI. most of the time i just make the agent send them to me on discord, or scp them, which gets old fast.

i’ve got a working patch. it adds a Download action that streams the file to disk with its real name, uses the existing filesystem:read scope, and needs no new permission. i checked it in a real browser and it works. branch is here, kept rebased on main: https://github.com/Ephraim-9/t3code/tree/feat/download-host-files

is this direction ok, or should i narrow it (like just the Files panel)? happy to open a PR once someone gives the go-ahead.

[gadzbi123]

+1. Here's the mobile side of this, which the proposal currently leaves out of scope.

My use case: I run T3 Code on a Raspberry Pi and drive it from the Android app. The agent builds an APK, and I want to install it on the phone I'm holding. Today, tapping the APK in the chat or the Files panel opens the file viewer, which tries to read it as text and shows:

File unavailable
Failed to read workspace file 'mobywatel-demo/dist/obywatel-demo.apk' in '/home/gadzbi'.

The underlying cause is WorkspaceBinaryFileError (apps/server/src/workspace/WorkspaceFileSystem.ts:329). The generic message in packages/contracts/src/project.ts:504 hides it, so the screen reads as if the file were missing. Host file chips can't Save/Share it either: both the client (apps/mobile/src/features/threads/fileChipMenu.ts:42) and the server (apps/server/src/assets/AssetAccess.ts:381) only allow types that have a preview MIME type.

If this direction is approved, I'd suggest a narrow mobile follow-up on top of the file-download resource: when the file viewer opens an .apk, show a Download action instead of the text error. Other files the viewer can't display would keep today's behavior, unless you'd rather offer Download for those too. That action would reuse downloadAndShareAttachment, so Android's share sheet opens and the user picks the package installer. T3 Code would add no Android permissions, in particular no REQUEST_INSTALL_PACKAGES. I'm happy to write and test that part on a real Android device once the main proposal has a direction.

A few things I checked at f43f6ddd that could inform the design:

• Token lifetime and caching. Asset tokens are bearer tokens in the URL path. They last 1 hour and aren't bound to a session (AssetAccess.ts:71). Expiry is checked once per request, so a slow download that has already started still completes. Download responses currently carry Cache-Control: private, max-age=3600 (apps/server/src/http.ts:106). For downloads, no-store might be a better fit.
• No resume. Range requests are only honored for audio/* and video/* (http.ts:197), so an interrupted download of a large APK or archive restarts from zero.
• T3 Connect limits. Large downloads over T3 Connect go through the managed tunnel. I didn't find any documented response-size or timeout guarantee there, so 100 MB+ transfers probably deserve a test.

[grahamfarrar]

+1, with one addition: an Open action next to Download, so the file opens in its default app on the device that clicked it.

My setup is a Mac Studio running the T3 background service, reached as a saved environment from the desktop app on the same Studio, from a MacBook over Tailscale, and from the iPhone app. Most of what the agent hands me is Office files (xlsx, pptx, docx). Clicking the chat chip opens the files panel, which shows "The file is binary and cannot be displayed as text". Right-click offers only "Copy relative path" and "Copy full path".

Download alone still leaves me finding the file in Downloads and opening it. The action I want on a chip is:

• Desktop app: fetch the file through the same signed asset URL this proposal describes, save it to a temp or Downloads folder, then shell.openPath it. A local file would skip the fetch and open in place.
• iPhone/Android app: fetch it, then hand it to Quick Look or the share sheet, which already preview xlsx, docx, pptx and PDF.
• Browser client: same as Download.

Making that the default click for file types the in-app viewer can't render would remove the "binary" dead end. #17981 (closed) asked for a configurable default action for file links, so that setting could hold the choice.

Related: #18515 (same-machine saved environments should count as local, which would bring back Reveal in Finder on the Studio itself) and #6894 / #14083 (download from a chat chip, closed without merging).

[Ephraim-9]

quick scope proposal so this is easy to say yes or no to.

v1 (one PR): download on web and desktop

• a file-download asset resource that serves any regular file the host can read, with its real filename and no preview-type limit
• it uses the existing filesystem:read scope, so there's no new permission
• Download shows up in the file tree right-click menu, the file preview header, chat file chips and diffs. folders don't get it

follow-ups on the same resource (separate PRs, only if wanted)

• mobile: Download/Share in the file viewer for files it can't render. this covers @gadzbi123's APK case through the existing downloadAndShareAttachment share sheet
• desktop: an "Open" action (fetch, then shell.openPath) for @grahamfarrar's Office files

the branch is rebased on today's main. it typechecks and the touched tests pass: https://github.com/Ephraim-9/t3code/tree/feat/download-host-files

@juliusmarminge ok if i open the v1 PR?

[grahamfarrar]

Splitting it that way works for me. Download on its own already helps the browser case, and Open can come later on the same resource.

[y-u-s-u-f]

+1 to this

[unbeholdendev]

I also need this for CSV exports generated on a remote environment. I can preview them in T3 Code but can’t save them to my laptop. The proposed web/desktop download scope would solve my case. Is there anything contributors can do to help get this approved?