[Feature]: Allow manifest actions to send HTTP headers, so engines behind authentication can be managed

Area

Engine or model management

User problem

ActionHTTP in the engine manifest schema carries only a method, a path and a body schema:

type ActionHTTP struct {
    Method     string          `json:"method"`
    Path       string          `json:"path"`
    BodySchema json.RawMessage `json:"body_schema,omitempty"`
}

There is no way to send a request header, so any engine whose API requires authentication cannot be driven by a manifest at all. This is not an edge case — an engine that binds a loopback port and expects a bearer token is a normal shape, and it is the shape you get whenever a local engine also supports remote access.

The concrete example I ran into is Unsloth Studio. Its /api/health is open, so PAIR's readiness and health probes work fine and the engine looks perfectly manageable. But /v1/models returns:

HTTP 401  {"error":{"message":"Not authenticated","type":"authentication_error"}}

so list_models, loaded_models and every model operation fail. The engine can be started and monitored but not used, which is arguably worse than not supporting it at all, because the failure appears only after it looks healthy.

The same applies to vLLM started with --api-key, to SGLang behind a token, and to any engine reached through an authenticating proxy.

Desired outcome

An optional headers map on ActionHTTP, so a manifest can declare what an action needs to send:

"list_models": {
  "http": {
    "method": "GET",
    "path": "/v1/models",
    "headers": { "Authorization": "Bearer {api_key}" }
  },
  "result": { "array": "data", "field": "id" }
}

That implies a way to supply the secret, which is the part worth designing rather than assuming. Some options, roughly in order of how much they widen the trust surface:

• a new {api_key}-style placeholder resolved from the existing per-engine settings the user already edits in the app, alongside the persisted port override
• resolution from the engine's environment, reusing runtime.env so the value lives where the engine's other configuration already lives
• a literal string in the manifest, which is simplest but puts a credential in a file users copy around, so probably worth refusing outright

Alternatives considered

An adapter process that holds the credential and presents an unauthenticated loopback surface to PAIR. This works — it is what I did — but it means every authenticated engine needs a sidecar to be manageable, and the credential ends up in a second place rather than in PAIR's own settings.

Skipping affected engines entirely is the current behavior, and it fails late rather than clearly: health probes pass, so the engine presents as healthy while every model action returns 401.

Compatibility and security implications

Additive and backward compatible: headers absent means today's behavior exactly, and existing manifests are unaffected.

The security consideration is where the secret comes from, not the header mechanism. A literal in the manifest would be the easy path and the wrong one, since manifests are user-editable files that get shared and pasted into issues. Sourcing from per-engine settings or runtime.env keeps the credential in the same places PAIR already treats as configuration. Redaction in logs would want checking too, since action URLs and errors are logged and a header value should never follow them there.

Scoping the feature to actions only, rather than to the readiness and health probes, would also keep the blast radius small — probes generally hit unauthenticated endpoints anyway, as the Unsloth case shows.

Validation approach

A manifest declaring a header against a local server that requires it, asserting the action succeeds and that the same action without the header returns 401. Plus a redaction test asserting the header value does not appear in logs on the failure path.

Happy to test against real engines on DGX Spark hardware if that is useful — the Unsloth Studio case above is reproducible on any machine with Studio installed.

Inizia dalla definizione in Go di ActionHTTP e segui il percorso di esecuzione della richiesta dell’action; poi esamina come vengono gestite le impostazioni per motore, runtime.env e gli errori delle richieste. Definisci la fonte del secret e il comportamento di redazione prima di implementare gli header; il lavoro è completo quando un’action autenticata su un server locale ha esito positivo, la stessa richiesta senza il relativo header restituisce 401 e i valori degli header sono assenti dai log degli errori.