Sublime Text Remote Development: Complete Guide

Introduction to Sublime Text Remote Development

Sublime Text has long been a favorite among developers for its speed, minimal footprint, and powerful plugin ecosystem. While editors like VS Code have popularized built-in remote development features, Sublime Text can be configured to work seamlessly with remote servers through a combination of SSH, SFTP, and specialized packages. This guide walks you through everything you need to know to turn Sublime Text into a fully capable remote development environment.

What Is Remote Development?

Remote development is the practice of editing, running, and debugging code that lives on a remote machine — typically a server, container, or virtual machine — while using your local editor's interface. Instead of manually copying files back and forth with scp or rsync, the editor handles synchronization, terminal access, and execution transparently.

Why It Matters

Performance: Heavy builds and tests run on powerful remote hardware without taxing your laptop.
Consistency: Your code runs in the same environment where it will be deployed.
Security: Sensitive credentials and databases never need to be exposed locally.
Collaboration: Shared development servers make pair programming easier.
Resource efficiency: Sublime Text's lightweight nature makes it ideal for remote workflows where bandwidth matters.

Prerequisites and Setup

Before diving in, ensure you have the following in place:

Sublime Text 4 installed on your local machine
Package Control installed (the package manager for Sublime Text)
SSH access to a remote server with key-based authentication
A basic understanding of the command line

Installing Package Control

If you haven't installed Package Control yet, open the Sublime Text console with Ctrl+` (backtick) and paste the following Python snippet:

import urllib.request,os,hashlib
h = '6f4c264a24d933ce70df5dedcf1dcaee' + 'ebe013ee18cced0ef93d5f746d80ef60'
pf = 'Package Control.sublime-package'
ipp = sublime.installed_packages_path()
urllib.request.install_opener(urllib.request.build_opener(urllib.request.ProxyHandler()))
open(os.path.join(ipp, pf), 'wb').write(urllib.request.urlopen('http://packagecontrol.io/' + pf.replace(' ', '%20')).read())

Restart Sublime Text after installation completes.

Configuring SSH Key Authentication

Remote development relies heavily on SSH. Set up key-based authentication to avoid repeated password prompts:

# Generate an SSH key pair locally
ssh-keygen -t ed25519 -C "your_email@example.com"

# Copy the public key to the remote server
ssh-copy-id user@remote-server.com

# Test the connection
ssh user@remote-server.com

Create or edit your ~/.ssh/config file to define a friendly host alias:

Host dev-server
    HostName 192.168.1.100
    User developer
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 60
    ServerAliveCountMax 10

With this in place, you can connect using just ssh dev-server.

Method 1: SFTP-Based File Synchronization

The most popular approach for remote development in Sublime Text is the SFTP package by Jon Robison. It bidirectionally syncs files between your local project folder and the remote server whenever you save.

Installing the SFTP Package

Open the Command Palette with Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS).
Type Package Control: Install Package and press Enter.
Search for SFTP and select it.

Creating an SFTP Configuration

Open a local folder that mirrors your remote project. Then, from the Command Palette, choose SFTP: Setup Server.... This generates a sftp-config.json file in your project root. Edit it as follows:

{
    "type": "sftp",
    "save_before_upload": true,
    "upload_on_save": true,
    "sync_down_on_open": false,
    "sync_skip_deletes": false,
    "sync_same_age": true,
    "confirm_downloads": false,
    "confirm_sync": true,
    "confirm_overwrite_newer": false,
    "host": "dev-server",
    "user": "developer",
    "password": "",
    "port": "22",
    "remote_path": "/home/developer/projects/myapp",
    "ignore_regexes": [
        "\\.sublime-(project|workspace)", "sftp-config(-alt\\d?)?\\.json",
        "sftp-settings\\.json", "\\.svn/", "\\.git/", "\\.hg/",
        "CVS", "\\.DS_Store", "Thumbs\\.db", "node_modules/",
        "\\.next/", "dist/", "build/"
    ],
    "connect_timeout": 30,
    "keepalive": 120,
    "ssh_key_file": "~/.ssh/id_ed25519",
    "remote_time_offset_in_hours": 0,
    "remote_encoding": "utf-8",
    "remote_chmod": null,
    "remote_locale": "C"
}

Key Configuration Options Explained

upload_on_save: Automatically pushes files to the server when you save locally.
sync_down_on_open: Pulls the latest remote version when you open a file — useful when multiple developers work on the same server.
ignore_regexes: Prevents large directories like node_modules from being uploaded.
ssh_key_file: Points to your private key for passwordless authentication.

Common SFTP Commands

Once configured, you can access SFTP commands from the Command Palette or the right-click context menu:

SFTP: Upload File — Push the current file to the server.
SFTP: Download File — Pull the latest version from the server.
SFTP: Sync Local → Remote — Recursively upload the entire project.
SFTP: Sync Remote → Local — Recursively download the entire project.
SFTP: Diff Remote File — Compare local and remote versions side by side.
SFTP: Browse Remote — Navigate the remote filesystem without syncing.

Method 2: SSH Terminal Integration with Terminus

