Skip to main content

Connecting to a Remote Pieces OS Instance

info

If Pieces OS is running on the same machine as VS Code, there should be no requirement to use this feature. Please verify these steps are required for your set up before following this guide. This custom URL is not the same thing as your Pieces Cloud custom url.

Through multiple user support tickets, we have noticed that many of our users are using the Pieces for Developers VS Code extension in a remote development environment.

This guide will walk you through how to connect to a remote Pieces OS instance using the Pieces for Developers VS Code extension.

This is currently only available for the Pieces for Developers VS Code extension. Functionality for the rest of the Pieces for Developers ecosystem is coming soon.

Windows Subsystem for Linux (WSL)​

Windows Subsystem for Linux (WSL) must be installed and configured on your machine

This integration should work out of the box with WSL. If you are having trouble connecting, please see the Troubleshooting section for steps on how to set up an inbound firewall rule.

VS Code Dev Containers​

As of the 1.12.0 release of the extension, Dev Container environments should also work with no extra configuration required. Once again, if you have trouble connecting please see Troubleshooting.

Troubleshooting​

Pieces OS is not connecting on WSL​

For WSL users, if the connection does not work automatically, you can either enable 'mirrored' networking or set up an inbound firewall rule to allow the connection.

Mirrored networking is the simplest way to resolve WSL connection issues, it requires WSL >= 2.0.0 and Windows 11.

How to set up mirrored networking (recommended): source

  1. Locate your .wslconfig file located at (windows_user_profile)/.wslconfig i.e: 'C:\Users\caleb\.wslconfig'. If the .wslconfig file is not present, then create it at the specified path
  2. If there is not a section labeled '[wsl2]', create one.
  3. Add a line under the [wsl2] section that says: 'networkingMode=mirrored'
  4. By the end of these steps your .wslconfig file should look something like:
[wsl2]
networkingMode=mirrored
  1. Restart WSL by running wsl --shutdown and wsl in a Windows command prompt

How to set up the firewall rule:

  1. Open Windows Firewall: Press Win + R, search firewall.cpl, and press Enter.
  2. In the left pane, click on Advanced settings to open the Windows Firewall with Advanced Security.
  3. In the left pane, click on Inbound Rules.
  4. On the right pane, click on New Rule.
  5. Rule Type: Select Port and click Next.
  6. Protocol and Ports: Choose TCP and specify port number 1000. Click Next.
  7. Action: Select Allow the connection and click Next.
  8. Profile: Choose Public, Private, and Domain for the profile.
  9. Name: Give the rule a name like Local Devices on Port 1000, and click Finish.

Pieces OS is not connecting on Dev Containers​

For Dev Container users, if the connection does not work automatically, there are a couple of troubleshooting steps to take.

  1. You must ensure that Pieces OS is running before launching VS Code. Please try starting Pieces OS and then reloading your VS Code window. a. see this guide for how to reload your VS Code window
  2. Similarly to the WSL troubleshooting guide above, there may be a firewall that is blocking requests between machines on your LAN. Try setting up an inbound firewall rule on the machine running Pieces OS to resolve this. a. for Windows and macOS the rule should be placed on port 1000 b. on linux, the rule should be placed on port 5323

Use Cases​

Prerequisites​

Getting Started​

Using the Custom URL Feature to Access a Remote Pieces OS Instance​

  • In the case that Pieces OS shares the same LAN with your remote VS Code instance, you should use the LAN IP address of your machine that is running Pieces OS.
  • In the case that Pieces OS is not on the same LAN as your development environment ngrok, or a similar alternative like Tailscale, must be installed on the machine with Pieces OS. It must be known that doing this will expose your Pieces OS endpoints to the public and this should only be done as a last resort.
  • The custom URL feature has no connection to your custom Pieces Cloud domain, attempting to use your custom Pieces Cloud domain i.e: https://caleb.pieces.cloud will result in the VS Code extension ceasing to function properly.
  1. Ensure that there is not a firewall in place that will block connection between two machines on your LAN.
  2. Locate your machine's LAN IP address a. If possible, you should also set up a DHCP IP reservation for your machine running Pieces OS so this IP address will not change in the future.
  3. Your custom URL will be: a. Linux: http://{'{LAN IP ADDRESS}'}:5323 b. macOS or Windows: http://{'{LAN IP ADDRESS}'}:1000

A generated a ngrok tunnel URL

Setting up your Pieces VS Code extension​

Now we will set up your Pieces VS Code extension to connect to your machine with Pieces OS.

  1. Open VS Code on your machine
  2. Go to VS Code Settings ⌘/CTRL + ,
  3. Ensure that you have the Workspace tab selected
  4. Search pieces custom url
  5. Paste your new forwarding URL in the input for Pieces: Custom Url

Configuring your VS Code extension to talk to a remote Pieces OS instance

Reloading your VS Code window​

Now we will reload your VS Code window to ensure that your Pieces VS Code extension is using your ngrok forwarding URL.

  1. Open up the Command Palette ⌘/CTRL + Shift + P
  2. Search Reload Window
  3. Select Developer: Reload Window

Reloading the VS Code window