Run builds locally with the AWS CodeBuild agent - AWS CodeBuild

Run builds locally with the AWS CodeBuild agent

You can use the AWS CodeBuild agent to run CodeBuild builds on a local machine. You can also subscribe to notifications about new versions of the agent.


Before you begin, you need to do the following:

  • Install Git on your local machine.

  • Install and setup Docker on your local machine.

Setup the build image

You only need to set up the build image the first time you run the agent, or when the image has changed.

To set up the build image

  1. Clone the CodeBuild image repo:

    $ git clone
  2. Build the image. For this example, use the aws/codebuild/standard:4.0 image. This will take several minutes.

    $ cd aws-codebuild-docker-images/ubuntu/standard/4.0 $ docker build -t aws/codebuild/standard:4.0 .
  3. Run the following Docker command to download the local CodeBuild agent.:

    $ docker pull amazon/aws-codebuild-local:latest --disable-content-trust=false
  4. The CodeBuild agent is available from Its Secure Hash Algorithm (SHA) signature is:


    You can use this to identify the version of the agent. To see the agent's SHA signature, run the following command:

    $ docker inspect amazon/aws-codebuild-local

Run the CodeBuild agent

To run the CodeBuild agent

  1. Change to the directory that contains your build project source.

  2. Download the script:

    $ wget $ chmod +x
  3. Run the script and specify your container image and the output directory:

    $ ./ -i aws/codebuild/standard:4.0 -a <output directory>

    The script launches the build image and runs the build on the project in the current directory. To specify the location of the build project, add the -s <build project directory> option to the script command.

Receive notifications for new CodeBuild agent versions

You can subscribe to Amazon SNS notifications so you know when new versions of the AWS CodeBuild agent are released.

To subscribe to CodeBuild agent notifications

  1. Open the Amazon SNS console at

  2. In the navigation bar, if it's not already selected, change the AWS Region to US East (N. Virginia). You must select this AWS Region because the Amazon SNS notifications that you are subscribing to are created in this Region.

  3. In the navigation pane, choose Subscriptions.

  4. Choose Create subscription.

  5. In Create subscription, do the following:

    1. For Topic ARN, use the following Amazon Resource Name (ARN):

    2. For Protocol, choose Email or SMS.

    3. For Endpoint, choose where (email or SMS) to receive the notifications. Enter an email or address or phone number, including area code.

    4. Choose Create subscription.

    5. Choose Email to receive an email asking you to confirm your subscription. Follow the directions in the email to complete your subscription.

      If you no longer want to receive these notifications, use the following procedure to unsubscribe.

To unsubscribe from CodeBuild agent notifications

  1. Open the Amazon SNS console at

  2. In the navigation pane, choose Subscriptions.

  3. Select the subscription and from Actions, choose Delete subscriptions. When you are prompted to confirm, choose Delete.