While SFTP handles file editing, you'll often need a terminal on the remote server to run builds, tests, and git commands. The Terminus package brings a full terminal emulator inside Sublime Text.

Installing Terminus

Use Package Control to install Terminus. Then, create a keybinding to launch an SSH session directly:

[
    {
        "keys": ["ctrl+alt+t"],
        "command": "terminus_open",
        "args": {
            "cmd": "ssh dev-server",
            "title": "Dev Server Terminal",
            "cwd": "$project_path"
        }
    }
]

Add this to Preferences → Key Bindings (User). Now pressing Ctrl+Alt+T opens a terminal tab connected to your remote server inside Sublime Text.

Creating a Build System for Remote Execution

You can configure Sublime Text's build system to run commands on the remote server via SSH. Create a new file at ~/.config/sublime-text/Packages/User/RemoteBuild.sublime-build (adjust the path for your OS):

{
    "shell_cmd": "ssh dev-server 'cd /home/developer/projects/myapp && npm test'",
    "working_dir": "$project_path",
    "selector": "source.js",
    "variants": [
        {
            "name": "Run Tests",
            "shell_cmd": "ssh dev-server 'cd /home/developer/projects/myapp && npm test'"
        },
        {
            "name": "Build",
            "shell_cmd": "ssh dev-server 'cd /home/developer/projects/myapp && npm run build'"
        },
        {
            "name": "Lint",
            "shell_cmd": "ssh dev-server 'cd /home/developer/projects/myapp && npm run lint'"
        }
    ]
}

Press Ctrl+B to run the default build, or Ctrl+Shift+B to choose a variant. Output appears in Sublime's built-in output panel.

Method 3: Mounting Remote Filesystems with SSHFS

For a more transparent workflow, you can mount the remote filesystem locally using SSHFS (SSH Filesystem). This makes the remote directory appear as a local folder, so Sublime Text (and any other tool) can read and write files directly.

Installing SSHFS

# Ubuntu / Debian
sudo apt install sshfs

# macOS (using Homebrew + macFUSE)
brew install --cask macfuse
brew install gromgit/fuse/sshfs-mac

# Windows (using WinFsp + SSHFS-Win)
# Download WinFsp: https://winfsp.dev/
# Download SSHFS-Win: https://github.com/winfsp/sshfs-win/releases

Mounting the Remote Directory

# Create a local mount point
mkdir -p ~/remote-projects/myapp

# Mount the remote directory
sshfs dev-server:/home/developer/projects/myapp ~/remote-projects/myapp \
    -o reconnect \
    -o ServerAliveInterval=15 \
    -o ServerAliveCountMax=3 \
    -o cache=yes \
    -o kernel_cache \
    -o compression=yes \
    -o Ciphers=arcfour

# Unmount when done
fusermount -u ~/remote-projects/myapp   # Linux
umount ~/remote-projects/myapp          # macOS

Now open ~/remote-projects/myapp in Sublime Text as a regular folder. Every save writes directly to the remote server.

Method 4: Remote Sublime Package for Direct Editing

The RemoteSubl package takes a different approach: it lets you edit remote files in your local Sublime Text instance by invoking a command on the server side.

Installing the Server-Side Script

On the remote server, install the rmate or rst script:

# Download the rmate script (Ruby version)
sudo wget -O /usr/local/bin/rmate https://raw.githubusercontent.com/aurora/rmate/master/rmate
sudo chmod +x /usr/local/bin/rmate

# Or use the Bash version (no Ruby required)
sudo wget -O /usr/local/bin/rmate https://raw.githubusercontent.com/aurora/rmate/master/rmate.bash
sudo chmod +x /usr/local/bin/rmate

Configuring the SSH Reverse Tunnel

Add a reverse port forward to your ~/.ssh/config:

Host dev-server
    HostName 192.168.1.100
    User developer
    RemoteForward 52698 localhost:52698

Installing the Client Package

In Sublime Text, install the RemoteSubl package via Package Control. Then, while SSH'd into the server, simply run:

rmate /etc/nginx/nginx.conf
rmate app/server.js

The file opens instantly in your local Sublime Text window. When you save, changes are written back to the remote server.

Method 5: Dev Containers with Docker

If your remote environment is a Docker container, you can combine SSH access with Sublime Text for a container-based development workflow.

Setting Up an SSH-Enabled Dev Container

Create a Dockerfile for your development environment:

FROM node:20-slim

RUN apt-get update && apt-get install -y \
    openssh-server \
    git \
    vim \
    curl \
    && mkdir /var/run/sshd \
    && echo 'root:devpassword' | chpasswd \
    && sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config \
    && sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config

WORKDIR /app
COPY . /app

EXPOSE 22 3000

CMD ["/usr/sbin/sshd", "-D"]

Running and Connecting

# Build and run the container
docker build -t dev-env .
docker run -d --name dev-container -p 2222:22 -p 3000:3000 -v $(pwd):/app dev-env

# Add to ~/.ssh/config
# Host dev-container
#     HostName localhost
#     Port 2222
#     User root

# Connect
ssh dev-container

Now use any of the methods above (SFTP, SSHFS, RemoteSubl) to edit files inside the container from Sublime Text.

