Skip to content

Example: Run a KVM guest

It is possible to launch a Virtual Machine (VM) within a GitHub Action. Support for virtualization is not enabled by default for Actuated. The Agent has to be configured to use a custom kernel.

There are some prerequisites to enable KVM support:

  • aarch64 runners are not supported at the moment.
  • A bare-metal host for the Agent is required.

Nested virtualisation is a premium feature

This feature requires a plan size of 15 concurrent builds or greater, however you can get a 14-day free trial by contacting our team directly through the actuated Slack.

Configure the Agent

  1. Make sure nested virtualization is enabled on the Agent host.

  2. Edit /etc/default/actuated on the Actuated Agent and add the kvm suffix to the AGENT_KERNEL_REF variable:

  3. Also add it to the AGENT_IMAGE_REF line:

  4. Restart the Agent to use the new kernel.

    sudo systemctl daemon-reload && \
        sudo systemctl restart actuated
  5. Run a test build to verify KVM support is enabled in the runner. The specs script from the test build will report whether /dev/kvm is available.

Run a Firecracker microVM

This example is an adaptation of the Firecracker quickstart guide that we run from within a GitHub Actions workflow.

The workflow instals Firecracker, configures and boots a guest VM and then waits 20 seconds before shutting down the VM and exiting the workflow.

  1. Create a new repository and add a workflow file.

    The workflow file: ./.github/workflows/vm-run.yaml:

    name: vm-run
    on: push
        runs-on: actuated-4cpu-8gb
        - uses: actions/checkout@master
            fetch-depth: 1
        - name: Install arkade
            uses: alexellis/setup-arkade@v2
        - name: Install firecracker
            run: sudo arkade system install firecracker
        - name: Run microVM
            run: sudo ./
  2. Add the script to the root of the repository.

    Running the script will:

    • Get the kernel and rootfs for the microVM
    • Start fireckracker and configure the guest kernel and rootfs
    • Start the guest machine
    • Wait for 20 seconds and kill the firecracker process so workflow finishes.

    The script:

    # Clone the example repo
    git clone
    # Run the VM script
  3. Hit commit and check the run logs of the workflow. You should find the login prompt of the running microVM in the logs.

The full example is available on GitHub

For more examples and use-cases see: