Private Runner Images

If your runner image lives in a private registry, Runaway pulls it with an operator-managed credential. 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 scale set. Open the scale set’s settings and select the credential under its image-pull setting. The next time Runaway pulls that scale set’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 silently 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 scale set 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 scale set’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 scale sets default to TtlHours / 24h. For the full settings reference, see Configuring scale sets.

Related

Configuring scale sets