Connect your local IDE to Amazon SageMaker Unified Studio spaces with remote access

Short Description

You can connect your local IDE (Visual Studio Code, Kiro, or Cursor) to Amazon SageMaker Unified Studio Spaces using a secure SSH-over-SSM tunnel. This allows you to use your customized local IDE setup—including AI-assisted development tools and custom extensions—with the scalable compute resources available in Amazon SageMaker Unified Studio. This article provides end-to-end setup instructions and troubleshooting steps for common connection issues.

Overview

A remote connection from your local IDE to SageMaker Unified Studio establishes a secure tunnel between your local development environment and a SageMaker Space. This lets you:

• Access scalable SageMaker compute resources (including GPUs) from your local environment
• Maintain security boundaries within the SageMaker framework
• Keep your familiar IDE experience with extensions, themes, and configurations

The connection uses AWS Systems Manager (SSM) Session Manager to create a secure tunnel without requiring open inbound ports.

Prerequisites

Before setting up the connection, ensure the following:

Component	Requirement
VS Code	v1.90 or later
Kiro	v0.8.0 or later
Cursor	v2.6.18 or later
AWS Toolkit extension	v3.97 or later (v3.100 or later for Cursor)
AWS CLI	v2.x (latest recommended)
Session Manager plugin	Latest version
SSH client	OpenSSH (included on macOS/Linux; install on Windows)
Operating System	macOS 13+, Windows 10/11, or Linux (official Microsoft VS Code distribution required for VS Code and Cursor on Linux)

⚠️ Important: The connection will fail silently (timeout with no clear error) if AWS CLI is not installed or not accessible from your IDE's environment. Verify with aws --version in the integrated terminal before attempting connection. If not found, install AWS CLI and fully restart your IDE to pick up the new PATH.

AWS-side requirements:

• An Amazon SageMaker Unified Studio Domain with proper network connectivity
• AWS Identity Center (SSO) setup or IAM credentials configured
• IAM permissions for sagemaker:StartSession on the space
• When logging in with an IAM role from your local IDE, ensure SageMakerStudioUserIAMConsolePolicy or equivalent permissions are attached to your role
• Space instance with at least 8 GB memory

⚠️ Important: The following instance types are NOT supported for remote access due to insufficient memory (less than 8 GB):

• ml.t3.medium
• ml.c7i.large
• ml.c6i.large
• ml.c6id.large
• ml.c5.large

Image requirements:

• SageMaker Distribution: Version 2.8 or later
• Custom images: Must follow SageMaker custom image specifications

Network requirements:

Your local machine must have network access to Session Manager endpoints:

• ssm.<region>.amazonaws.com
• ssmmessages.<region>.amazonaws.com
• ec2messages.<region>.amazonaws.com

⚠️ Important: Remote Space connections are NOT supported for TIP (Trusted Identity Propagation) enabled projects. Set enableTrustedIdentityPropagationPermissions to false to use remote connections.

Network Configuration Options

SageMaker Unified Studio Projects create Spaces in VpcOnly mode by default. Choose one of the following network configurations to support remote connections:

Option 1: Public Internet Access

Set sagemakerDomainNetworkType to PublicInternetOnly in your project configuration. This is the simplest option for development environments.

Option 2: VPC with NAT Gateway (Recommended)

Keep Spaces in VpcOnly mode and attach a NAT Gateway to your VPC to provide internet access. This is the default configuration with Unified Studio Quick Setup.

Option 3: Isolated VPC with VPC Endpoints (Most secure)

For environments requiring complete network isolation, configure VPC endpoints for the required AWS services. This requires additional setup but provides the strongest security posture.

Step 1: Configure IAM Permissions

Different connection methods require different IAM permissions. Configure the appropriate permissions based on how your users will connect.

⚠️ Important: Using broad permissions for sagemaker:StartSession with a wildcard resource * creates the risk that any user with this permission can initiate a session against any SageMaker Space in the account. For production environments, scope down permissions to specific space ARNs.

Method 1: Deep Link Permissions

