# RealHW

> Developer documentation for hardware-aware GitLab runners.

Source: https://docs.realhw.dev/
Documentation index: https://docs.realhw.dev/llms.txt

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.

```yaml
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

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.


## Choose your path


  ### [Open the dashboard](https://realhw.dev/dashboard)

    Manage project runners, inspect placement, and review usage in the RealHW app.
  
  ### [Select hardware](https://docs.realhw.dev/hardware-markers/)

    Browse the marker catalog and compose a request from stable capability tags.
  
  ### [Run an image locally](https://docs.realhw.dev/guides/run-image-workload/)

    Use the local runner CLI to launch an existing OCI image and collect artifacts.
  
  ### [Debug placement](https://docs.realhw.dev/guides/debug-runner-selection/)

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


## Developer reference

| Need | Start here |
| --- | --- |
| GitLab job examples | [CI examples](https://docs.realhw.dev/gitlab/gitlab-ci-examples/) |
| CPU and architecture | [CPU and architecture](https://docs.realhw.dev/hardware-markers/cpu-and-architecture/) |
| GPUs and device counts | [GPU markers](https://docs.realhw.dev/hardware-markers/gpu/) |
| KVM, artifacts, and cloud-init | [Run an image workload](https://docs.realhw.dev/guides/run-image-workload/) |
| Runner selection failures | [Debug runner selection](https://docs.realhw.dev/guides/debug-runner-selection/) |