Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).
# Write and modify code with Dev Environments in CodeCatalyst
Dev Environments are cloud-based development environments. In Amazon CodeCatalyst, you use Dev Environments to work on the code stored in the source repositories of your project. When creating a Dev Environments, you have several options:
+ Create a project-specific Dev Environment in CodeCatalyst to work on code with a supported integrated development environment (IDE).
+ Create an empty Dev Environment, clone code into it from a source repository, and work on that code with a supported IDE.
+ Create a Dev Environment in an IDE and clone a source repository into the Dev Environment
A *devfile* is an open standard YAML file that standardizes your Dev Environments. In other words, this file codifies the required development tools for your Dev Environment. As a result, you can quickly set up a Dev Environment, switch between projects, and replicate the Dev Environment configuration across team members. Dev Environments minimize the time that you spend creating and maintaining a local development environment, because they use a devfile that configures all of the tools you need to code, test, and debug for a given project.
**Important**
Dev Environments can run scripts via devfiles that have access to your CodeCatalyst credentials. Please inspect the repository before opening untrusted resources.
The project tools and application libraries included in your Dev Environment are defined by the devfile in the source repository of your project. If you don't have a devfile in your source repository, CodeCatalyst automatically applies a default devfile. This default devfile includes tools for the most frequently used programming languages and frameworks. If your project was created using a blueprint, a devfile is automatically created by CodeCatalyst. For more information about the devfile, see [https://devfile.io](https://devfile.io).
After you've created a Dev Environment, only you can access it. In your Dev Environment, you can view and work on your source repository's code in a supported IDE.
By default, a Dev Environment is configured to have a 2-core processor, 4 GB of RAM, and 16 GB of persistent storage. If you have Space administrator permissions, you can change the billing tier for your space to use different Dev Environment configuration options and manage compute and storage limits.
**Topics**
+ [Creating a Dev Environment](devenvironment-create.md)
+ [Stopping a Dev Environment](devenvironment-stop.md)
+ [Resuming a Dev Environment](devenvironment-resume.md)
+ [Editing a Dev Environment](devenvironment-edit.md)
+ [Deleting a Dev Environment](devenvironment-delete.md)
+ [Connecting to a Dev Environment using SSH](devenvironment-connect-ssh.md)
+ [Configuring a devfile for a Dev Environment](devenvironment-devfile.md)
+ [Associating a VPC connection to a Dev Environment](devenvironment-using-vpc.md)
+ [Quotas for Dev Environments in CodeCatalyst](devenvironment-limits.md)
# Creating a Dev Environment
You can create a Dev Environment in multiple ways:
+ Create a Dev Environment in CodeCatalyst with a CodeCatalyst source repository or a [linked source repository](source-repositories-link.md) from the **Overview**, **Dev Environments** or **Source repositories** pages
+ Create an empty Dev Environment in CodeCatalyst that is not connected to a source repository from the Dev Environments page
+ Create a Dev Environment in your IDE of choice and clone any source repository into the Dev Environment
**Important**
Dev Environments aren't available for users in spaces where Active Directory is used as the identity provider. For more information, see [I can't create a Dev Environment when I'm signed into CodeCatalyst using a single sign-on account](devenvironments-troubleshooting.md#troubleshoot-create-dev-env-idprovider).
You can create one Dev Environment per branch of a repository. A project can have multiple repositories. The Dev Environments you create can only be managed with your CodeCatalyst account, but you can open the Dev Environment and work in it with any of the supported IDEs. You must have the AWS Toolkit installed to use Dev Environments in your IDE. For more information, see [Supported integrated development environments for Dev Environments](#devenvironment-supported-ide). By default, Dev Environments are created with a 2-core processor, 4 GB of RAM, and 16 GB of persistent storage.
**Note**
If you created a Dev Environment that is associated with a source repository, the **Resource** column always shows the branch you specified when creating this Dev Environment. This applies even if you create another branch, switch to another branch within the Dev Environment, or clone an additional repository. If you created an empty Dev Environment, the **Resource** column will be blank.
## Supported integrated development environments for Dev Environments
You can use Dev Environments with the following supported integrated development environments (IDEs):
+ [AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/welcome.html)
+ [JetBrains IDEs](https://www.jetbrains.com/help)
+ [IntelliJ IDEA Ultimate](https://www.jetbrains.com/help/idea/getting-started.html)
+ [GoLand](https://www.jetbrains.com/help/go/getting-started.html)
+ [PyCharm Professional](https://www.jetbrains.com/help/pycharm/getting-started.html)
+ [Visual Studio Code](https://code.visualstudio.com/docs)
## Creating a Dev Environment in CodeCatalyst
To get started working with Dev Environment in CodeCatalyst, authenticate and sign in with either your [AWS Builder ID](id-how-to-sign-in.md) or [SSO](sign-in-sso.md).
**To create a Dev Environment from a branch**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to create a Dev Environment.
1. In the navigation pane, do one of the following:
+ Choose **Overview**, and then navigate to the **My Dev Environments** section.
+ Choose **Code**, and then choose **Dev Environments**.
+ Choose **Code**, choose **Source repositories**, and choose the repository for which you want to create a Dev Environment.
1. Choose **Create Dev Environment**.
1. Choose a supported IDE from the drop-down menu. See [Supported integrated development environments for Dev Environments](#devenvironment-supported-ide) for more information.
1. Choose **Clone a repository**.
1. Do one of the following:
1. Choose the repository to clone, choose **Work in existing branch**, and then choose a branch from the **Existing branch** drop-down menu.
**Note**
If you choose a third-party repository, you must work in an existing branch.
1. Choose the repository to clone, choose **Work in new branch**, enter a branch name into the **Branch name** field, and choose a branch off of which to create the new branch from the **Create branch from** drop-down menu.
**Note**
If you create a Dev Environment from the **Source repositories** page or from a specific source repository, you do not need to choose a repository. The Dev Environment will be created from the source repository you chose from the **Source repositories** page.
1. (Optional) In **Alias - optional**, enter an alias for the Dev Environment.
1. (Optional) Choose the **Dev Environment configuration** edit button to edit the Dev Environment's compute, storage, or timeout configuration.
1. (Optional) In **Amazon Virtual Private Cloud (Amazon VPC) - optional**, select a VPC connection that you'd like to associate with your Dev Environment from the drop-down menu.
If a default VPC is set for your space, your Dev Environments will run connected to that VPC. You can override this by associating a different VPC connection. Also, note that VPC-connected Dev Environments don’t support AWS Toolkit.
If the VPC connection that you want to use is not listed, it might be because it includes an AWS account connection that's not allowed in your project. For more information, see [ Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.
**Note**
When you create a Dev Environment with a VPC connection, a new network interface is created inside the VPC. CodeCatalyst interacts with this interface using the associated VPC role. Also, make sure that your IPv4 CIDR block is **not** configured to the `172.16.0.0/12` IP address range.
1. Choose **Create**. While your Dev Environment is being created, the Dev Environment status column will display **Starting**, and the status column will display **Running** once the Dev Environment has been created.
**To create an empty Dev Environment**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to create a Dev Environment.
1. In the navigation pane, do one of the following:
+ Choose **Overview**, and then navigate to the **My Dev Environments** section.
+ Choose **Code**, and then choose **Dev Environments**.
1. Choose **Create Dev Environment**.
1. Choose a supported IDE from the drop-down menu. See [Supported integrated development environments for Dev Environments](#devenvironment-supported-ide) for more information.
1. Choose **Create an empty Dev Environment**.
1. (Optional) In **Alias - optional**, enter an alias for the Dev Environment.
1. (Optional) Choose the **Dev Environment configuration** edit button to edit the Dev Environment's compute, storage, or timeout configuration.
1. (Optional) In **Amazon Virtual Private Cloud (Amazon VPC) - optional**, select a VPC connection that you'd like to associate with your Dev Environment from the drop-down menu.
If a default VPC is set for your space, your Dev Environments will run connected to that VPC. You can override this by associating a different VPC connection. Also, note that VPC-connected Dev Environments don’t support AWS Toolkit.
If the VPC connection that you want to use is not listed, it might be because it includes an AWS account connection that's not allowed in your project. For more information, see [ Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.
**Note**
When you create a Dev Environment with a VPC connection, a new network interface is created inside the VPC. CodeCatalyst interacts with this interface using the associated VPC role. Also, make sure that your IPv4 CIDR block is **not** configured to the `172.16.0.0/12` IP address range.
1. Choose **Create**. While your Dev Environment is being created, the Dev Environment status column will display **Starting**, and the status column will display **Running** once the Dev Environment has been created.
**Note**
Creating and opening a Dev Environment for the first time might take one to two minutes.
**Note**
After the Dev Environment opens in the IDE, you might need to change the directory to the source repository before you commit and push changes to your code.
## Creating a Dev Environment in an IDE
You can use Dev Environments to quickly work on the code stored in the source repositories of your project. Dev Environments increase your development velocity because you can start coding immediately in a project-specific, fully functioning cloud development environment with a supported integrated development environment (IDE).
For information about working with CodeCatalyst from an IDE, see the following documentation.
+ [Amazon CodeCatalyst for JetBrains IDEs](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/codecatalyst-service.html)
+ [Amazon CodeCatalyst for VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/codecatalyst-service.html)
+ [Amazon CodeCatalyst for AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/ide-toolkits-cloud9.html)
# Stopping a Dev Environment
The `/projects` directory of a Dev Environment stores the files that are pulled from the source repository and the devfile that is used to configure the Dev Environment. The `/home` directory, which is empty upon Dev Environment creation, stores the files you create while using your Dev Environment. Everything in the `/projects` and `/home` directories of a Dev Environment is stored persistently, so you can stop working in a Dev Environment if you need to switch to another Dev Environment, repository, or project.
**Warning**
A Dev Environment will not timeout if any instances, including web browsers, remote shells, and IDEs, remain connected. So, make sure to close all connected instances to avoid incurring additional costs.
A Dev Environment will automatically stop if it is idle for the amount of time that was selected in the **Timeout** fields during Dev Environment creation. You can stop the Dev Environment before it goes idle. If you chose **No timeout** when you created your Dev Environment, the Dev Environment will not stop automatically. Instead, it will run continuously.
**Warning**
If you stop a Dev Environment that's associated with a deleted VPC connection, it can't be resumed.
**To stop a Dev Environment from the Dev Environments page**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to stop a Dev Environment.
1. In the navigation pane, choose **Code**.
1. Choose **Dev Environments**.
1. Choose the radio button for the Dev Environment you want to stop.
1. From the **Actions** menu, choose **Stop**.
**Note**
Compute use is billed only while the Dev Environment is running, but storage use is billed for the entire time that the Dev Environment exists. Stop your Dev Environment when it is not in use to stop compute billing.
# Resuming a Dev Environment
The `/projects` directory of a Dev Environment stores the files that are pulled from the source repository and the devfile that is used to configure the Dev Environment. The `/home` directory, which is empty upon Dev Environment creation, stores the files you create while using your Dev Environment. Everything in the `/projects` and `/home` directories of a Dev Environment is stored persistently, so you can stop working in a Dev Environment if you need to switch to another Dev Environment, repository, or project and resume working in your Dev Environment at a later time.
A Dev Environment will automatically stop if it is idle for the amount of time that was selected in the **Timeout** fields during Dev Environment creation. You must close the AWS Cloud9 browser tab for the Dev Environment to be idle.
**Note**
The Dev Environment is still available and running even if you delete the branch with which you created the Dev Environment. If you want to resume working in a Dev Environment for which you deleted the branch, create a new branch and push your changes to it.
**To resume a Dev Environment from the overview page**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to resume a Dev Environment, and navigate to the **My Dev Environments** section.
1. Choose **Resume in (IDE)**.
+ For JetBrains IDEs, choose JetBrains Gateway-EAP when prompted to **Choose an application to open the JetBrains-gateway link**. Choose **Open Link** to confirm when prompted.
+ For the VS Code IDE, choose VS Code when prompted to **Choose an application to open the VS Code link**. Choose **Open Link** to confirm.
**To resume a Dev Environment from the source repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to resume a Dev Environment.
1. In the navigation pane, choose **Code**.
1. Choose **Source Repositories**.
1. Choose the source repository that contains the Dev Environment you want to resume.
1. Choose the branch name to view a drop-down menu of your branches, then choose your branch.
1. Choose **Resume Dev Environment**.
+ For JetBrains IDEs, choose **Open Link** to confirm when prompted to **Allow this site to open the JetBrains-gateway link with JetBrains Gateway?**.
+ For the VS Code IDE, choose **Open Link** to confirm when prompted to **Allow this site to open the VS Code link with Visual Studio Code?**.
**To resume a Dev Environment from the Dev Environments page**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to resume a Dev Environment.
1. In the navigation pane, choose **Code**.
1. Choose **Dev Environments**.
1. From the **IDE** column, choose **Resume in (IDE)** for the Dev Environment.
+ For JetBrains IDEs, choose **Open Link** to confirm when prompted to **Allow this site to open the JetBrains-gateway link with JetBrains Gateway?**.
+ For the VS Code IDE, choose **Open Link** to confirm when prompted to **Allow this site to open the VS Code link with Visual Studio Code?**.
**Note**
Resuming a Dev Environment may take a few minutes.
# Editing a Dev Environment
While your IDE is running, you can edit the Dev Environment. If you edit your compute or inactivity timeout, your Dev Environment will restart after you've saved your changes.
**To edit a Dev Environment**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to edit a Dev Environment.
1. In the navigation pane, choose **Code**.
1. Choose **Dev Environments**.
1. Choose the Dev Environment you want to edit.
1. Choose **Edit**.
1. Make the changes you want to the compute or inactivity timeout.
1. Choose **Save**.
# Deleting a Dev Environment
When you have finished working on the content that is stored in your Dev Environment, you can delete the Dev Environment. Create a new Dev Environment to work on new content. If you delete your Dev Environment, the persisted content will be permanently deleted. Before you delete your Dev Environment, make sure you commit and push your code changes to the Dev Environment's original source repository. After you have deleted your Dev Environment, compute and storage billing for the Dev Environment will stop.
After you delete your Dev Environment, it may take a few minutes for the storage quota to be updated. If you've reached the storage quota, you will be unable to create a new Dev Environment during this time.
**Important**
Deleting a Dev Environment cannot be undone. After you delete a Dev Environment, you are no longer able to recover it.
**To delete a Dev Environment**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to delete a Dev Environment.
1. In the navigation pane, choose **Code**.
1. Choose **Dev Environments**.
1. Choose the Dev Environment you want to delete.
1. Choose **Delete**.
1. Enter **delete** to confirm the Dev Environment deletion.
1. Choose **Delete**.
**Note**
Before deleting a VPC connection in your space, make sure to remove the Dev Environment associated to that VPC.
Even if you delete a Dev Environment, you might not delete the network interface in the VPC. Make sure to clean up your resources as needed. If an error occurs when you delete a VPC-connected Dev Environment, you must [detach](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#detach_eni) your stale connection, and [delete](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#delete_eni) it after confirming that it's not being used.
# Connecting to a Dev Environment using SSH
You can connect to your Dev Environment using SSH to perform actions without limitations, such as port forwarding, uploading and downloading files, and using other IDEs.
**Note**
If you want to continue using SSH for an extended time after closing the IDE tab or window, make sure to set a high timeout for your Dev Environment so that it doesn't stop due to inactivity in the IDE.
**Prerequisites**
+ You need one of the following operating systems:
+ Windows 10 or newer and OpenSSH enabled
+ macOS and Bash version 3 or higher
+ Linux with `yum`, `dpkg` or `rpm` package managers and Bash version 3 or higher
+ You also need AWS CLI version 2.9.4 or higher.
**To connect to a Dev Environment using SSH**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to connect to a Dev Environment using SSH.
1. In the navigation pane, choose **Code**.
1. Choose **Dev Environments**.
1. Choose a running Dev Environment you want to connect to using SSH.
1. Choose **Connect via SSH**, choose your desired operating system, and do the following:
+ If you haven't done so already, paste and execute the first command in your specified terminal. The command downloads a script and executes the following modifications in your local environment so that you can connect to your Dev Environment using SSH:
+ Installs the [Session Manager plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
+ Modifies your local AWS Config and adds a CodeCatalyst profile so that you're able to perform the SSO login. For more information, see [Setting up to use the AWS CLI with CodeCatalyst](set-up-cli.md).
+ Modifies your local SSH config and adds the required configuration for connecting to your Dev Environment using SSH.
+ Adds a script in the `~/.aws/codecatalyst-dev-env` directory that is used by the SSH client to connect to your Dev Environment. This script calls the [CodeCatalyst StartDevEnvironmentSession API](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_StartDevEnvironmentSession.html) and uses AWS Systems Manager Session Manager plugin to establish an AWS Systems Manager session with your Dev Environment which is used by the local SSH client to securely connect to the remote Dev Environment.
+ Sign-in to Amazon CodeCatalyst using AWS SSO using the second command. This command requests and retrieves credentials so that the script in the `~/.aws/codecatalyst-dev-env` directory can call [CodeCatalyst StartDevEnvironmentSession API](https://docs.aws.amazon.com/codecatalyst/latest/APIReference/API_StartDevEnvironmentSession.html). This command should be executed every time your credentials expire. When you execute the last command in the modal( ssh ) you will get an error if your credentials are expired or you haven’t performed the SSO login as instructed in this step.
+ Connect to your specified Dev Environment using SSH using the third command. This command has the following structure:
```
ssh codecatalyst-dev-env===
```
You can also use this command to perform other actions allowed by the SSH client, such as port forwarding or uploading and downloading files:
+ Port forwarding:
```
ssh -L :127.0.0.1: codecatalyst-dev-env===
```
+ Uploading a file to the home directory in your Dev Environment:
```
scp -O codecatalyst-dev-env===:
```
# Configuring a devfile for a Dev Environment
A *devfile* is an open standard that helps you to customize your development Dev Environments across your team. A devfile is a YAML file that codifies your required development tools. By configuring a devfile, you can pre-determine the project tools and application libraries you need and Amazon CodeCatalyst installs them to your Dev Environment for you. The devfile is specific to the repository for which it was created, and you can create a separate devfile for each repository. Your Dev Environment supports commands and events, and provides a default universal devfile image.
If you create a project using the empty blueprint, you can create a devfile manually. If you create a project using a different blueprint, CodeCatalyst creates a devfile automatically. The `/projects` directory of a Dev Environment stores the files that are pulled from the source repository and the devfile. The `/home` directory, which is empty when you first create a Dev Environment, stores the files you create while using your Dev Environment. Everything in the `/projects` and `/home` directories of a Dev Environment is stored persistently.
**Note**
The `/home` folder only changes if you change the name of the devfile or devfile component name. If you change the devfile or devfile component name, the contents of the `/home` directory are replaced and your previous `/home` directory data cannot be recovered.
If you create a Dev Environment with a source repository that does not contain a devfile in its root, or if you create a Dev Environment without a source repository, a default universal devfile is applied to the source repository automatically. The same default universal devfile image is used for all IDEs. CodeCatalyst currently supports devfile version 2.0.0. For more information about the devfile, see [Devfile schema - Version 2.0.0](https://devfile.io/docs/2.0.0/devfile-schema).
**Note**
You can only include public container images in your devfile.
Note that VPC-connected Dev Environments only support the following devfile images:
+ Universal image
+ Private Amazon ECR images, if the repository is in the same region as the VPC
**Topics**
+ [Editing a repository devfile for a Dev Environment](devenvironment-devfile-moving.md)
+ [Devfile features supported by CodeCatalyst](#devenvironment-devfile-support)
+ [Example of a devfile for a Dev Environment](#devenvironment-devfile-example)
+ [Troubleshooting a repository devfile using recovery mode](#devenvironment-devfile-recovery)
+ [Specifying universal devfile images for a Dev Environment](devenvironment-universal-image.md)
+ [Devfile commands](devenvironment-devfile-commands.md)
+ [Devfile events](devenvironment-devfile-events.md)
+ [Devfile components](devenvironment-devfile-components.md)
# Editing a repository devfile for a Dev Environment
Use the following procedure to edit a repository devfile for a Dev Environment.
## Editing a repository devfile for a Dev Environment in CodeCatalyst
**To edit the repository devfile**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project that contains the source repository for which you want to edit the devfile.
1. In the navigation pane, choose **Code**.
1. Choose **Source Repositories**.
1. Choose the source repository that contains the devfile that you want to edit.
1. From the list of files, choose the `devfile.yaml` file.
1. Choose **Edit**.
1. Edit the devfile.
1. Choose **Commit**, or create a pull request so a team member can review and approve the changes.
**Note**
If you edit your devfile, you have to restart the devfile for the changes to take effect. This can be done by running `/aws/mde/mde start --location devfile.yaml`. If there's a problem starting your devfile, it will enter recovery mode. However, if you edit a devfile associated to a VPC-connected Dev Environment, you have to restart the Dev Environment instead for the changes to take effect.
You can review which devfile is being used by running `/aws/mde/mde status`. The location field has the path of the devfile relative to the environment’s `/projects` folder.
```
{
"status": "STABLE",
"location": "devfile.yaml"
}
```
You can also move the default devfile in `/projects/devfile.yaml` to your source code repository. To update the location of the devfile, use following command: `/aws/mde/mde start --location repository-name/devfile.yaml`.
## Editing a repository devfile for a Dev Environment in an IDE
To change the configuration of a Dev Environment, you must edit the devfile. We recommend that you edit the devfile in a supported IDE and then update your Dev Environment, but you can also edit the devfile from the root of the source repository in CodeCatalyst. If you edit the devfile in a supported IDE, you must commit and push your changes to the source repository or create a pull request so a team member can review and approve the devfile edits.
+ [Editing the repository devfile for a Dev Environment in AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/devenvironment-cloud9.title.html#ide-toolkits-edit-devfile-cloud9)
+ [Editing the repository devfile for a Dev Environment in VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/codecatalyst-devenvironment.html#codecatalyst-devenvironment-devfile)
+ [Editing the repository devfile for a Dev Environment in JetBrains](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/codecatalyst-overview.html#codecatalyst-overview-default)
## Devfile features supported by CodeCatalyst
CodeCatalyst supports the following devfile features on version 2.0.0. For more information about the devfile, see [Devfile schema - Version 2.0.0](https://devfile.io/docs/2.0.0/devfile-schema).
| Feature | Type |
| --- | --- |
| `exec` | Command |
| `postStart` | Event |
| `container` | Component |
| `args` | Component Properties |
| `env` | Component Properties |
| `mountSources` | Component Properties |
| `volumeMounts` | Component Properties |
## Example of a devfile for a Dev Environment
The following is an example of a simple devfile.
```
schemaVersion: 2.0.0
metadata:
name: al2
components:
- name: test
container:
image: public.ecr.aws/amazonlinux/amazonlinux:2
mountSources: true
command: ['sleep', 'infinity']
- name: dockerstore
commands:
- id: setupscript
exec:
component: test
commandLine: "chmod +x script.sh"
workingDir: /projects/devfiles
- id: executescript
exec:
component: test
commandLine: "/projects/devfiles/script.sh"
- id: yumupdate
exec:
component: test
commandLine: "yum -y update --security"
events:
postStart:
- setupscript
- executescript
- yumupdate
```
Devfile startup, command, and event logs are captured and stored in `/aws/mde/logs`. To debug devfile behaviour, start up your Dev Environment using a working devfile and access the logs.
## Troubleshooting a repository devfile using recovery mode
If there's a problem starting your devfile, it will enter recovery mode so that you can still connect to your environment and fix your devfile. While in recovery mode, running `/aws/mde/mde status` won’t contain the location of your devfile.
```
{
"status": "STABLE"
}
```
You can check the error in the logs under `/aws/mde/logs`, fix the devfile, and try running `/aws/mde/mde start` again.
# Specifying universal devfile images for a Dev Environment
The default *universal image* includes the most commonly used programming languages and related tools that can be used for your IDE. If no image is specified, CodeCatalyst provides this image and contains tools that are maintained by CodeCatalyst. To remain notified of new image releases, see [Subscribing to universal image notifications with SNS](#devenvironment-universal-notifications).
Amazon CodeCatalyst actively supports the following devfile images:
| Image version | Image identifier |
| --- | --- |
| Universal image 4.0 | public.ecr.aws/aws-mde/universal-image:4.0 |
| Universal image 5.0 | public.ecr.aws/aws-mde/universal-image:5.0 |
**Note**
You can also use `public.ecr.aws/aws-mde/universal-image:latest` to get the latest image, which is currently `public.ecr.aws/aws-mde/universal-image:5.0`.
CodeCatalyst has deprecated the following images. You can still use these images, but they won't be cached on the build host and will result in increased Dev Environment start-up times.
| Image version | Image identifier | Deprecation date |
| --- | --- | --- |
| Universal image 1.0 | public.ecr.aws/aws-mde/universal-image:1.0 | August 16, 2024 |
| Universal image 2.0 | public.ecr.aws/aws-mde/universal-image:2.0 | August 16, 2024 |
| Universal image 3.0 | public.ecr.aws/aws-mde/universal-image:3.0 | July 30, 2025 |
**Note**
If you're using AWS Cloud9, auto-complete will not work for PHP, Ruby and CSS after upgrading to `universal-image:3.0`.
**Topics**
+ [Subscribing to universal image notifications with SNS](#devenvironment-universal-notifications)
+ [Universal image 4.0 runtime versions](#devenvironment-universal-runtimes-4.0)
+ [Universal image 5.0 runtime versions](#devenvironment-universal-runtimes-5.0)
## Subscribing to universal image notifications with SNS
CodeCatalyst provides a universal image notification service. You can use it to subscribe to an Amazon Simple Notification Service (SNS) topic that notifies you when CodeCatalyst universal image updates have been released. For more information about SNS topics, see [What is Amazon Simple Notification Service?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html).
Whenever new universal images are released, we send notifications to subscribers; this section describes how to subscribe to CodeCatalyst universal image updates.
**Sample message**
```
{
"Type": "Notification",
"MessageId": "123456789",
"TopicArn": "arn:aws:sns:us-east-1:1234657890:universal-image-updates",
"Subject": "New Universal Image Release",
"Message": {
"v1": {
"Message": "A new version of the Universal Image has been released. You are now able to launch new DevEnvironments using this image.",
"image ": {
"release_type": "MAJOR VERSION",
"image_name": "universal-image",
"image_version": "2.0",
"image_uri": "public.ecr.aws/amazonlinux/universal-image:2.0"
}
}
},
"Timestamp": "2021-09-03T19:05:57.882Z",
"UnsubscribeURL": "example url"
}
```
**To subscribe to CodeCatalyst universal image updates using the Amazon SNS console**
1. Open the Amazon SNS console to the [Dashboard](https://console.aws.amazon.com/sns/v2/home).
1. In the navigation bar, choose your AWS Region.
1. In the navigation pane, choose **Subscriptions**, and then choose **Create subscription**.
1. In **Topic ARN**, enter `arn:aws:sns:us-east-1:089793673375:universal-image-updates`.
1. In **Protocol**, choose **Email**.
1. In **Endpoint**, provide an email address. This email address will be used to receive notifications.
1. Choose **Create subscription**.
1. You will receive a confirmation email with the subject line "AWS Notification - Subscription Confirmation". Open the email and choose **Confirm subscription**.
**To unsubscribe from CodeCatalyst universal image updates using the Amazon SNS console**
1. Open the Amazon SNS console to the [Dashboard](https://console.aws.amazon.com/sns/v2/home).
1. In the navigation bar, choose your AWS Region.
1. In the navigation pane, choose **Subscriptions** and then select the subscription you want to unsubscribe from.
1. Choose **Actions**, and then choose **Delete subscriptions**.
1. Choose **Delete**.
## Universal image 4.0 runtime versions
The following table lists the available runtimes for `universal-image:4.0`.
**`universal-image:4.0` runtime versions**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment-universal-image.html)
## Universal image 5.0 runtime versions
The following table lists the available runtimes for `universal-image:5.0`.
**`universal-image:5.0` runtime versions**
| Runtime name | Version | Specific major and latest minor version |
| --- | --- | --- |
| aws cli | 2.25 | `aws-cli: 2.x` |
| docker compose | 2.34 | `docker-compose: 2.x` |
| dotnet | 8.0 | `dotnet: 8.x` |
| golang | 1.24 | `golang: 1.x` |
| java | corretto21 | `java: corretto21.x` |
| nodejs | 22.0 | `nodejs: 22.x` |
| php | 8.3.16 | `php: 8.x` |
| python | 3.12 | `python: 3.x` |
| ruby | 3.4.2 | `ruby: 3.x` |
| terraform | 1.10.5 | `terraform: 1.x` |
# Devfile commands
Currently, CodeCatalyst only supports `exec` commands in your devfile. For more information, see [Adding commands](https://devfile.io/docs/2.0.0/adding-commands) in the Devfile.io documentation.
The following example shows you how to specify `exec` commands in your devfile.
```
commands:
- id: setupscript
exec:
component: test
commandLine: "chmod +x script.sh"
workingDir: /projects/devfiles
- id: executescript
exec:
component: test
commandLine: "./projects/devfiles/script.sh"
- id: updateyum
exec:
component: test
commandLine: "yum -y update --security"
```
After you're connected to your Dev Environment, you can execute defined commands through the terminal.
```
/aws/mde/mde command
/aws/mde/mde command executescript
```
For long running commands, you can use the streaming flag `-s` to output the execution of the command in real time.
```
/aws/mde/mde -s command
```
**Note**
`command-id` must be lower case.
## Exec parameters supported by CodeCatalyst
CodeCatalyst supports the following `exec` parameters on devfile version 2.0.0.
+ `commandLine`
+ `component`
+ `id`
+ `workingDir`
# Devfile events
Currently, CodeCatalyst only supports `postStart` events in your devfile. For more information, see [postStartObject](https://devfile.io/docs/2.0.0/adding-event-bindings#post-start-object) in the Devfile.io documentation.
The following example shows you how to add `postStart` event bindings in your devfile.
```
commands:
- id: executescript
exec:
component: test
commandLine: "./projects/devfiles/script.sh"
- id: updateyum
exec:
component: test
commandLine: "yum -y update --security"
events:
postStart:
- updateyum
- executescript
```
After startup, your Dev Environment will execute the specified `postStart` commands in the order they are defined. If a command fails, the Dev Environment will continue running and the execution output is stored in the logs under `/aws/mde/logs`.
# Devfile components
Currently, CodeCatalyst only supports `container` components in your devfile. For more information, see [Adding components](https://devfile.io/docs/2.0.0/adding-components) in the Devfile.io documentation.
The following example shows you how to add a startup command to your container in your devfile.
```
components:
- name: test
container:
image: public.ecr.aws/amazonlinux/amazonlinux:2
command: ['sleep', 'infinity']
```
**Note**
When the container has short lived entry command, you must include `command: ['sleep', 'infinity']` to keep the container running.
CodeCatalyst also supports the following properties in your container component: `args`, `env`, `mountSources`, and `volumeMounts`.
# Associating a VPC connection to a Dev Environment
A *VPC connection* is a CodeCatalyst resource which contains all of the configurations needed for your workflow to access a VPC. Space administrators can add their own VPC connections in the Amazon CodeCatalyst console on behalf of space members. By adding a VPC connection, space members can run workflow actions and create Dev Environments that adhere to network rules and can access resources in the associated VPC.
**Important**
Dev Environments with a VPC connection do not support [third-party source repositories linked to CodeCatalyst](source-repositories-link.md).
You can only associate a Dev Environment to a VPC connection upon Dev Environment creation. You can't change the VPC connection associated to your Dev Environment after you create it. If you'd like to use a different VPC connection, you have to delete your current Dev Environment and create new one.
**Note**
Dev Environments can only be associated to a VPC connection with an AWS account that has access to your project. For more information, see [ Configuring project-restricted account connections](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-accounts-restriction.html) in the *Amazon CodeCatalyst Administrator Guide*.
Note that Dev Environments utilize several AWS resources and services upon creation. This means that Dev Environments connect to the following AWS services:
+ Amazon CodeCatalyst
+ AWS SSM
+ AWS KMS
+ Amazon ECR
+ Amazon CloudWatch
+ Amazon ECS
**Note**
AWS Toolkit doesn't support Dev Environments creation with an associated VPC connection. Also note that if you use an IDE other than AWS Cloud9, you may experience loading times of about five minutes.
You must have the **Space administrator** role or **Power user** role to manage VPC connections at the space level. For more information about VPCs, see [ Managing Amazon VPCs in CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.html) in the *CodeCatalyst Administrator Guide*.
# Quotas for Dev Environments in CodeCatalyst
The following table describes quotas and limits for Dev Environments in Amazon CodeCatalyst. For more information about quotas in Amazon CodeCatalyst, see [Quotas for CodeCatalyst](quotas.md).
| | |
| --- |--- |
| Number of Dev Environment hours per month | Dev Environment hours are impacted by the overall storage limits for your space. For more information, see [Pricing](https://codecatalyst.aws/explore/pricing) and [Troubleshooting problems with Dev Environments](devenvironments-troubleshooting.md). |
| Amount of Dev Environment storage per space | Dev Environment storage us impacted by the overall storage limits for your space. For more information, see [Pricing](https://codecatalyst.aws/explore/pricing) and [Troubleshooting problems with Dev Environments](devenvironments-troubleshooting.md). |
| Amount of Dev Environment compute | Dev Environment compute is impacted by the overall storage limits for your space. For more information, see [Pricing](https://codecatalyst.aws/explore/pricing) and [Troubleshooting problems with Dev Environments](devenvironments-troubleshooting.md). |