Skip to content
| Marketplace
Sign in
Visual Studio Code>Debuggers>tOS RemoteNew to Visual Studio Code? Get it now.
tOS Remote

tOS Remote

PlanXLab

|
40 installs
| (0) | Free
Open, edit, run, and debug the workspace of a tOS (Raspberry Pi 5) board from VS Code on your PC, and run Jupyter cells on the board. No VS Code Server is installed on the board.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

tOS Remote

English | 한국어

This VS Code extension allows you to open a workspace on a target board—which runs an SSH/FTP/SFTP server—directly from VS Code on your PC. It enables you to edit, execute, and debug vision inference code on the board. You can also run Jupyter cells (defined by #%% in Python files or within notebook files) on the board.

Nothing is installed on the board for VS Code: no VS Code Server is needed. The extension uses only the SSH (SFTP) server already running on the board, so it uses no extra memory on the board.

Features

  • Open/close the remote workspace: Syncs the board's working folder (default /home/<account>/Workspace) to a user-specified local SSD folder, opening it in VS Code with instant background SFTP upload on save.

  • Sidebar panel: Board host, user, workspace, and local folder settings, connection test, SSH key registration, prerequisites (rclone, OpenSSH, uv), board tools (debugpy, Jupyter), and tools.

  • Getting Started walkthrough: Guides you step by step: install rclone → board settings → register an SSH key → open the workspace. Steps that are already done are checked automatically; you do not need to select Mark Done.

  • SSH terminal: The default terminal of the workspace opens a shell on the board. If VS Code restores local terminals from an earlier session when the workspace window opens, they are replaced with the board terminal.

  • Run/debug (for Python files in the remote workspace window)

    Action How
    Debug on tOS F5, or Debug on tOS in the Run button menu
    Run on tOS (without the debugger) Ctrl+F5, or the Run button at the top right of the editor (Run on tOS)
    • Output appears in the Run on tOS: <file> task in the terminal panel. The file is saved and its upload to the board is completed before it runs. When the program exits, the terminal displays a termination message and waits for a key press.
    • The ssh command line is hidden; a lost connection is reported in one line.
    • If debugpy is not installed on the board, F5 offers to install it (see Board tools) and then starts debugging.
    • Run Python File in the Run button menu (from the Python extension) runs with the local Python on your PC, so do not use it in the remote workspace. The Run button remembers the last item you chose.
    • You do not need Ctrl+Shift+B (build task) to run on tOS.
  • Board tools: Installs debugpy (remote debugging) and jupyter_server + ipykernel (Jupyter) into the board's global Python environment when they are missing. Nothing is installed if they are already there.

    • The board does not need internet access. Your PC resolves the packages for the board's Python version and platform with uv, downloads them from PyPI (SHA-256 verified), copies them to a temporary folder on the board, and installs them with sudo pip install (on tOS, pip installs into the global environment with uv). The temporary folder is deleted afterwards.
    • Any Python 3 version on the board works as long as the packages support it (checked with Python 3.8 to 3.14).
    • The sudo password is taken from the saved board password, or asked for when needed. It is sent only inside the script given to the board over SSH, never on a command line or in a log.
    • /usr/local/bin/run_debug.sh (the debugpy launcher of the tOS image) is created with execute permission if it does not exist. An existing file is not changed.
  • Jupyter on the board: Starts a Jupyter server on the board in the background (listening only on 127.0.0.1, with a token), forwards it to your PC over SSH, and adds it to the Jupyter extension's kernel picker as tOS Remote. Cells (#%% in Python files, notebooks) then run on the board, keeping their state between cells.

  • Terminal path links: Ctrl+click a /home/<account>/Workspace/... path printed in the terminal (Python traceback, gcc, and pdb formats) to open that line in the local file. Board site-packages paths open the local cached copy.

  • IntelliSense: Only the .py/.pyi files of the board's Python packages are copied locally for Pylance.

    • The global site-packages are required; a notification is shown if syncing them fails.
    • ~/.local user packages and virtual environments in the workspace (folders with pyvenv.cfg, such as those created by uv venv, up to two levels deep) are optional; if they are missing or fail to sync, this is only logged.
    • Virtual environments created while you work are detected again when you select Sync Python Libraries in the panel.
  • Connection watchdog: If the rclone daemon exits or connection drops, the extension reconnects automatically.

  • Robust SSH terminal: If the connection fails, it retries up to 3 times at 2-second intervals. Run tasks display a termination message and wait for a key press when the remote process exits.

  • Display language: Korean when the VS Code display language is Korean; English otherwise (only English and Korean are supported). To use Korean, install the Korean Language Pack and set VS Code's display language to Korean. Logs in the Output panel are written in English only. The Details and Changelog tabs of the extension page are always shown in English (README.md, CHANGELOG.md) because VS Code does not support per-language documents; the Korean versions are README.ko.md and CHANGELOG.ko.md.

Requirements

Item Description
Windows 10/11, Linux, macOS x64 and arm64.
OpenSSH client Install the OpenSSH client and key generator (ssh, ssh-keygen) for your OS. Windows includes an optional OpenSSH Client feature.
rclone Version 1.65.0 or newer. The extension reuses a supported installation first. If missing, it tries winget/Scoop/Chocolatey, Homebrew/MacPorts, or apt/dnf/pacman/zypper/yum/apk in a terminal (which may request administrator/sudo approval). If unavailable or unsuitable, it offers the official SHA-256-verified download. On Linux, the download fallback requires unzip or bsdtar. For offline use, set tosRemote.rclonePath.
Python Debugger extension (ms-python.debugpy) Required for remote debugging (F5).
Jupyter extension (ms-toolsai.jupyter) Optional; install it when you want to run Jupyter cells on the board.
uv Version 0.8.0 or newer; needed only to install board tools. An installed uv is reused without upgrading it; otherwise the extension downloads a matching Windows/Linux/macOS build from PyPI and verifies its SHA-256. The first resolution also downloads a Python runtime for uv (about 21 MB). Your computer must be online when installing board tools.
debugpy, jupyter_server, ipykernel on the board Installed from the panel (Board Tools) if missing.

Usage

  1. After installation, the Getting Started walkthrough opens. If you closed it, run tOS: Getting Started from the Command Palette.
  2. Select the tOS Remote icon in the activity bar, check the board host, user, and workspace folder, then select Test Connection.
    • The workspace is always under the user's home directory, because the user has full access only there. /home// is shown automatically from the User field; enter only the rest (for example Workspace or class/vision). The folder, including intermediate folders, is created on the board when you open the workspace if it does not exist.
  3. Select Register SSH Key and enter the board password once. If your PC has no key, ~/.ssh/id_ed25519 is created and added to ~/.ssh/authorized_keys on the board.
  4. Select Open Remote Workspace. If no local workspace folder is set yet, choose a folder on your PC, then choose whether to replace the current VS Code window or open the remote workspace in a new window.
  5. When you are done, select Close Remote Workspace. The workspace closes after all pending uploads to the board finish.
  • The remote workspace can be open in only one window. If it is already open elsewhere, use Go to That Window to open VS Code's window switcher without replacing the current folder. Changes made in VS Code, your file manager, or the remote terminal are synchronized in both directions; if the same file changes on both sides, the most recently modified copy wins.
  • If you quit VS Code without closing the workspace, your local files remain intact and reconnect automatically the next time.
  • If you connect with a password only, the terminal and Run on tOS ask for the password every time. Debugging, board tools, and Jupyter use the saved password. Registering an SSH key is recommended.

Running Jupyter cells on the board

  1. Open the remote workspace and check Board Tools in the panel. If Jupyter is not installed, select Install (the sudo password of the board may be asked for).
  2. Open a notebook or a Python file with #%% cells. Jupyter starts on the board automatically and is forwarded to your PC (you can also select Start next to the Jupyter server, or run tOS: Start Jupyter on tOS).
  3. The board's kernel is selected automatically. The first time on each board, a list of the board's kernels appears once: choose the Python kernel (marked with a star). It is remembered, so later notebooks and Interactive windows use it without asking. To turn this off, set tosRemote.jupyterAutoSelectKernel to false and choose tOS Remote in Select Kernel yourself.
  4. Select Stop when you are done. Closing the remote workspace also stops the server. Idle kernels without a connection are shut down after an hour, and the server stops an hour after the last kernel and request.
#%%
import sys
#%%
print(sys.path)   # runs on the board

Settings

Setting Default Description
tosRemote.host 192.168.254.1 Board IP address
tosRemote.port 22 SSH port
tosRemote.user tos Board user account
tosRemote.remoteWorkspace Workspace Workspace folder under the user's home directory (/home/<user>/). Enter only the path after the home directory; /home/<user>/ is filled in from the user account. Created on the board if it does not exist.
tosRemote.localWorkspace (prompt on first open) Local folder on this PC where the remote workspace files are kept and synced.
tosRemote.driveLetter (auto) Legacy mount drive setting.
tosRemote.identityFile (auto) SSH private key path
tosRemote.pythonCommand python3 Python command on the board
tosRemote.debugPort 5678 debugpy port
tosRemote.pythonLibraryPaths (auto-detect) Board package paths to copy for IntelliSense. Paths set here are all treated as required.
tosRemote.pathMappings [] Additional path mappings for terminal links
tosRemote.rclonePath (auto-install) Path to an rclone executable you provide
tosRemote.packageExcludeNewer (empty) Install board packages as they were on this date (for example 2026-10-01). Use the same date on every PC to install identical versions on all boards in a class. If empty, the latest versions compatible with the board's Python are used.
tosRemote.jupyterAutoSelectKernel true Start Jupyter on the board when a notebook or #%% file is opened, and select the board's kernel automatically.

All settings are machine-specific and are not copied to other PCs by Settings Sync. Passwords are stored only in VS Code secret storage (SecretStorage), never in settings.

How It Works

VS Code (extension) ──HTTP (127.0.0.1, random port/credentials)──▶ rclone rcd (detached)
     │                                                              │ SFTP
     │ ssh (terminal, run, debug)                                   ▼
     └─────────────────────────────────────────────────────────▶ Dropbear (board)
                                     Local SSD workspace ◀──▶ Instant SFTP sync
  • rclone runs as a control server (rclone rcd) detached from the extension process, surviving window reloads and VS Code restarts.
  • The workspace file (.code-workspace) is created in the extension storage on your PC; nothing is written to the board.
  • Before running or debugging after a save, the extension flushes the sync queue so the board never runs an old file.
  • The SSH terminal runs through a platform-specific script in extension storage (.cmd on Windows, .sh on Linux/macOS), which handles connection retries and exit codes. Run on tOS uses the same approach to keep the ssh command out of the terminal output.
  • Python library sync uses at most 4 SSH connections because of the concurrent connection limit of the board (Dropbear), and starts 15 seconds after the workspace opens. The board tools (debugpy, Jupyter) are checked in the same SSH connection when the workspace opens.
  • File changes in the local workspace are uploaded to the board after a 200 ms debounce (operations/copyfile / operations/deletefile). Use Pull from Board in the panel to pull files created or modified directly on the board.
  • Board tools: uv on the PC resolves the packages for the board (--python-version and --python-platform from the board, wheels only, packages already on the board are kept). An existing supported uv on PATH, in ~/.local/bin, or in the usual package-manager binary directories is reused; otherwise a platform-matched binary is downloaded from PyPI and SHA-256 verified. The wheels are downloaded from PyPI and verified with SHA-256, copied with rclone to /tmp/tos-remote.XXXXXX (mode 0700), and installed with sudo pip install --no-index --find-links. The resolver data stays in the extension storage (including the uv Python runtime). Caches use %LOCALAPPDATA%\tOS Remote on Windows, ~/Library/Caches/tOS Remote on macOS, and $XDG_CACHE_HOME/tOS Remote or ~/.cache/tOS Remote on Linux.
  • Jupyter: the server runs on the board as the board user (python3 -m jupyter_server, 127.0.0.1, random port and token, terminals disabled), and its state and log are kept in ~/.local/state/tos-remote (mode 0700). The PC forwards a free local port to it with ssh -N -L and registers it with the Jupyter extension (createJupyterServerCollection). If the forwarding drops, it reconnects automatically while the server is running.
  • With password authentication, background ssh commands receive the saved password through SSH_ASKPASS: a small helper script (.cmd on Windows, .sh on Linux/macOS) runs VS Code's own Node.js and reads it from a one-time local channel opened by the extension.

Security Notes

  • SSH host keys are not verified, so the connection keeps working after the board is reinstalled. Use it only on trusted networks (direct connection or a lab network).
  • While remote debugging, debugpy listens on 127.0.0.1:5678 on the board and is forwarded securely to your PC through an SSH tunnel.
  • Disconnecting leaves the remote process and its SSH tunnel running. Restart saves and uploads the file, then starts the program again on the board.
  • The rclone control server listens only on 127.0.0.1 and uses random credentials each time it starts.
  • The Jupyter server listens only on 127.0.0.1 on the board and requires a random token; it is reached only through the SSH tunnel.
  • Board packages are installed into the global Python environment with sudo. The sudo password is not stored by this feature; the saved board password is reused if you saved one in the panel.

Troubleshooting

  • Check Show Log in the panel (Output panel tOS Remote) and the rclone Log. Board tool installation output is written to the same log.
  • Error that the drive is in use: set the drive to Auto in the panel or choose another letter.
  • If the connection to the board is lost, the status bar shows Reconnecting and the extension retries automatically.
  • Jupyter cells run on your PC instead of the board: select Select Kernel → tOS Remote. To see the server log on the board, select Jupyter Log in the panel.
  • Board tool installation fails with a resolution error: the board's Python version may be too old for the packages. Check the [uv] lines in the log.

Development

src/               Extension source (plain JavaScript, no build step, no runtime dependencies)
media/             Sidebar panel (html/css/js), icon, walkthrough pages (English; ko/ Korean)
l10n/              Korean translations of runtime strings (bundle.l10n.ko.json; source strings are the English in the code)
package.nls*.json  Manifest strings (English default, .ko Korean)
test/run.js        Unit tests (node test/run.js, including checks for missing translations and placeholders)
test/install.js    Network-enabled platform installer tests, followed by the unit suite with a real local SFTP server
test/integration/  VS Code extension host integration tests (local rclone SFTP server instead of the board; debug start, Restart, and Disconnect with a fake debugpy; English and Korean display languages)
scripts/build-vsix.ps1         Builds a Marketplace-uploadable .vsix without Node.js or build tools
scripts/integration-test.ps1   Runs the integration tests
node test/run.js                       # Unit tests
node test/install.js                   # Downloads/verifies rclone and uv, then runs all tests with real SFTP
.\scripts\build-vsix.ps1               # dist\tos-remote-<version>.vsix (no Node.js or build tools needed)
.\scripts\integration-test.ps1 -CodePath <Code.exe>
.\scripts\integration-test.ps1 -DebugOnly  # Debug start, Restart, and Disconnect only (no board or rclone needed)

Upload the generated .vsix from the Visual Studio Marketplace publisher page. No Node.js or vsce installation is needed to package the extension.

The integration-test launcher starts VS Code with separate test data (also for a portable VS Code), so it can run while you use VS Code. The debug phase runs once without and once with the Python Debugger extension, which is installed into the test data; pass -SkipPythonDebugger to skip the second run.

The unit suite is platform-independent. The supplied integration-test launcher is a PowerShell script for Windows; the extension host test itself uses platform-neutral paths and can also be launched from VS Code on Linux or macOS.

CI runs the installer and SFTP tests on Windows, Linux, and macOS before packaging a universal VSIX. No platform-specific native binaries are bundled.

Localization

  • Write user-facing strings in English in the source and wrap them with t('...') (src/i18n.js, which uses vscode.l10n.t). Use single-quoted strings only.
  • Add Korean translations to l10n/bundle.l10n.ko.json, keyed by the English source string. Add manifest strings to package.nls.json and package.nls.ko.json with the same key.
  • Update the documents in both English (README.md, CHANGELOG.md) and Korean (README.ko.md, CHANGELOG.ko.md).
  • node test/run.js checks for missing or unused translations and mismatched {0} placeholders.
  • The integration tests install the Korean language pack (MS-CEINTL.vscode-language-pack-ko) into an isolated extensions folder and run once more with --locale=ko. Without a network connection, pass -SkipKorean.

License

GPL-3.0-or-later. Copyright (C) PlanXLab.

This extension does not bundle rclone or uv. It uses supported rclone and uv installations already available on your computer where possible. Otherwise, rclone (MIT) is installed with an available package manager or downloaded from the official site with SHA-256 verification; uv (MIT or Apache-2.0) is downloaded from PyPI with SHA-256 verification when you first install board tools. Board packages (debugpy, Jupyter) are downloaded from PyPI when you install them.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft