# Service boundaries and pilot readiness

> What RealHW currently supports and what requires an agreed pilot configuration.

Source: https://docs.realhw.dev/guides/service-boundaries/
Documentation index: https://docs.realhw.dev/llms.txt

RealHW offers complete GitLab execution offload: connect a project and keep its
existing pipeline and supported job definitions in GitLab. RealHW supplies
execution capacity for ordinary jobs and hardware-specific jobs, returning traces,
results and artifacts to GitLab. You do not need to convert each job into an API
request. Runner settings and compatible tag coverage must match your project;
validate the CI features your pipeline uses before switching execution over.

You can also run an existing container image directly through the workload
API/CLI, without a pipeline. That path selects reported hardware and returns
status, logs and declared outputs; it does not build your Dockerfile. GitLab
pipelines can retain their existing build jobs.

The current system operates trusted workloads. A general-purpose public service
for arbitrary untrusted code is not currently offered. API authentication and
container packaging do not establish tenant isolation. External pilots require
an agreed isolation boundary, supported hardware profile and operational review.

## One service, configurable execution

Hardware requirements (x86, ARM64, GPU and devices), fleet ownership
(RealHW-managed or customer cloud/hardware), and capacity policy (best effort or
reserved) are dimensions of the same service. GitLab, API and CLI are entry
points. A configuration must be supported and validated as a whole; these choices
do not imply that every combination is available. In particular, ARM KVM needs
hardware that exposes compatible virtualization. Reported capabilities and
provisionable catalog entries are distinct from a verified workload result.

## Capacity and execution

Hardware discovery reports online and provisionable hardware; a matching label
is not a reservation or an immediate-start guarantee. Any reserved-capacity offer
requires an explicit agreement identifying capacity, concurrency and replacement
behavior. A successful provisioning probe does not establish that your program
or guest kernel boots.

A workload's `started_at` currently means a runner accepted it. The runner may
still be preparing the workspace, inputs or image. Do not use that timestamp as
proof that QEMU or your application executed.

Use `queue_timeout_seconds` to bound further dispatch attempts while a workload
is queued or waiting for capacity. See [image workloads](../run-image-workload/)
for the cutoff semantics and the separate overall timeout.

## Evidence and failures

A script failure and an infrastructure failure have different meanings. A job
that never reached execution is not a product test verdict. Status and
provisioning history identify the available evidence.

Final collection prioritizes artifacts over cache uploads and attempts to retain
the workspace when collection fails. A host that disappears can still prevent
final serial/artifact collection. Permanent off-host partial-artifact recovery is
not currently a general guarantee. A job that never booted a guest cannot supply
a guest serial log.

## Images, identity and billing

Remote image submissions currently accept digest-pinned images from the GitLab
Container Registry. Scope API tokens to the project and required operations;
never put credentials in a prompt, issue, repository or workload log. Follow the
[API key guide](../api-keys/) and current private-image submission documentation.

Prepaid credits exist. They do not themselves purchase reserved capacity or an
availability SLA. Never-started jobs have zero compute usage under the existing
metering path. Started infrastructure failures and retries require an explicit
commercial credit policy; do not assume automatic refunds or free retries.

Public availability commitments, reserved pricing, retention and support terms
must be agreed explicitly. A healthy service snapshot or successful deployment
is not proof that a configuration is ready for a paid production workload.