RealHW

Developer docs for workloads that need real hardware.

Run your first job Run an image workload

RealHW offers complete GitLab execution offload: connect your project and keep your existing pipeline and supported job definitions. GitLab orchestrates the pipeline; RealHW supplies execution capacity and returns job results, logs and artifacts. You do not need to rewrite every job into a new API workflow. Keep using familiar GitLab tags for ordinary jobs, then ask for GPUs, KVM, NICs, SR-IOV, NUMA placement, hugepages, or a specific CPU architecture when the workload needs them. The web app manages project runners, pipeline placement, usage, and interactive hardware leases.

qemu-tests:
  tags:
    - realhw
    - arch:x86_64
    - kvm
  script:
    - ./run-qemu-tests.sh
  artifacts:
    when: always
    paths:
      - results/

The runner admits the request before the job starts, projects only allowlisted devices, streams logs through the lifecycle, and returns the job result to GitLab.

Set up with your agent

Give this prompt to your coding agent to install the CLI and verify access. Repository access is required during early access.

Preview prompt

Set up the RealHW CLI on this machine using https://docs.realhw.dev/get-started/agent-setup/index.md as the canonical guide. Read it first and follow its pinned checkout installation instructions; the CLI is not published on PyPI and repository access is required. Preserve existing checkouts and credentials. Use an existing environment token without displaying it, or guide me through browser login with read-only permissions. Never ask me to paste credentials into this conversation. Verify the CLI version, supported operations, and current hardware with JSON commands. Report any access or setup blocker clearly. Stop after verification; do not reserve hardware or start workloads.

Setup instructions

Choose your path

Open the dashboard

Manage project runners, inspect placement, and review usage in the RealHW app.

Select hardware

Browse the marker catalog and compose a request from stable capability tags.

Run an image locally

Use the local runner CLI to launch an existing OCI image and collect artifacts.

Debug placement

Trace tags, capacity, admission, and unsupported requests when a job waits.

Developer reference

Need	Start here
GitLab job examples	CI examples
CPU and architecture	CPU and architecture
GPUs and device counts	GPU markers
KVM, artifacts, and cloud-init	Run an image workload
Runner selection failures	Debug runner selection