Remote Native Open

Open remote workspace files in your local desktop applications.

Remote Native Open copies a file from a VS Code remote or provider-backed workspace into a controlled cache on your Windows computer, then opens it with the operating system's registered application. Local edits can be synchronized back manually or automatically with SHA-256 conflict protection.

Remote Workspace
      ↓
VS Code FileSystem API
      ↓
Remote Native Open (local UI extension)
      ↓
Tracked Local Cache
      ↓
Excel / Word / PowerPoint / PDF viewer / other registered app

No additional SSH credentials. No SFTP setup. No Kubernetes credentials. No additional remote agent.

The extension reuses the remote filesystem connection already established by VS Code.

Features

• Open in Local Application from the Explorer context menu or Command Palette.
• Uses the Windows default registered application—no hard-coded Office executable paths.
• Tracks multiple remote-file sessions.
• Detects stable local saves, including replace/rename-style application saves.
• Manual synchronization by default; optional automatic synchronization.
• SHA-256 conflict detection before every upload.
• Explicit confirmation before overwriting independently changed remote content.
• Reveal and close commands for local copies.
• Controlled cache directories with tracked cleanup.
• URI-correct support for VS Code FileSystemProvider resources.

Supported Environments

MVP target:

• VS Code Desktop on Windows 10 or Windows 11
• Remote SSH (end-to-end tested against Linux on 2026-08-31; verify each target setup)
• Dev Containers (vscode-remote://dev-container, end-to-end tested on 2026-08-31)
• WSL (vscode-remote://wsl, end-to-end tested on 2026-08-31)

The implementation is provider-agnostic and may work with other writable FileSystemProvider implementations, but this is not a support claim for Codespaces, Kubernetes/OpenShift extensions, or arbitrary virtual workspaces until they are tested.

Browser-hosted VS Code is not supported because it cannot create/watch local Windows files or launch desktop applications through Node APIs.

Supported Files

Defaults:

.xlsx, .xlsm, .docx, .docm, .pptx, .pptm, .pdf, .csv

The transfer and synchronization core is not Office-specific. Additional extensions can be allowed with remoteNativeOpen.supportedExtensions; customized types remain accessible through the Command Palette because Explorer menu visibility uses the built-in defaults.

How to Use

1. Open a trusted remote workspace in VS Code Desktop on Windows.
2. Right-click a supported file and choose Open in Local Application. You can also press Ctrl+Alt+Shift+O for the active file.
3. Edit and save in the native desktop application.
4. In manual mode run Remote Native Open: Sync Local Changes to Remote.
5. Use Reveal Local Copy, Show Active Sessions, or Close Local Session as needed.

Normal local file: resources open directly and do not create synchronization sessions.

Conflict Behavior

When a file is downloaded, its SHA-256 hash becomes the baseline. Before upload, Remote Native Open reads and hashes the current remote file:

• baseline unchanged → upload proceeds;
• remote and local both changed → no upload occurs until you explicitly choose Overwrite Remote;
• remote changes again during confirmation → upload aborts.

There is no binary merge or distributed lock.

Settings

Security Model

• Remote access uses only vscode.workspace.fs and inherits provider permissions.
• Office applications are discovered from Windows App Paths and verified before direct launch; explicit executable overrides are machine-scoped. Other types use the system association path. No filename enters a shell command.
• Cache paths use random session IDs, basename extraction, containment checks, and guarded cleanup.
• Workspaces must be trusted.
• No telemetry, file-content logging, credential storage, sudo, chmod, or authentication prompts.

Macro-enabled Office documents and PDFs remain potentially active/untrusted content. The extension does not sandbox or sanitize them. See Security Model.

Known Limitations

• Transfers use workspace.fs.readFile/writeFile, so each file is held in memory. Default maximum: 100 MB.
• The VS Code filesystem API has no portable compare-and-swap write; a small check/write race remains.
• Cache deletion is not secure erasure, and crashes may leave tracked files behind. The cache uses the local UI extension's globalStoragePath.
• Native applications can keep files locked and delay cleanup.
• Dynamic custom extensions do not alter the static Explorer context-menu filter; use the Command Palette.
• No session recovery after VS Code restarts in this MVP.
• Remote SSH, Dev Containers, and WSL were validated against the recorded environments; each production environment should still be verified using the test plan.

Troubleshooting

The command is missing: confirm the workspace is trusted and the file uses a default supported extension. Custom extensions are available through the Command Palette.

The wrong machine opens the file: run Developer: Show Running Extensions and confirm Remote Native Open is listed as Local. The manifest forces UI placement.

Sync fails: check Output → Remote Native Open, reconnect the remote workspace, and verify provider write permission. The extension will not request elevation.

A conflict appears: another process changed the remote bytes after download. Cancel to preserve both sides, or explicitly overwrite after reviewing the remote change.

The cache remains: close the session and check remoteNativeOpen.cleanupOnSessionClose. Application file locks or an extension-host crash can leave data behind.

Contact & Support

• Report a bug or request a feature
• Source code and documentation
• Developer profile

Please use GitHub Issues for support. Do not include credentials, private remote paths, or sensitive file contents in reports.

Development

npm install
npm run compile
npm run lint
npm test
npm run package

Press F5 to launch the Extension Development Host. Packaging creates a local VSIX and does not publish it.

Architecture details are in docs/architecture.md.