Private Runner Images

If your runner image lives in a private registry, Runaway pulls it with an operator-managed credential. The credential attaches on the runner profile that defines the image, so every workload using that profile pulls with it. Credentials are stored encrypted at rest and never echoed back to the UI.

Add a credential and attach it

1. Add the credential. Open the image-credentials tab and add an entry for the registry — its host, a username, and a password or token. Runaway encrypts it at rest immediately; the secret is never returned to the browser after you save.

2. Attach it to the runner profile. Open the runner profile’s settings and select the credential under its image-pull setting. The next time Runaway pulls that profile’s runner image, it authenticates with the attached credential.

Note

The password is decrypted on the hub once per reconcile pass and forwarded to the target host’s agent over the authenticated WebSocket link. It is never persisted or logged on the agent, and never echoed in any UI response.

Pull failures fail loud

A pull failure hard-fails the spawn for that pass and surfaces a clear per-host error. The hub never falls back to a stale cached layer, so a broken or expired credential shows up as an explicit error rather than runners quietly running an old image.

Caution

If you remove a credential that a runner profile still references, the next pull is attempted anonymously and will fail loudly for a private image — it will not reuse a stale cached layer. Re-attach a valid credential to recover.

Pull policy recap

The credential governs authentication; the runner profile’s pull policy governs when the pull happens:

• IfNotPresent — pull only when the image isn’t already on the host.
• Always — pull on every spawn.
• TtlHours — pull only if the last pull is older than the configured TTL.

New profiles default to TtlHours / 24h. For the full settings reference, see Runner profiles.

Related

Runner profiles

Workloads