SFTP Explorer

A VS Code extension that adds plain SFTP remote file access to the Remote Explorer sidebar. Browse, edit, upload, download, and manage files on any SFTP server — no VS Code Server required on the remote machine.

Use cases: Pterodactyl-hosted Docker containers, FiveM server development, any server where Remote SSH is unavailable.

Table of Contents

• Using the Extension
  • Install from VSIX (private use)
  • Add your first host
  • Connect and browse files
  • File operations
  • Upload & download
  • Drag and drop
• Building from Source
• Running Tests
• Publishing to the VS Code Marketplace
• Troubleshooting

Using the Extension

Install from VSIX (private use)

If you just want to use the extension yourself without publishing it:

Step 1 — Build the VSIX package

npm install
npm run package        # builds dist/extension.js in production mode
npx vsce package       # creates vs-sftp-explorer-0.0.1.vsix

If you don't have vsce installed: npm install -g @vscode/vsce

Step 2 — Install in VS Code

• Open VS Code
• Press Ctrl+Shift+P → type Extensions: Install from VSIX...
• Select the .vsix file you just built

Or from the terminal:

code --install-extension vs-sftp-explorer-0.0.1.vsix

Step 3 — Reload VS Code

Press Ctrl+Shift+P → Developer: Reload Window

Add your first host

1. Open the Remote Explorer sidebar (click the monitor icon in the Activity Bar, or Ctrl+Shift+P → Remote Explorer: Focus on Remote Explorer View)
2. Find the SFTP Hosts section
3. Click Add SFTP Host... or the + button in the view title bar
4. Fill in the form:

1. For Password auth: enter your password, check "Remember password" if you want it saved
2. For SSH Key auth: enter the path to your private key (defaults to ~/.ssh/id_rsa), optionally enter a passphrase
3. Click Save Host

Connect and browse files

• Right-click a host → Connect, or double-click it
• The host icon turns green and its file tree expands inline
• Click any file to open it in the editor — edits save directly to the server on Ctrl+S
• Only one host can be active at a time — connecting a new host disconnects the previous one
• The status bar shows the active connection name; click it to disconnect

File operations

Right-click any file or folder in the SFTP tree:

On a file:

• Open
• Rename
• Copy / Cut
• Download to local...
• Delete

On a folder:

• New File...
• New Folder...
• Rename
• Copy / Cut / Paste
• Upload File Here... / Upload Folder Here...
• Download Folder...
• Delete

Note on Copy/Move: SFTP has no server-side copy command. All remote-to-remote copies buffer through the extension memory (readFile → buffer → writeFile). A progress notification appears for large files and can be cancelled.

Upload & download

Upload files: Right-click a folder → Upload File Here... → pick one or more local files from the OS file picker.

Upload a folder: Right-click a folder → Upload Folder Here... → pick a local folder. Uploads recursively.

Download a file: Right-click a file → Download to local... → choose where to save it.

Download a folder: Right-click a folder → Download Folder... → choose a local destination. Downloads recursively.

Drag and drop

Drag any file from VS Code's local Explorer panel and drop it onto a folder in the SFTP tree — it uploads automatically.

Building from Source

Requirements: Node.js 18+, npm

git clone <your-repo>
cd vs-sftp-explorer
npm install

Test the extension live (F5 debug):

1. Open the vs-sftp-addon folder in VS Code
2. Press F5
3. A new Extension Development Host window opens with the extension loaded

Running Tests

The test suite has two layers:

Unit tests (no VS Code needed — run directly with mocha):

npm run compile-tests
./node_modules/.bin/mocha --ui tdd --timeout 10000 \
  out/test/suite/connectionManager.test.js \
  out/test/suite/sftpClient.test.js

Expected: 11 passing

Full suite (launches VS Code headlessly via @vscode/test-electron):

npm test

Expected: 17 passing (includes FileSystemProvider tests that require the VS Code API)

Publishing to the VS Code Marketplace

Prerequisites

1. A Microsoft account — create one at account.microsoft.com
2. A publisher account on marketplace.visualstudio.com/manage
3. A Personal Access Token (PAT)

Step 1 — Create a publisher

Go to marketplace.visualstudio.com/manage → Create publisher → pick a publisher ID (e.g. juliadev). Remember this — you need it in package.json.

Step 2 — Create a Personal Access Token

1. Go to dev.azure.com → your organization → User Settings → Personal Access Tokens
2. Click New Token
3. Set Scopes → Marketplace → check Manage
4. Copy the token (you won't see it again)

Step 3 — Update package.json

Open package.json and set your publisher ID:

"publisher": "your-publisher-id-here"

Also update name, displayName, description, version, and optionally add:

"repository": { "type": "git", "url": "https://github.com/you/your-repo" },
"license": "MIT",
"icon": "icon.png"

The icon must be a 128×128 PNG in the project root if you include it.

Step 4 — Install vsce

npm install -g @vscode/vsce

Step 5 — Login

vsce login your-publisher-id-here
# paste your PAT when prompted

Step 6 — Publish

vsce publish

This runs npm run package (production build), packages the VSIX, and uploads it. The extension goes live within a few minutes.

Publish a specific version:

vsce publish 1.0.0
# or bump automatically:
vsce publish minor   # 0.0.1 → 0.1.0
vsce publish patch   # 0.0.1 → 0.0.2

Just package without publishing:

vsce package
# creates vs-sftp-explorer-0.0.1.vsix

Troubleshooting

"SFTP Hosts" section doesn't appear in Remote Explorer

The Remote Explorer sidebar requires the Remote Explorer extension to be installed (it ships with VS Code by default but may be disabled). Check Extensions → search Remote Explorer → enable it.

Connection times out

• Default timeout is 10 seconds. Check that the host/port is reachable.
• For Pterodactyl containers: use the server's IP and the SFTP port shown in the panel (usually not 22 — check the server details page).

Authentication fails

• Password auth: double-check username and password. If "Remember password" was checked with a wrong password, edit the host to re-enter it.
• SSH key auth: make sure the path is absolute (or starts with ~). The key must not have Windows line endings — use a key generated on Linux/macOS or via ssh-keygen on WSL.

Permission denied on file operations

The connected user doesn't have write access to that path. Check server-side permissions.

File changed warning on save

If you see "Remote file has changed since you opened it. Overwrite anyway?" — another process modified the file on the server between when you opened it and when you saved. Choose Overwrite to write your version, or close the tab and reopen the file to get the latest version.

Extension crashes / stops responding

Open the Output panel (Ctrl+Shift+U) and select SFTP Explorer from the dropdown for logs. You can also open the Extension Development Host's DevTools via Help → Toggle Developer Tools.