For users connecting via the "Open in VS Code/Kiro/Cursor" link from the SageMaker Studio UI, attach this policy to the space execution role (or domain execution role if space execution role is not configured):

{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Sid": "RestrictStartSessionOnSpacesToUserProfile",
            "Effect": "Allow",
            "Action": ["sagemaker:StartSession"],
            "Resource": "arn:*:sagemaker:*:*:space/${sagemaker:DomainId}/*",
            "Condition": {
                "ArnLike": {
                    "sagemaker:ResourceTag/sagemaker:user-profile-arn": "arn:aws:sagemaker:*:*:user-profile/${sagemaker:DomainId}/${sagemaker:UserProfileName}"
                }
            }
        }
    ]
}

Method 2: AWS Toolkit Permissions

For users connecting through the AWS Toolkit extension in their IDE, attach this policy to:

• For IAM authentication: the IAM user or role
• For Identity Center authentication: the Permission Sets managed by IdC

{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sagemaker:ListSpaces",
                "sagemaker:DescribeSpace",
                "sagemaker:ListApps",
                "sagemaker:DescribeApp",
                "sagemaker:DescribeDomain",
                "sagemaker:UpdateSpace",
                "sagemaker:CreateApp",
                "sagemaker:DeleteApp",
                "sagemaker:AddTags"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowStartSessionOnSpaces",
            "Effect": "Allow",
            "Action": "sagemaker:StartSession",
            "Resource": [
                "arn:aws:sagemaker:<region>:<account-id>:space/<domain-id>/<space-name-1>",
                "arn:aws:sagemaker:<region>:<account-id>:space/<domain-id>/<space-name-2>"
            ]
        }
    ]
}

Important: For production environments, scope down the StartSession resource to specific space ARNs rather than using wildcards.

Method 3: SSH Terminal Permissions (SageMaker AI classic domains only)

⚠️ Note: This method is only supported for SageMaker AI (classic Studio) domains. It does not work with SageMaker Unified Studio domains.

For SSH terminal connections, the StartSession API is called by the SSH proxy command script using local AWS credentials. Attach this policy to the IAM user or role associated with the local AWS credentials (not the domain execution role):

{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Sid": "AllowStartSessionOnSpecificSpaces",
            "Effect": "Allow",
            "Action": "sagemaker:StartSession",
            "Resource": [
                "arn:aws:sagemaker:<region>:<account-id>:space/<domain-id>/<space-name-1>",
                "arn:aws:sagemaker:<region>:<account-id>:space/<domain-id>/<space-name-2>"
            ]
        }
    ]
}

Advanced: Tag-Based Access Control

For fine-grained access control based on organizational structure, you can use tag-based policies to restrict connections based on team, environment, and cost center tags:

{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Sid": "RestrictStartSessionOnTaggedSpacesInDomain",
            "Effect": "Allow",
            "Action": ["sagemaker:StartSession"],
            "Resource": ["arn:aws:sagemaker:<region>:<account-id>:space/<domain-id>/*"],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/Team": "${aws:PrincipalTag/Team}",
                    "aws:ResourceTag/Environment": "${aws:PrincipalTag/Environment}",
                    "aws:ResourceTag/CostCenter": "${aws:PrincipalTag/CostCenter}"
                }
            }
        }
    ]
}

This ensures users can only connect to spaces tagged with matching values for their assigned team, environment, and cost center.

Step 2: Enable Remote Access on Your Space

1. Navigate to Amazon SageMaker Unified Studio using your domain URL.
2. In the left navigation, choose JupyterLab or navigate to your space.
3. Choose Configure space and set the instance type to ml.m5.large or higher (minimum 8 GB memory).
4. Toggle on Remote Access.
5. Choose Save and restart to apply the changes.

Note: If connecting via the AWS Toolkit (Method 2), the Toolkit can enable remote access automatically when you attempt to connect.

Step 3: Connect from Your IDE

Choose one of the following connection methods:

Method 1: Deep Link from Studio UI (Simplest)

This method works with both IAM and Identity Center-based domains.

In Identity Center-based domains:

1. Navigate to Amazon SageMaker Unified Studio using the URL from your admin and log in using your SSO credentials.
2. In the left navigation pane, under IDEs, choose JupyterLab.
3. After your JupyterLab Notebook opens, choose Open in VS Code, Open in Kiro, or Open in Cursor in the top right corner of the page.
4. Confirm the prompt to open your IDE on your local machine.
5. In your IDE, confirm the remote connection prompt.

In IAM-based domains:

1. Navigate to Amazon SageMaker Unified Studio using the URL from your admin and log in using your IAM credentials.
2. In the left navigation, choose JupyterLab.
3. After your JupyterLab Notebook opens, choose Open in VS Code in the top right corner of the page. This will establish a remote connection and open your SageMaker space in your IDE.

Note: Sessions initiated through this link last up to 12 hours and do not auto-reconnect if interrupted. You will need to create a new remote connection using the link in Amazon SageMaker Unified Studio.

Method 2: AWS Toolkit in Your IDE (Recommended for repeated use)

This method is available for VS Code, Kiro, and Cursor.

⚠️ Important: This method requires IAM Identity Center (SSO) authentication to fully function. With IAM-only credentials, the SageMaker Unified Studio section appears in the AWS Toolkit panel and shows a connection status, but project selection fails with "Failed to fetch IAM principal information." For IAM-based domains without Identity Center, use Method 1 (Deep Link) instead.

