boot_spec.md

Boot Spec

Purpose

LlamaCppSdk.BootSpec is the canonical launch contract for the backend. Raw caller input is normalized once, and all later layers consume the typed spec instead of re-reading arbitrary option maps.

Supported Fields

The first release normalizes these fields:

• binary_path
• launcher_args
• model
• alias
• model_identity
• host
• port
• api_prefix
• ctx_size
• gpu_layers
• threads
• threads_batch
• parallel
• flash_attn
• embeddings
• api_key
• api_key_file
• timeout_seconds
• threads_http
• pooling
• ready_timeout_ms
• readiness_interval_ms
• health_interval_ms
• stop_timeout_ms
• execution_surface
• environment
• extra_args
• metadata
• governed_authority

execution_surface is intentionally narrow in the first release: only :local_subprocess is accepted, even though the lower substrate now has SSH and guest placement breadth elsewhere in the stack.

Derived Fields

Normalization also derives endpoint-facing fields:

• root_url
• base_url
• health_url
• headers

That keeps endpoint publication deterministic and avoids re-deriving URLs in multiple modules. headers are derived from either api_key or the contents of api_key_file so the published endpoint remains directly usable by northbound clients.

Governed Authority

governed_authority selects governed local service materialization. It is a standalone field because governed mode must not infer endpoint auth, model config, attach refs, or process env from normal caller options or ambient machine state.

The authority packet supplies:

• endpoint, service identity, model config, target, attach grant, operation policy, and redaction refs
• optional credential and credential lease refs
• materialized model path, alias, model identity, host, port, API prefix, and service auth
• materialized subprocess environment and backend command fields

When it is present, direct boot-spec fields that can carry endpoint auth, model configuration, process env, subprocess command material, attach metadata, or arbitrary metadata are rejected with {:unmanaged_governed_boot_field, field}. Standalone callers keep the existing direct-field behavior by omitting governed_authority.

Instance Identity

BootSpec.instance_key/1 includes the fields that materially affect runtime identity and reuse, including:

• model identity
• host and port
• flag-bearing launch knobs
• execution surface
• environment and extra args

Additive metadata does not affect the instance key.

Unsupported In The First Release

The first release rejects Unix-socket hosts and rejects non-local execution surfaces such as :ssh_exec. Those are additive future paths, not hidden partial support.