Remote Development with VSCode using thin-edge.io and go-c8y-cli

[Yishu_Zhong]

Introduction

Developing applications directly on IoT devices has always been a challenge. Traditional approaches often require complex VPN setups or physical access to devices. However, with Cumulocity’s Cloud Remote Access feature combined with thin-edge.io and C8Y CLI, you can achieve seamless remote development using VSCode without any VPN infrastructure.

This article demonstrates how to set up a complete remote development environment that allows you to:

• Connect to your IoT devices securely through Cumulocity
• Use VSCode’s powerful remote development features
• Edit, debug, and run code directly on edge devices
• Accomplish all of this without requiring VPN or complex network configurations

The solution architecture is straightforward:

This approach offers several advantages over traditional VPN solutions:

• No VPN required: All connections are tunneled through secure WebSocket connections
• Simplified setup: No complex network configurations or firewall rules
• Secure by default: Authentication and encryption handled by Cumulocity
• Familiar VSCode interface: Use your existing VSCode features for remote development

Understanding the Key Components

Before diving into the setup, let’s understand the three key components that make this solution work.

thin-edge - The Device-Side Agent

thin-edge.io is a lightweight, open-source framework designed specifically for edge devices. It’s the production-ready agent that runs on your IoT device and provides comprehensive device management capabilities, including built-in support for Cloud Remote Access.

thin-edge.io acts as the bridge between your device and Cumulocity, establishing a secure WebSocket connection that enables remote access capabilities. The built-in Cloud Remote Access support means no additional configuration is needed beyond the standard thin-edge.io setup.

C8Y CLI - The Local Proxy Bridge

The C8Y CLI is a tool written in Go that provides a Command-Line Interface to access Cumulocity functionality. It also provides the option to establish a local proxy to the device that is securely proxied via the Cumulocity platform.

The local proxy runs on your development machine and creates a local TCP endpoint that VSCode can connect to. It then tunnels all traffic through the secure WebSocket connection established by thin-edge.io. The c8y remoteaccess server command provides Passthrough mode support, allowing native SSH clients like VSCode to connect seamlessly.

VSCode Remote - SSH Extension

VSCode’s Remote - SSH extension enables you to connect to remote machines over SSH and develop as if you were working locally. In our setup, VSCode connects to the local proxy endpoint created by C8Y CLI, which transparently forwards the connection to your remote device.

Prerequisites

Before starting the setup, ensure you have the following:

• Cumulocity tenant with Cloud Remote Access feature enabled
  • Your Cumulocity user must have the “Remote Access” admin permission
• Device running thin-edge.io agent
  • Thin-edge.io device must be bootstrapped and connected to your Cumulocity tenant
  • SSH server must be running on the device
• VSCode installed locally on your development machine with Remote - SSH extension installed
  • Download VSCode from code.visualstudio.com and find the SSH Extension in VSCode’s extension marketplace
  • This setup also works with other VSCode-based IDEs such as Cursor
• C8Y CLI installed and configured on your development machine
  • Installation instructions available at C8Y CLI’s website

Step-by-Step Setup Guide

Configuring Cloud Remote Access Passthrough

To enable remote development, we need to configure a Passthrough endpoint. This allows native SSH clients (like VSCode) to connect through the Cloud Remote Access tunnel.

There are multiple ways you can create the configuration:

• UI - If you prefer being guided by a UI, continue here.
• CLI - If you prefer a single CLI command, continue here.
• API - If you prefer using the API with tools like curl or Postman, continue here

Creating Passthrough Configuration via UI

1. Navigate to Device Management in your Cumulocity tenant
2. Select your device from the device list
3. Go to the Remote Access tab
4. Click Add endpoint
5. Select PASSTHROUGH as Protocol
6. Fill in the configuration:

• Name: native-ssh (or any descriptive name)
• Hostname: 127.0.0.1 (localhost on the device)
• Port: 22 (SSH default port)

7. Click Save

Creating Passthrough Configuration via C8Y CLI

You can also create a Passthrough Configuration using one command with C8Y CLI:

c8y remoteaccess configurations create-passthrough --device <device-name> --name "Passthrough" --port 22

Replace <device-name> with your device’s name. This method is simpler than using the REST API as it handles authentication automatically through your C8Y CLI session.

Creating Passthrough Configuration via API

Alternatively, you can create the configuration using the Cumulocity REST API:

curl -X POST "https://<url>/service/remoteaccess/devices/<device-id>/configurations" \

-H "Authorization: Basic <base64(tenant/user:password)>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "name": "native-ssh",
    "hostname": "127.0.0.1",
    "port": 22,
    "protocol": "PASSTHROUGH",
    "credentialsType": "NONE"
}'

