Using the Linux VM execution environment

today • 1 min read

Cloud Server v3.x Server v2.x

You can run your jobs in the linux VM (virtual machine) execution environment by using the machine executor and specifying a Linux image. Using the machine executor runs your jobs in a dedicated, ephemeral VM.

Using the machine executor gives your application full access to OS resources and provides you with full control over the job environment. This control can be useful in situations where you need full access to the network stack; for example, to listen on a network interface, or to modify the system with sysctl commands.

To use the machine executor, use the machine key in your job configuration and specify an image:

version: 2.1
jobs:
  my-job:
    machine:
      image: ubuntu-2004:current
    resource_class: large

version: 2.1
jobs:
  my-job:
    machine: true
    resource_class: large

You can view the list of available images in the docs Configuration Reference, or on the Developer Hub. If you are working on an installation of CircleCI server, you will notice in the example above the syntax is slightly different, and the available Linux images are managed by your system administrator.

Available LinuxVM resource classes

Pre-installed software

The most up to date list of pre-installed software can be found on the image builder page. You can also visit the Discuss page for more information.

Additional packages can be installed with sudo apt-get install <package>. If the package in question is not found, sudo apt-get update may be required before installing it.

Use machine with Docker

Using the machine executor also means that you get full access to the Docker process. This allows you to run privileged Docker containers and build new Docker images.

The following example uses an image and enables Docker layer caching (DLC) which is useful when you are building Docker images during your job or workflow.

machine:
  image: ubuntu-2004:202104-01
  docker_layer_caching: true    # default - false

Using machine and IP ranges

The IP range 192.168.53.0/24 is reserved by CircleCI for internal use on the machine executor. This range should not be used in your jobs.

Next steps

To find out about migrating a project from using the Docker executor to using machine, see the Executor Migration from Docker to Machine document.

---

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

• Suggest an edit to this page (please read the contributing guide first).
• To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
• CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

---

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.