Source GitHub

cdk-vscode-server

Running your dev IDE vscode on AWS for development and workshop purposes.

EXPERIMENTAL
This is an early version of the package. The API will change while I we implement new features. Therefore make sure you use an exact version in your package.json before it reaches 1.0.0.

Features
Usage
Solution Design
Inspiration

Features

⚡ Quick Setup: Spin up and configure your vscode server in under 10 minutes in your AWS account
📏 Best Practice Setup: Set up with projen and a single configuration file to keep your changes centralized.
🤹‍♂️ Pre-installed packages: Besides the vscode server, other tools and software packages such as git, docker, awscli nodejs and python are pre-installed on the EC2 instance.
🌐 Custom Domain Support: Use your own domain name with automatic ACM certificate creation and Route53 DNS configuration, or bring your existing certificate.
💰 Auto-Stop: Automatically stop EC2 instances after inactivity with Elastic IP retention - save up to 75% on costs for development environments.
🔧 Custom Install Steps: Extend the standard installation with your own shell commands to install workshop-specific tools, configure environments, or run setup scripts.
🏗️ Extensibility: Pass in properties to the construct, which start with additional*. They allow you to extend the configuration to your needs. There are more to come...

Usage

Actually we supported 2 modes:

Standard

The following steps get you started:

Create a new awscdk-app via

npx projen new awscdk-app-ts --package-manager=npm

Add @mavogel/cdk-vscode-server as a dependency to your project in the .projenrc.ts file
Run npx projen to install it
Add the following to the src/main.ts file:

import { App, Stack, StackProps } from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as iam from 'aws-cdk-lib/aws-iam';
import { Construct } from 'constructs';
import {
  LinuxArchitectureType,
  LinuxFlavorType,
  VSCodeServer
} from '@mavogel/cdk-vscode-server';

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps = {}) {
    super(scope, id, props);

    new VSCodeServer(this, 'vscode', {
      // for example (or simply use the defaults by not setting the properties)
      instanceVolumeSize: 8,
      instanceClass: ec2.InstanceClass.M7G,
      instanceSize: ec2.InstanceSize.LARGE,
      instanceOperatingSystem: LinuxFlavorType.UBUNTU_24, // or UBUNTU_26, AMAZON_LINUX_2023
      instanceCpuArchitecture: LinuxArchitectureType.ARM,

      // 👇🏽 or if you want to give the InstanceRole more permissions
      additionalInstanceRolePolicies: [
        new iam.PolicyStatement({
          effect: iam.Effect.ALLOW,
          actions: [
            'codebuild:*',
          ],
          resources: [
            `arn:aws:codebuild:*:${Stack.of(this).account}:*/*`,
          ],
        }),
      ]

      // and more... 💡
    });
  }
}

const env = {
  account: '123456789912',
  region: 'eu-central-1',
};

const app = new App();
new MyStack(app, 'vscode-server', { env });
app.synth();

and deploy it

npx projen build
npx projen deploy

with the output

✨  Deployment time: 509.87s

Outputs:
dev.vscodedomainName6729AA39 = https://d1foo65bar4baz.cloudfront.net/?folder=/Workshop
dev.vscodepassword64FBCA12 = foobarbaz

See the examples folder for more inspiration.

Supported Operating Systems

Set the operating system with instanceOperatingSystem and the CPU architecture with instanceCpuArchitecture (ARM or AMD64). Only Ubuntu LTS releases are supported:

`LinuxFlavorType`	OS	Notes
`UBUNTU_24` (default)	Ubuntu 24.04 LTS (noble)	Installs .NET SDK 8.0
`UBUNTU_26`	Ubuntu 26.04 LTS (resolute)	Installs .NET SDK 10.0, since 8.0 is not in the Ubuntu 26 archive
`AMAZON_LINUX_2023`	Amazon Linux 2023	Installs .NET SDK 8.0