Best Practices for Remote Development

1. Optimize Your SSH Configuration

Enable connection multiplexing to avoid the overhead of establishing a new SSH connection for every operation:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600
    Compression yes
    ServerAliveInterval 60
    ServerAliveCountMax 10

# Create the sockets directory
mkdir -p ~/.ssh/sockets

2. Use .gitignore-Aware Syncing

When using SFTP, make sure your ignore_regexes array covers all build artifacts and dependencies. A comprehensive example:

"ignore_regexes": [
    "\\.sublime-(project|workspace)",
    "sftp-config(-alt\\d?)?\\.json",
    "sftp-settings\\.json",
    "\\.svn/",
    "\\.git/",
    "\\.hg/",
    "CVS",
    "\\.DS_Store",
    "Thumbs\\.db",
    "node_modules/",
    "\\.next/",
    "\\.nuxt/",
    "dist/",
    "build/",
    "\\.cache/",
    "coverage/",
    "\\.env\\.local",
    "\\.env\\..*",
    "*.log",
    "\\.pytest_cache/",
    "__pycache__/",
    "*.pyc",
    ".venv/",
    "vendor/"
]

3. Leverage Sublime Projects for Multiple Environments

Create separate .sublime-project files for different environments (staging, production, local). Each can reference a different sftp-config.json:

{
    "folders": [
        {
            "path": ".",
            "folder_exclude_patterns": ["node_modules", ".git", "dist"]
        }
    ],
    "settings": {
        "sftp_config_file": "sftp-config.staging.json"
    }
}

4. Automate Initial Project Download

Instead of letting SFTP download files one by one, use rsync for the initial sync:

# Download the entire project efficiently
rsync -avz --progress \
    --exclude 'node_modules' \
    --exclude '.git' \
    --exclude 'dist' \
    --exclude 'build' \
    dev-server:/home/developer/projects/myapp/ ./myapp/

# Upload changes efficiently
rsync -avz --delete \
    --exclude 'node_modules' \
    --exclude '.git' \
    --exclude 'dist' \
    ./myapp/ dev-server:/home/developer/projects/myapp/

5. Keep a Local Terminal Handy

Even with Terminus inside Sublime Text, maintain a dedicated terminal window for long-running processes like log tails and database sessions:

# Tail remote logs in a background terminal
ssh dev-server 'tail -f /var/log/myapp/app.log'

# Open a persistent tmux session on the server
ssh dev-server -t 'tmux attach || tmux new'

6. Secure Your Credentials

Never hardcode passwords in sftp-config.json. Always use SSH keys, and if you must store credentials, use environment variables or a secrets manager. Add sftp-config.json to your .gitignore:

# .gitignore
sftp-config.json
sftp-config.*.json
sftp-settings.json

7. Handle Large Files and Binary Assets

For projects with large binary assets (images, videos, compiled binaries), exclude them from SFTP syncing and use a CDN or object storage instead. Configure your sync to skip files above a certain size by adding a custom script:

"ignore_regexes": [
    ".*\\.(zip|tar|gz|rar|7z|mp4|mov|avi|mkv|iso|dmg)$",
    ".*\\.(png|jpg|jpeg|gif|bmp|tiff|psd|ai|sketch)$"
]

Troubleshooting Common Issues

Connection Timeouts

If SFTP connections drop frequently, increase the keepalive interval and add ServerAliveInterval to your SSH config. Also check if your network or VPN is interfering with long-lived TCP connections.

Permission Denied Errors

Ensure your SSH key has the correct permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/config

File Encoding Issues

If you see garbled characters in remote files, verify the remote_encoding setting in your SFTP config matches the server's locale. Run locale on the remote server to check.

Slow Sync Performance

For large projects, disable upload_on_save temporarily and batch-upload using SFTP: Sync Local → Remote. Also enable SSH compression by adding Compression yes to your SSH config.

Comparing the Methods

Method	Best For	Pros	Cons
SFTP Package	Most workflows	Easy setup, automatic sync	Requires local copy of files
Terminus + SSH	Running commands	Full terminal in editor	No file sync by itself
SSHFS Mount	Transparent editing	No sync needed, works with all tools	Network-dependent, can be slow
RemoteSubl	Quick single-file edits	No local copy needed	One file at a time, requires tunnel
Docker + SSH	Containerized dev	Reproducible environment	More setup overhead

Conclusion

Sublime Text may not ship with remote development features out of the box, but its extensible plugin ecosystem and integration with standard Unix tools make it a surprisingly capable remote development environment. Whether you choose the SFTP package for automatic file synchronization, SSHFS for transparent filesystem mounting, Terminus for in-editor terminal access, or RemoteSubl for quick single-file edits, you can build a workflow that matches your needs and preferences. The key is to combine multiple methods: use SFTP for file syncing, Terminus for running commands, and rsync for bulk operations. By following the best practices outlined in this guide — optimizing SSH settings, securing credentials, excluding unnecessary files from sync, and leveraging Sublime projects for multi-environment setups — you'll enjoy a fast, reliable, and productive remote development experience that takes full advantage of Sublime Text's legendary speed and simplicity.