Replace:

• <url> with your Cumulocity tenant URL
• <device-id> with your device’s internal ID (found in Device Management)
• <base64(tenant/user:password)> with your base64-encoded user credentials

Verifying Configuration

After creating the configuration, you should see your Passthrough endpoint listed with a connection endpoint URL.

Running the Local Proxy

Make sure C8Y CLI is configured with your Cumulocity session. For detailed setup instructions, refer to the C8Y CLI documentation.

Starting the Proxy Server

Use the c8y remoteaccess server command to start the local proxy:

c8y remoteaccess server --device <device-name> --configuration <endpoint-name> --listen "127.0.0.1:0"

Replace <device-name> with your device’s name and <endpoint-name> with the endpoint name you defined in the previous step. You can also specify a custom port instead of 0 (e.g., "127.0.0.1:2222").

The --listen "127.0.0.1:0" option tells C8Y CLI to:

• Listen on localhost (127.0.0.1)
• Use a random available port (0 means auto-select)

Example output:

Important: Note the port number (49996 in this example) - you’ll need it for the VSCode configuration.

Configuring VSCode Remote - SSH

Now we’ll configure VSCode to connect through the local proxy to your remote device.

Configuring SSH Config File

VSCode uses your SSH config file to manage remote connections. Edit ~/.ssh/config (or C:\Users\.ssh\config on Windows):

Host cumulocity-device
  HostName 127.0.0.1
  Port 49996
  User iotadmin

Replace:

• Port 49996 with the port number from your C8Y CLI proxy (or use your fixed port)
• User iotadmin with the username on your device (commonly iotadmin for thin-edge.io demo containers, or your actual device username like admin)

Testing SSH Connection (Optional)

Before connecting with VSCode, test the SSH connection from your terminal:

ssh cumulocity-device

You should be prompted for a password and then connected to your device. If this works, VSCode will work too. The SSH connection will use password authentication by default.

Connecting and Developing with VSCode

Now that everything is configured, let’s connect to your device and start developing.

Establishing Remote Connection

1. Open VSCode
2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Type: Remote-SSH: Connect to Host
4. Select: cumulocity-device (or whatever you named your host in SSH config)
5. Enter password (if not using SSH keys)

VSCode will:

• Connect to the local proxy
• Establish the remote connection through Cloud Remote Access
• Open a new VSCode window connected to your device

You’ll see “SSH: cumulocity-device” in the bottom-left corner when connected.

Opening Remote Folder/Workspace

Once connected:

1. Open Folder (File → Open Folder / Cmd+O / Ctrl+O)
2. Navigate to your project directory on the device (e.g., /home/iotadmin/project)
3. Select the folder

VSCode will load the workspace and you can start editing files directly on the device.

Installing VSCode Extensions on Remote Device

Extensions need to be installed on the remote device for full functionality:

1. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
2. Install extensions as usual
3. VSCode will automatically install them on the remote device

Extensions are installed separately for local and remote environments, so you may need to reinstall your favorite extensions.

Using Integrated Terminal

The integrated terminal in VSCode runs directly on your remote device:

1. Open Terminal (Ctrl+ / Cmd+)
2. Run commands as if you were SSH’d into the device
3. Multiple terminals can be opened simultaneously

File Editing and Synchronization

• Edit files directly - changes are saved immediately on the device
• No file sync needed - you’re working directly on the remote filesystem
• Git operations work normally - clone, commit, push from the remote terminal
• Real-time collaboration - multiple developers can connect to the same device (with proper permissions)

Real-Time Development Workflow

With this setup, you can:

• Edit code directly on the device
• Run applications in the integrated terminal
• Debug applications using VSCode’s debugger
• Use Git for version control
• Test on actual hardware in real-time

Everything works as if you were developing locally, but you’re actually working on a remote IoT device through Cumulocity’s secure Cloud Remote Access.

Next Steps

For more information about thin-edge.io, see the official documentation. Additional resources are available in the C8Y CLI documentation and the Cloud Remote Access guide.

How to get started with Cloud Remote Access for Cumulocity IoT

Introduction Update Sep 2024: Change default agent to thin-edge. Using go-c8y-cli as default local proxy for Passthrough Update Jan 2024: I’ve updated some links and added a chapter to tunnel a local HTTP proxy directly to the C8Y UI. Last year, I published an article roughly describing the Cloud Remote Access Feature of Cumulocity IoT. Since then I received a lot of requests on how to use it in detail and decided to write another knowledge base article going into detail and covering all …