Upgrading: UBUNTU_22 and UBUNTU_25 were removed; only the two current Ubuntu LTS releases (24.04 and 26.04) are supported, and 25.04 was not an LTS release. If your stack uses either removed value, switch to UBUNTU_24 or UBUNTU_26. Changing the operating system replaces the EC2 instance.

Log Retention

Every log group the construct creates expires its logs after 5 days and is deleted together with the stack. That covers the Lambda functions, the custom resource providers and the install output (/aws/ssm/<document>). They are deleted after all other resources of the stack, because Lambda delivers its last logs a few seconds late and would recreate an already deleted group without retention. Change both with:

import { RemovalPolicy } from 'aws-cdk-lib';
import { RetentionDays } from 'aws-cdk-lib/aws-logs';

new VSCodeServer(this, 'vscode', {
  logRetention: RetentionDays.ONE_MONTH, // default: FIVE_DAYS, INFINITE never expires the logs
  logRemovalPolicy: RemovalPolicy.RETAIN, // default: DESTROY, RETAIN keeps the logs after the stack is deleted
});

Upgrading: the Lambda functions now log to log groups of the stack. The groups they used before (/aws/lambda/<function name>) are not touched and keep their old retention; delete them if you do not need the logs. If you have several VSCodeServer in one stack, the setting of the first one applies to the shared log group of the VPC default security group provider.

Pre-populate with Git Repository

Clone a git repository into the VS Code Server's home folder during instance setup - perfect for workshops or development environments with starter code:

new VSCodeServer(this, 'vscode', {
  // Clone a git repository into the home folder
  repoUrl: 'https://github.com/aws-samples/my-workshop-repo.git',

  // Optional: customize the home folder path (default: /Workshop)
  homeFolder: '/MyWorkshop',

  // Optional: specify VS Code user (default: vscode-user)
  vscodeUser: 'workshop-user',
});

What happens:

During instance setup, the specified git repository is cloned into the user's home folder
VS Code Server opens with the repository already loaded and ready to use
Participants can start coding immediately without manual git clone steps

Use cases:

Workshop environments with pre-configured starter code
Development environments with boilerplate projects
Training sessions with example applications
Code review sessions with pre-loaded repositories

Repository requirements:

Must be publicly accessible (no authentication required)
HTTPS URLs only (SSH git URLs are not supported)
Repository will be cloned using git clone during instance initialization

For complete examples, see examples/.

Custom Domain Configuration

You can configure your VS Code Server with a custom domain name instead of using the default CloudFront domain. The construct supports three different configuration options:

Option 1: Auto-create Certificate with DNS Validation

new VSCodeServer(this, 'vscode', {
  domainName: 'vscode.example.com',
  hostedZoneId: 'Z123EXAMPLE456',  // optional - will auto-discover if not provided
  autoCreateCertificate: true,
});

This will:

Create an ACM certificate in us-east-1 (required for CloudFront)
Validate the certificate using DNS validation
Create a Route53 A record pointing to the CloudFront distribution
Configure the CloudFront distribution with the custom domain

Option 2: Use Existing Certificate

new VSCodeServer(this, 'vscode', {
  domainName: 'vscode.example.com',
  hostedZoneId: 'Z123EXAMPLE456',
  certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012',
});

Requirements:

Certificate must be in us-east-1 region
Certificate must be validated and ready to use
Certificate must include the domain name

Option 3: Default (No Custom Domain)

new VSCodeServer(this, 'vscode', {
  // No domain configuration - uses CloudFront default domain
});

For complete examples, see examples/custom-domain/main.ts.

Then open the domain name in your favorite browser and you'd see the following login screen:
After entering the password, you are logged into VSCode and can start coding 🎉

vscode-server-ui

Auto-Stop Configuration

Save up to 75% on costs by automatically stopping EC2 instances when idle:

new VSCodeServer(this, 'vscode', {
  enableAutoStop: true,              // Enable auto-stop feature
  idleTimeoutMinutes: 30,            // Stop after 30 minutes of no activity (default)
  idleCheckIntervalMinutes: 5,       // Check for idle activity every 5 minutes (default)
});

How it works:

Idle Detection: Monitors CloudFront request metrics at configured intervals (default: every 5 minutes)
Auto-Stop: Stops the EC2 instance after the configured idle timeout when no requests are detected
Static IP: Allocates an Elastic IP to maintain a consistent public IP address across stop/start cycles
Manual Resume: Users can manually start the instance via AWS Console or CLI when needed

Cost Savings Example:

Without auto-stop: m7g.xlarge running 24/7 = ~$120/month
With auto-stop (8 hours/day, 5 days/week): ~$30/month
Savings: ~$90/month (75% reduction)

Additional costs:

Elastic IP (allocated): ~$3.65/month
Lambda function (IdleMonitor): ~$0.10/month
EventBridge rule: Negligible
Net savings: ~$86/month per instance

Architecture Components:

Elastic IP for consistent public addressing
EventBridge rule triggering idle monitoring at configured intervals
IdleMonitor Lambda function checking CloudWatch metrics for request activity
IdleMonitorEnabler custom resource ensuring monitoring only starts after installation completes
CloudWatch metrics from CloudFront distribution

Integration Testing:

The stop-on-idle functionality includes comprehensive integration tests (integ-tests/integ.stop-on-idle.ts) that verify the complete workflow:

Phase 1 - Verify Auto-Stop: Waits for the instance to automatically stop after the configured idle timeout
Phase 2 - Disable IdleMonitor: Disables the EventBridge rule to prevent the instance from being stopped again during testing
Phase 3 - Start Instance: Starts the stopped instance and waits for it to reach the running state
Phase 4 - Verify Login: Confirms that VS Code Server is accessible through CloudFront after the instance has been restarted

This 4-phase test ensures that:

Idle detection works correctly based on CloudWatch metrics
Instance stops automatically when no activity is detected
Instance can be successfully restarted after being stopped
VS Code Server remains accessible after stop/start cycles
Elastic IP maintains connectivity across state changes

Run integration tests with:

npm run integ-test

Custom Installation Steps

Extend the standard VS Code Server installation with your own custom shell commands - perfect for installing workshop-specific tools, configuring development environments, or running setup scripts:

new VSCodeServer(this, 'vscode', {
  // Add custom installation steps that run after standard setup
  customInstallSteps: [
    {
      name: 'InstallWorkshopTools',
      commands: [
        '#!/bin/bash',
        'echo "Installing workshop-specific tools"',

        // Install additional software
        'curl -fsSL https://get.docker.com | sh',
        'usermod -aG docker ubuntu',

        // Configure environment
        'echo "export WORKSHOP_ENV=production" >> /home/ubuntu/.bashrc',
      ],
    },
    {
      name: 'CloneStarterCode',
      commands: [
        '#!/bin/bash',
        'cd /home/ubuntu',
        'git clone https://github.com/my-org/workshop-starter.git',
        'chown -R ubuntu:ubuntu workshop-starter',
      ],
    },
  ],
});

Key Features:

Execute After Standard Setup: Custom steps run after VS Code Server installation completes
Multiple Steps: Add as many installation steps as needed, executed in order
Full Shell Access: Run any shell commands with root privileges
Workshop-Friendly: Pre-install tools, configure environments, or download starter code

Common Use Cases:

Install additional development tools (Docker, kubectl, terraform)
Configure workshop-specific environments and credentials
Clone starter code repositories with specific permissions
Set up databases or services required for training
Download and prepare datasets or assets
Configure IDE extensions or settings

Supported Operating Systems:

Ubuntu 24/26
Amazon Linux 2023

Requirements:

Commands execute with root privileges during instance initialization
Use absolute paths or ensure proper working directory context
Consider idempotency if instance might be restarted
Commands run synchronously in the order specified

For complete examples, see examples/custom-install-steps/main.ts.

Solution Design

... if you're curious about click here for the details

vscode-server-solution-design

Inspiration

This project was created based on the following inspiration

