# Set up Remote IDE


After administrators complete the instructions in [Connect your Remote IDE to SageMaker spaces with remote access](remote-access.md), you can connect your Remote IDE to your remote SageMaker spaces.

**Topics**
+ [

## Set up your local environment
](#remote-access-local-ide-setup-local-environment)
+ [

## Connect to your Remote IDE
](#remote-access-local-ide-setup-local-vs-code)
+ [

# Connect to VPC with subnets without internet access
](remote-access-local-ide-setup-vpc-no-internet.md)
+ [

# Filter your Studio spaces
](remote-access-local-ide-setup-filter.md)

## Set up your local environment


Install your preferred Remote IDE on your local machine:
+ [Visual Studio Code](https://code.visualstudio.com/)
+ [Kiro](https://kiro.dev/)
+ [Cursor](https://cursor.com/home)

For information on the version requirements, see [IDE version requirements](remote-access.md#remote-access-ide-version-requirements).

## Connect to your Remote IDE


Before you can establish a connection from your Remote IDE to your remote SageMaker spaces, your administrator must [Set up remote access](remote-access-remote-setup.md). Your administrator sets up a specific method for you to establish a connection. Choose the method that was set up for you.

**Topics**
+ [

### Method 1: Deep link from Studio UI
](#remote-access-local-ide-setup-local-vs-code-method-1-deep-link-from-studio-ui)
+ [

### Method 2: Amazon Toolkit in the Remote IDE
](#remote-access-local-ide-setup-local-vs-code-method-2-aws-toolkit-in-vs-code)
+ [

### Method 3: Connect from the terminal via SSH CLI
](#remote-access-local-ide-setup-local-vs-code-method-3-connect-from-the-terminal-via-ssh-cli)

### Method 1: Deep link from Studio UI


Use the following procedure to establish a connection using deep link.

1. [Launch Amazon SageMaker Studio](https://docs.amazonaws.cn/sagemaker/latest/dg/studio-updated-launch.html#studio-updated-launch-console).

1. In the Studio UI, navigate to your space.

1. Choose **Open in VS Code**, **Open in Kiro**, or **Open in Cursor** button for your preferred IDE. Ensure that your preferred IDE is already installed on your local computer.

1. When prompted, confirm to open your IDE. Your IDE opens with another pop-up to confirm. Once completed, the remote connection is established.

### Method 2: Amazon Toolkit in the Remote IDE


Use the following procedure to establish a connection using the Amazon Toolkit for Visual Studio Code. This method is available for VS Code, Kiro, and Cursor.

1. Open your Remote IDE (VS Code, Kiro, or Cursor).

1. Open the Amazon Toolkit extension.

1. [Connect to Amazon](https://docs.amazonaws.cn/toolkit-for-vscode/latest/userguide/connect.html).

1. In the Amazon Explorer, expand **SageMaker AI**, then expand **Studio**.

1. Find your Studio space.

1. Choose the **Connect** icon next to your space to start it.
**Note**  
Stop and restart the space in the Toolkit for Visual Studio to enable remote access, if not already connected.
If the space is not using a supported [instance size](https://docs.amazonaws.cn/sagemaker/latest/dg/remote-access.html#remote-access-instance-requirements), you will be asked to change the instance.

### Method 3: Connect from the terminal via SSH CLI


Choose one of the following platform options to view the procedure to establish a connection using the SSH CLI.

**Note**  
Ensure that you have the latest versions of the [Local machine prerequisites](remote-access.md#remote-access-local-prerequisites) installed before following the instructions below.
If you [Bring your own image (BYOI)](studio-updated-byoi.md), ensure you have installed the required dependencies listed in [Image requirements](remote-access.md#remote-access-image-requirements) before proceeding

------
#### [ Linux/macOS ]

Create a shell script (for example, `/home/user/sagemaker_connect.sh`):

```
#!/bin/bash
# Disable the -x option if printing each command is not needed.
set -exuo pipefail

SPACE_ARN="$1"
AWS_PROFILE="${2:-}"

# Validate ARN and extract region
if [[ "$SPACE_ARN" =~ ^arn:aws[-a-z]*:sagemaker:([a-z0-9-]+):[0-9]{12}:space\/[^\/]+\/[^\/]+$ ]]; then
    AWS_REGION="${BASH_REMATCH[1]}"
else
    echo "Error: Invalid SageMaker Studio Space ARN format."
    exit 1
fi

# Optional profile flag
PROFILE_ARG=()
if [[ -n "$AWS_PROFILE" ]]; then
    PROFILE_ARG=(--profile "$AWS_PROFILE")
fi

# Start session
START_SESSION_JSON=$(aws sagemaker start-session \
    --resource-identifier "$SPACE_ARN" \
    --region "${AWS_REGION}" \
    "${PROFILE_ARG[@]}")

# Extract fields using grep and sed
SESSION_ID=$(echo "$START_SESSION_JSON" | grep -o '"SessionId": "[^"]*"' | sed 's/.*: "//;s/"$//')
STREAM_URL=$(echo "$START_SESSION_JSON" | grep -o '"StreamUrl": "[^"]*"' | sed 's/.*: "//;s/"$//')
TOKEN=$(echo "$START_SESSION_JSON" | grep -o '"TokenValue": "[^"]*"' | sed 's/.*: "//;s/"$//')

# Validate extracted values
if [[ -z "$SESSION_ID" || -z "$STREAM_URL" || -z "$TOKEN" ]]; then
    echo "Error: Failed to extract session information from sagemaker start session response."
    exit 1
fi

# Call session-manager-plugin
session-manager-plugin \
    "{\"streamUrl\":\"$STREAM_URL\",\"tokenValue\":\"$TOKEN\",\"sessionId\":\"$SESSION_ID\"}" \
    "$AWS_REGION" "StartSession"
```

1. Make the script executable:

   ```
   chmod +x /home/user/sagemaker_connect.sh
   ```

1. Configure `$HOME/.ssh/config` to add the following entry:

```
Host space-name
  HostName 'arn:PARTITION:sagemaker:us-east-1:111122223333:space/domain-id/space-name'
  ProxyCommand '/home/user/sagemaker_connect.sh' '%h'
  ForwardAgent yes
  AddKeysToAgent yes
  StrictHostKeyChecking accept-new
```

For example, the `PARTITION` can be `aws`.

If you need to use a [named Amazon credential profile](https://docs.amazonaws.cn/cli/v1/userguide/cli-configure-files.html#cli-configure-files-using-profiles), change the proxy command as follows:

```
  ProxyCommand '/home/user/sagemaker_connect.sh' '%h' YOUR_CREDENTIAL_PROFILE_NAME
```
+ Connect via SSH or run SCP command:

```
ssh space-name
scp file_abc space-name:/tmp/
```

------
#### [ Windows ]

**Prerequisites for Windows:**
+ PowerShell 5.1 or later
+ SSH client (OpenSSH recommended)

Create a PowerShell script (for example, `C:\Users\user-name\sagemaker_connect.ps1`):

```
# sagemaker_connect.ps1
param(
    [Parameter(Mandatory=$true)]
    [string]$SpaceArn,

    [Parameter(Mandatory=$false)]
    [string]$AwsProfile = ""
)

# Enable error handling
$ErrorActionPreference = "Stop"

# Validate ARN and extract region
if ($SpaceArn -match "^arn:aws[-a-z]*:sagemaker:([a-z0-9-]+):[0-9]{12}:space\/[^\/]+\/[^\/]+$") {
    $AwsRegion = $Matches[1]
} else {
    Write-Error "Error: Invalid SageMaker Studio Space ARN format."
    exit 1
}

# Build Amazon CLI command
$awsCommand = @("sagemaker", "start-session", "--resource-identifier", $SpaceArn, "--region", $AwsRegion)

if ($AwsProfile) {
    $awsCommand += @("--profile", $AwsProfile)
}

try {
    # Start session and capture output
    Write-Host "Starting SageMaker session..." -ForegroundColor Green
    $startSessionOutput = & aws @awsCommand

    # Try to parse JSON response
    try {
        $sessionData = $startSessionOutput | ConvertFrom-Json
    } catch {
        Write-Error "Failed to parse JSON response: $_"
        Write-Host "Raw response was:" -ForegroundColor Yellow
        Write-Host $startSessionOutput
        exit 1
    }

    $sessionId = $sessionData.SessionId
    $streamUrl = $sessionData.StreamUrl
    $token = $sessionData.TokenValue

    # Validate extracted values
    if (-not $sessionId -or -not $streamUrl -or -not $token) {
        Write-Error "Error: Failed to extract session information from sagemaker start session response."
        Write-Host "Parsed response was:" -ForegroundColor Yellow
        Write-Host ($sessionData | ConvertTo-Json)
        exit 1
    }

    Write-Host "Session started successfully. Connecting..." -ForegroundColor Green

    # Create session manager plugin command
    $sessionJson = @{
        streamUrl = $streamUrl
        tokenValue = $token
        sessionId = $sessionId
    } | ConvertTo-Json -Compress

    # Escape the JSON string
    $escapedJson = $sessionJson -replace '"', '\"'

    # Call session-manager-plugin
    & session-manager-plugin "$escapedJson" $AwsRegion "StartSession"

} catch {
    Write-Error "Failed to start session: $_"
    exit 1
}
```
+ Configure `C:\Users\user-name\.ssh\config` to add the following entry:

```
Host space-name                            
  HostName "arn:aws:sagemaker:us-east-1:111122223333:space/domain-id/space-name"
  ProxyCommand "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe" -ExecutionPolicy RemoteSigned -File "C:\\Users\\user-name\\sagemaker_connect.ps1" "%h"
  ForwardAgent yes
  AddKeysToAgent yes
  User sagemaker-user
  StrictHostKeyChecking accept-new
```

------

# Connect to VPC with subnets without internet access
Connect to private subnet with no internet access

Before connecting your Remote IDE to Studio spaces in private subnets without internet access, ensure your administrator has [Set up Studio to run with subnets without internet access within a VPC](remote-access-remote-setup-vpc-subnets-without-internet-access.md).

You have the following options to connect your Remote IDE to Studio spaces in private subnets:
+ Set up HTTP Proxy (supported for VS Code and Kiro)
+ Pre-packaged remote server and extensions (VS Code only)

**Important**  
Cursor is not supported for connecting to Studio spaces in private subnets without outbound internet access.

**Topics**
+ [

## HTTP Proxy with controlled allow-listing
](#remote-access-local-ide-setup-vpc-no-internet-http-proxy-with-controlled-allow-listing)
+ [

## Pre-packaged remote server and extensions (VS Code only)
](#remote-access-local-ide-setup-vpc-no-internet-pre-packaged-vs-code-remote-server-and-extensions)

## HTTP Proxy with controlled allow-listing


When your Studio space is behind a firewall or proxy, ask your administrator to allow access to your IDE server and extension-related CDNs and endpoints. For more information, see [Set up HTTP Proxy with controlled allow-listing](remote-access-remote-setup-vpc-subnets-without-internet-access.md#remote-access-remote-setup-vpc-subnets-without-internet-access-setup-http-proxy-with-controlled-allow-listing).

------
#### [ VS Code ]

Configure the HTTP proxy for VS Code remote development by providing the proxy URL with the `remote.SSH.httpProxy` or `remote.SSH.httpsProxy` setting.

**Note**  
Consider enabling "Remote.SSH: Use Curl And Wget Configuration Files" to use the configuration from the remote environment’s `curlrc` and `wgetrc` files. This is so that the `curlrc` and `wgetrc` files, placed in their respective default locations in the SageMaker space, can be used for enabling certain cases.

------
#### [ Kiro ]

Configure the HTTP proxy for Kiro remote development by setting the `aws.sagemaker.ssh.kiro.httpsProxy` setting to your HTTP or HTTPS proxy endpoint.

If you use MCP (Model Context Protocol) servers in Kiro, you also need to add the proxy environment variables to your MCP server configuration:

```
"env": {
    "http_proxy": "${http_proxy}",
    "https_proxy": "${https_proxy}"
}
```

------

This option works when you are allowed to set up HTTP proxy and lets you install additional extensions flexibly, as some extensions require a public endpoint.

## Pre-packaged remote server and extensions (VS Code only)


**Note**  
This option is only available for Visual Studio Code. Kiro and Cursor do not support pre-packaged remote server setup.

When your Studio spaces can’t access external endpoints to download VS Code remote server and extensions, you can pre-package them. With this approach, your administrator can export a tarball containing the `.VS Code-server` directory for a specific version of VS Code. Then, the administrator uses a SageMaker AI Lifecycle Configuration (LCC) script to copy and extract the tarball into your home directory (`/home/sagemaker-user`). For more information, see [Set up Pre-packaged remote server and extensions (VS Code only)](remote-access-remote-setup-vpc-subnets-without-internet-access.md#remote-access-remote-setup-vpc-subnets-without-internet-access-setup-pre-packaged-vs-code-remote-server-and-extensions).

**Instructions for using pre-packaging for your VS Code remote server and extensions**

1. Install VS Code on your local machine

1. When you connect to the SageMaker space:
   + Use the Default profile to ensure compatibility with pre-packaged extensions. Otherwise, you’ll need to install extensions using downloaded VSIX files after connecting to the Studio space.
   + Choose a VS Code version specific LCC script to attach to the space when you launch the space.

### Example Dockerfile usage for pre-packaging your VS Code remote server and extensions


The following is a sample Dockerfile to launch a local container with SSH server pre-installed, if it is not possible to create a space with remote access and internet enabled.

**Note**  
In this example the SSH server does not require authentication and is only used for exporting the VS Code remote server.
The container should be built and run on an x64 architecture.

```
FROM amazonlinux:2023

# Install OpenSSH server and required tools
RUN dnf install -y \
    openssh-server \
    shadow-utils \
    passwd \
    sudo \
    tar \
    gzip \
    && dnf clean all

# Create a user with no password
RUN useradd -m -s /bin/bash sagemaker-user && \
    passwd -d sagemaker-user

# Add sagemaker-user to sudoers via wheel group
RUN usermod -aG wheel sagemaker-user && \
    echo 'sagemaker-user ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/sagemaker-user && \
    chmod 440 /etc/sudoers.d/sagemaker-user

# Configure SSH to allow empty passwords and password auth
RUN sed -i 's/^#\?PermitEmptyPasswords .*/PermitEmptyPasswords yes/' /etc/ssh/sshd_config && \
    sed -i 's/^#\?PasswordAuthentication .*/PasswordAuthentication yes/' /etc/ssh/sshd_config

# Generate SSH host keys
RUN ssh-keygen -A

# Expose SSH port
EXPOSE 22

WORKDIR /home/sagemaker-user
USER sagemaker-user

# Start SSH server
CMD ["bash"]
```

Use the following commands to build and run the container:

```
# Build the image
docker build . -t remote_server_export

# Run the container
docker run --rm -it -d \
  -v /tmp/remote_access/.VS Code-server:/home/sagemaker-user/.VS Code-server \
  -p 2222:22 \
  --name remote_server_export \
  remote_server_export
  
# change the permisson for the mounted folder
docker exec -i remote_server_export \
       bash -c 'sudo chown sagemaker-user:sagemaker-user ~/.VS Code-server'

# start the ssh server in the container 
docker exec -i remote_server_export bash -c 'sudo /usr/sbin/sshd -D &'
```

Connect using the following command:

```
ssh sagemaker-user@localhost -p 2222
```

Before this container can be connected, configure the following in the `.ssh/config` file. Afterwards you will be able to see the `remote_access_export` as a host name in the remote SSH side panel when connecting. For example:

```
Host remote_access_export
  HostName localhost
  User=sagemaker-user
  Port 2222
  ForwardAgent yes
```

Archive `/tmp/remote_access/.VS Code-server` and follow the steps in Pre-packaged VS Code remote server and extensions to connect and install the extension. After unzipping, ensure that the `.VS Code-server` folder shows as the parent folder.

```
cd /tmp/remote_access/
sudo tar -czvf VS Code-server-with-extensions-for-1.100.2.tar.gz .VS Code-server
```

### Example LCC script (LCC-install-VS Code-server-v1.100.2)


The following is an example of how to install a specific version of VS Code remote server.

```
#!/bin/bash

set -x

remote_server_file=VS Code-server-with-extensions-for-1.100.2.tar.gz

if [ ! -d "${HOME}/.VS Code-server" ]; then
    cd /tmp
    aws s3 cp s3://S3_BUCKET/remote_access/${remote_server_file} .
    tar -xzvf ${remote_server_file}
    mv .VS Code-server "${HOME}"
    rm ${remote_server_file}
else
    echo "${HOME}/.VS Code-server already exists, skipping download and install."
fi
```

# Filter your Studio spaces


You can use filtering to display only the relevant Amazon SageMaker AI spaces in the Amazon Toolkit for Visual Studio Code explorer. The following provides information on manual filtering and automated filtering. For more information on the definitions of manual and automatic filtering, see [Filtering overview](remote-access-remote-setup-filter.md#remote-access-remote-setup-filter-overview).

This setup only applies when using the [Method 2: Amazon Toolkit in the Remote IDE](remote-access-local-ide-setup.md#remote-access-local-ide-setup-local-vs-code-method-2-aws-toolkit-in-vs-code) method to connect from your Remote IDE to Amazon SageMaker Studio spaces. See [Set up remote access](remote-access-remote-setup.md) for more information.

**Topics**
+ [

## Manual filtering
](#remote-access-local-ide-setup-filter-manual)
+ [

## Automatic filtering setup when using IAM credentials to sign-in
](#remote-access-local-ide-setup-filter-automatic-IAM-credentials)

## Manual filtering


To manually filter displayed spaces:
+ Open your Remote IDE and navigate to the Toolkit for VS Code side panel explorer
+ Find the **SageMaker AI** section
+ Choose the filter icon on the right of the SageMaker AI section header. This will open a dropdown menu.
+ In the dropdown menu, select the user profiles for which you want to display spaces

## Automatic filtering setup when using IAM credentials to sign-in


Automated filtering depends on the authentication method during sign-in. See [Connecting to Amazon from the Toolkit](https://docs.amazonaws.cn/toolkit-for-vscode/latest/userguide/connect.html#connect-to-aws) in the Toolkit for VS Code User Guide for more information.

When you authenticate and connect with **IAM Credentials**, automated filtering requires [Set up when connecting with IAM credentials](remote-access-remote-setup-filter.md#remote-access-remote-setup-filter-set-up-iam-credentials). Without this setup, if users opt-in for identity filtering, no spaces will be shown.

Once the above is set up, Amazon Toolkit matches spaces belonging to user profiles that start with the authenticated IAM user name or assumed role session name.

Automatic filtering is opt-in for users:
+ Open your Remote IDE settings
+ Navigate to the **Amazon Toolkit** extension
+ Find **Enable Identity Filtering**
+ Choose to enable automatic filtration of spaces based on your Amazon identity