SKIP_TO_MAIN_CONTENT
machine.dev
SIGN_UP
04.0 // Documentation v1.12.2 Last updated 2026-10-12

Quickstart

Get your first machine.dev GPU runner job running in about 5 minutes. Install the GitHub App, enable self-hosted runners, push a workflow.

[INDEX] // ALL_DOCS ›
[TOC] // ON_THIS_PAGE ›

This guide walks you from zero to a green machine.dev job in about 5 minutes. By the end you’ll have a workflow that boots a T4G GPU runner, prints nvidia-smi, and shuts down. T4G spot starts at $0.00261/min.

Prerequisites

  • A GitHub account
  • A repository where you can add a workflow file (any repo will do, even an empty one)
  • Permission to install GitHub Apps on your account or organization

Create a machine.dev account

Go to app.machine.dev/signup and sign in with GitHub. New accounts get $10 of free compute, enough for ~63 hours of T4G GPU time at today’s spot rates.

Non-paying teams can run one job at a time, with a 30-minute limit per job. Buying compute or subscribing removes the 30-minute limit. Promotional grants alone do not count as a purchase. See Billing & limits for paid concurrency limits.

Install the Machine Provisioner

After signing in, you’ll be prompted to install the Machine Provisioner GitHub App. Pick the account or organization you want to use machine.dev with. Then either grant access to all repositories or pick specific ones.

Enable self-hosted runners on your org

GitHub blocks self-hosted runners by default for security. You need to enable them once per org.

See Enable self-hosted runners for the click-by-click steps. Takes about 30 seconds.

If you’re using a personal repo (not an org), self-hosted runners are typically enabled by default. You can skip this step.

Add a workflow file

After connecting GitHub, the dashboard’s Run your first GPU job card offers a copyable sample and lists repositories the installation can access. Select a repository to open GitHub’s new-file editor with a sample workflow already filled in. Review and commit it, then open the repository’s Actions tab to run it. The card also appears on the dashboard and Job Runs page until your team has run its first job.

To create the workflow yourself, add .github/workflows/machine-test.yml in your repository with this content:

name: machine.dev quickstart
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  hello-gpu:
    runs-on: machine/gpu=t4g/tenancy=spot
    steps:
      - uses: actions/checkout@v4

      - name: Show GPU info
        run: nvidia-smi

      - name: Show CPU info
        run: |
          echo "Architecture: $(uname -m)"
          echo "vCPUs: $(nproc)"
          echo "RAM: $(free -h | awk '/^Mem:/{print $2}')"

Commit and push this file to your main branch.

Prevent job-stealing on busy repos

Everything machine.dev needs is packed into one label, led by machine and split on /. When you run many jobs at once, add id=${{ github.run_id }} so the runner is pinned to this exact run and can’t be grabbed by another job:

    runs-on: machine/id=${{ github.run_id }}/gpu=t4g/tenancy=spot

See Configuration → Label format for the full rules.

Watch it run

Open the Actions tab in your repository on GitHub. You should see the “machine.dev quickstart” workflow running. Within about a minute, the job will:

  1. Get picked up by a freshly provisioned machine.dev T4G runner
  2. Print the GPU details (nvidia-smi)
  3. Print the CPU info (4 vCPUs, 8 GB RAM, ARM64 Graviton)
  4. Finish and shut down

Total runtime: about 30 to 60 seconds. Cost: about one minute at the T4G spot rate (from $0.00261/min).

What just happened

When you pushed the workflow file, GitHub Actions saw the runs-on: machine/gpu=t4g/tenancy=spot label. It handed the job off to the Machine Provisioner, which launched a fresh AWS spot instance with an NVIDIA T4G GPU (16 GB VRAM, ARM64 Graviton). The runner agent inside the VM registered itself with GitHub as an ephemeral self-hosted runner, GitHub dispatched the job, and the runner shut down when the job finished.

You only paid for the seconds the runner was actually up.

Where to go next