1. Open your IDE and navigate to the AWS Toolkit panel.
2. Connect to AWS via Identity Center (SSO).
3. Under the SageMaker Unified Studio section, choose Sign in to get started.
4. Provide your domain URL (format: https://<domain-id>.sagemaker.<region>.on.aws).
5. Complete the browser-based authentication flow.
6. Select your project from the list.
7. Under Compute Spaces, find your space and choose the Connect icon.

Note: If the space is not using a supported instance size, you will be asked to change the instance. Stop and restart the space in the Toolkit to enable remote access if not already connected.

Method 3: SSH Terminal (For SageMaker AI classic domains only)

⚠️ Important: This method is NOT supported for SageMaker Unified Studio domains. Attempting StartSession from the CLI for a Unified Studio domain returns: "StartSession for SageMaker Unified Studio Domain is supported only from Unified Studio clients - AWS Toolkit and SageMaker Unified Studio Web IDEs." For Unified Studio, use Method 1 (Deep Link) or Method 2 (AWS Toolkit with Identity Center).

Per AWS documentation, this method is available for SageMaker AI (classic Studio) domains. It allows you to connect via SSH directly from the terminal, and also enables SCP file transfers.

macOS/Linux Setup:

1. Create a shell script (e.g., /home/user/sagemaker_connect.sh):

#!/bin/bash
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
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"

2. Make the script executable:

chmod +x /home/user/sagemaker_connect.sh

3. Configure ~/.ssh/config:

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

To use a named AWS credential profile:

  ProxyCommand '/home/user/sagemaker_connect.sh' '%h' YOUR_CREDENTIAL_PROFILE_NAME

4. Connect:

ssh my-sagemaker-space
# Or transfer files:
scp file.txt my-sagemaker-space:/tmp/

Windows Setup:

1. Create a PowerShell script (e.g., C:\Users\user-name\sagemaker_connect.ps1):

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

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

$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 AWS CLI command
$awsCommand = @("sagemaker", "start-session", "--resource-identifier", $SpaceArn, "--region", $AwsRegion)

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

try {
    Write-Host "Starting SageMaker session..." -ForegroundColor Green
    $startSessionOutput = & aws @awsCommand

    try {
        $sessionData = $startSessionOutput | ConvertFrom-Json
    } catch {
        Write-Error "Failed to parse JSON response: $_"
        exit 1
    }

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

    if (-not $sessionId -or -not $streamUrl -or -not $token) {
        Write-Error "Error: Failed to extract session information from sagemaker start session response."
        exit 1
    }

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

    $sessionJson = @{
        streamUrl = $streamUrl
        tokenValue = $token
        sessionId = $sessionId
    } | ConvertTo-Json -Compress

    $escapedJson = $sessionJson -replace '"', '\"'

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

} catch {
    Write-Error "Failed to start session: $_"
    exit 1
}

2. Configure C:\Users\user-name\.ssh\config:

Host my-sagemaker-space
  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

Troubleshooting

Issue 1: StartSession Permission Denied

Symptoms: Connection fails with AccessDeniedException when calling sagemaker:StartSession.

Resolution:

• Verify the IAM policy attached to your user/role includes sagemaker:StartSession permission.
• Ensure the resource ARN in the policy matches your space ARN exactly (region, account ID, domain ID, space name).
• For Deep Link (Method 1): The policy must be attached to the space execution role, not your IAM user.
• For Toolkit/SSH (Methods 2 & 3): The policy must be attached to your IAM user or role.
• For Identity Center users: Verify the managed policy has been updated, or add the custom policy from Step 1.
• Check for any SCPs at the organization level that might deny the action.

Issue 2: Space Not Visible or "Failed to fetch IAM principal information" in AWS Toolkit

Symptoms: The SageMaker Unified Studio section appears in the AWS Toolkit, but clicking "Select a project" fails with "Failed to fetch IAM principal information. Try again." Or the Spaces list is empty.

Resolution:

• The SageMaker Unified Studio section in AWS Toolkit requires Identity Center (SSO) authentication to browse projects and spaces. With IAM-only credentials, the section appears but project selection fails.
• If you are using an IAM-based domain, use Method 1 (Deep Link) from the SageMaker Unified Studio web UI instead.
• If using Identity Center: verify you're signed in to the correct AWS region and have selected the correct domain.
• Ensure the space is in Running state.
• Confirm you have sagemaker:ListSpaces and sagemaker:DescribeSpace permissions.

Issue 3: Connection Timeout

Symptoms: Your IDE hangs or times out when establishing the remote connection.

Resolution:

• Verify AWS CLI is installed and accessible from your IDE's environment (aws --version in the integrated terminal).
• Verify network access to Session Manager endpoints (ssm.<region>.amazonaws.com, ssmmessages.<region>.amazonaws.com).
• Ensure the Session Manager plugin is installed and up to date: session-manager-plugin --version.
• If behind a corporate proxy/VPN, ensure SSM endpoints are not blocked.
• For VpcOnly Spaces: Verify NAT Gateway is configured or VPC endpoints exist for SSM services.
• Check that the instance type has at least 8 GB memory (see unsupported instance list above).
• Try fully quitting your IDE (Cmd+Q on macOS) and reopening to pick up PATH changes.

Issue 4: Remote SSH Extension Errors

Symptoms: IDE shows Remote-SSH errors like "Could not establish connection" or "Resolver error."

Resolution:

• Update AWS Toolkit extension to v3.97 or later (v3.100 for Cursor).
• Check IDE version meets minimum requirements (see Prerequisites table).
• On Linux, ensure you're using the official Microsoft VS Code distribution (not VSCodium or similar).
• For Kiro: Ensure v0.8.0 or later.

Issue 5: Session Disconnects After Some Time

Symptoms: Remote connection drops unexpectedly; cannot reconnect automatically.

Resolution:

• Sessions can last up to 12 hours. After expiry, you must establish a new connection.
• Sessions do not auto-reconnect if interrupted (network change, laptop sleep, etc.).
• Re-establish the connection using the same method (Deep Link or Toolkit). For SageMaker AI classic domains, Method 3 (SSH) is also available.
• For frequent disconnects, check your network stability to SSM endpoints.
• Note: When using IAM Identity Center, remote IDE connections may persist for up to 12 hours even after you log out of your IdC session. Review session duration settings on shared workstations.

Issue 6: Extensions Not Working in Remote Session

Symptoms: Some IDE extensions fail to activate or behave incorrectly after connecting remotely.

Resolution:

• Not all extensions support remote development. Extensions requiring local GUI components or architecture-specific binaries may not work.
• Check the extension documentation for remote development compatibility.
• Try installing the extension on the remote host (your IDE will prompt you for this).
• Some extensions need to be explicitly configured to run on the remote side.

Issue 7: Trusted Identity Propagation Incompatibility

Symptoms: Connection fails with errors related to TIP or trusted identity propagation.

Resolution:

• Remote Space connections are NOT supported for TIP-enabled project profiles.
• Set enableTrustedIdentityPropagationPermissions to false to use remote connections.
• Contact your administrator to adjust the project profile configuration.

Issue 8: VS Code Server Cannot Download on Isolated VPC

Symptoms: Connection starts but VS Code remote server fails to install on the Space.

Resolution:

• For Spaces in isolated VPCs (no internet), VS Code needs access to Microsoft's server endpoints to install the remote server.
• Configure VPC endpoints or proxy that allows access to update.code.visualstudio.com and *.vo.msecnd.net.
• Alternatively, manually install VS Code Server using VSIX files.
• Consider switching to VPC with NAT Gateway configuration.

Issue 9: Method 3 SSH Script Fails

Symptoms: SSH connection using the proxy command script fails or hangs.

Resolution:

• Ensure the script is executable: chmod +x sagemaker_connect.sh
• Verify the Space ARN format in your SSH config is correct: arn:aws:sagemaker:<region>:<account-id>:space/<domain-id>/<space-name>
• Confirm session-manager-plugin is installed and on your PATH.
• Check that local AWS credentials have sagemaker:StartSession permission on the specific space ARN.
• If using a named profile, verify the ProxyCommand includes the profile name as the second argument.
• On Windows, ensure PowerShell execution policy allows script execution (-ExecutionPolicy RemoteSigned).

Issue 10: SSH Terminal Returns "StartSession for SageMaker Unified Studio Domain is supported only from Unified Studio clients"

Symptoms: SSH connection fails with ValidationException: "StartSession for SageMaker Unified Studio Domain is supported only from Unified Studio clients - AWS Toolkit and SageMaker Unified Studio Web IDEs. Retry your request from a supported client."

Resolution:

• Method 3 (SSH terminal) is not supported for SageMaker Unified Studio domains. This is a platform limitation, not a configuration issue.
• For Unified Studio domains, use Method 1 (Deep Link) or Method 2 (AWS Toolkit with Identity Center).
• Method 3 is only available for SageMaker AI (classic Studio) domains.

Best Practices

1. Use Method 1 (Deep Link) for SageMaker Unified Studio — it works with both IAM and Identity Center-based domains and is the most reliable method.
2. Use the AWS Toolkit method (Method 2) for repeated use — requires Identity Center authentication. Provides the most seamless reconnection experience across VS Code, Kiro, and Cursor.
3. Use Method 3 (SSH) only for SageMaker AI classic domains — enables SCP file transfers and integration with other SSH-based tools, but is not supported for Unified Studio domains.
4. Choose appropriate instance sizes — at least 8 GB RAM. For ML workloads with GPUs, select GPU instances.
5. Keep extensions minimal on remote sessions — only install what you need to reduce resource usage.
6. Save work frequently — sessions don't auto-reconnect, so avoid losing unsaved changes.
7. Use SageMaker Distribution v2.8 or later for full compatibility with remote access features.
8. Stop your Space when not in use — to avoid unnecessary compute charges.
9. Scope IAM permissions — For production, use specific space ARNs or tag-based access control rather than wildcards.

Related Information

• Connect your Remote IDE to SageMaker spaces with remote access
• Set up remote access (Admin Guide)
• Set up Remote IDE (User Guide)
• Prerequisites for remote access
• Link to VS Code from Amazon SageMaker Unified Studio
• Configuring Amazon SageMaker Unified Studio for Remote Access
• Accelerate your data and AI workflows by connecting to Amazon SageMaker Unified Studio from Visual Studio Code (AWS Blog)
• Advanced access control for remote access
• AWS Toolkit for Visual Studio Code
• Install the Session Manager plugin
• VS Code Remote Development FAQ