vscode-on-ec2-for-prototyping: as baseline, which unfortunately was outdated
aws-terraform-dev-container: as baseline for terraform, but unfortunately also outdated
java-on-aws-workshop-ide-only.yaml: an already synthesized cloudformation stack, which used mostly python as the custom resources
fleet-workshop-team-stack-self.json: also an already synthesized cloudformation stack, which did much more as I currently implemented here.
eks-workshop-vscode-cfn.yaml: another great baseline

🚀 Unlock the Full Potential of Your AWS Cloud Infrastructure

Hi, I’m Manuel, an AWS expert passionate about empowering businesses with scalable, resilient, and cost-optimized cloud solutions. With MV Consulting, I specialize in crafting tailored AWS architectures and DevOps-driven workflows that not only meet your current needs but grow with you.

🌟 Why Work With Me?

✔️ Tailored AWS Solutions: Every business is unique, so I design custom solutions that fit your goals and challenges. ✔️ Well-Architected Designs: From scalability to security, my solutions align with AWS Well-Architected Framework. ✔️ Cloud-Native Focus: I specialize in modern, cloud-native systems that embrace the full potential of AWS. ✔️ Business-Driven Tech: Technology should serve your business, not the other way around.

🛠 What I Bring to the Table

🔑 12x AWS Certifications I’m AWS Certified Solutions Architect and DevOps – Professional and hold numerous additional certifications, so you can trust I’ll bring industry best practices to your projects. Feel free to explose by badges

⚙️ Infrastructure as Code (IaC) With deep expertise in AWS CDK and Terraform, I ensure your infrastructure is automated, maintainable, and scalable.

📦 DevOps Expertise From CI/CD pipelines with GitHub Actions and GitLab CI to container orchestration Kubernetes and others, I deliver workflows that are smooth and efficient.

🌐 Hands-On Experience With over 7 years of AWS experience and a decade in the tech world, I’ve delivered solutions for companies large and small. My open-source contributions showcase my commitment to transparency and innovation. Feel free to explore my GitHub profile

💼 Let’s Build Something Great Together

I know that choosing the right partner is critical to your success. When you work with me, you’re not just contracting an engineer – you’re gaining a trusted advisor and hands-on expert who cares about your business as much as you do.

✔️ Direct Collaboration: No middlemen or red tape – you work with me directly. ✔️ Transparent Process: Expect open communication, clear timelines, and visible results. ✔️ Real Value: My solutions focus on delivering measurable impact for your business.

🙌 Acknowledgements

Big shoutout to the amazing team behind Projen! Their groundbreaking work simplifies cloud infrastructure projects and inspires us every day. 💡

Author

Manuel Vogel

Metadata

Release files for cdk-vscode-server 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cdk-vscode-server 0.1.2
File	Size	Uploaded
cdk_vscode_server-0.1.2.tar.gz	6.8 MB	Oct 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cdk-vscode-server 0.1.2
File	Interpreter	ABI	Platform	Reset
cdk_vscode_server-0.1.2-py3-none-any.whl 6.8 MB Oct 12, 2026	Python 3	none	any	Details

Total release size: 13.6 MB

Release files / cdk_vscode_server-0.1.2.tar.gz

Download URL	cdk_vscode_server-0.1.2.tar.gz
Size	6.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`a31a3da4c85679ee027497ee13899e467b9527a2833262be38accbbb25ba79f1`
BLAKE2b-256 checksum How to use checksums	`b78968f6a22b86463ae1d57b4a69f4e9d0f945640c18f1bbf22ae3d3f50185ea`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.14.8`

Release files / cdk_vscode_server-0.1.2-py3-none-any.whl

Download URL	cdk_vscode_server-0.1.2-py3-none-any.whl
Size	6.8 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`7da332c5b572104f11fb1f63e32ae83b368254704576c1eb2079ea3fba817547`
BLAKE2b-256 checksum How to use checksums	`aedea0b71b4a6d115b9b5ecf78aa02cf632118d8725a3405c2e6250b9128b05c`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.14.8`