The spec
One multihull.yaml per service. A pydantic v2 model validates it; hull schema exports JSON Schema for editor completion.
Sections
Section titled “Sections”| Section | Purpose |
|---|---|
container |
Image or build, command, port, health probe, env, secret names |
resources |
GPU classes (any-of, in preference order), GPU count, memory |
scaling |
Concurrency per replica, min and max replicas |
reliability |
Redundancy floor: minWarmProviders, overprovision, fallbackScaleToZero, spot |
targets |
One entry per provider deployment with priority and provider-specific block |
route |
Hostname, protocol, failover policy, auth, optional sticky routing |
GPU classes
Section titled “GPU classes”A normalised enum: L4, A10G, A100-40, A100-80, H100, H200, B200. Each translator maps classes to provider SKUs and reports which it can supply through gpu_inventory, which feeds hull doctor.
Credentials
Section titled “Credentials”Never in the file. Each target reads its provider’s native location by default. Set credentials on a target to read them elsewhere, for example a second account or a kubeconfig outside KUBECONFIG:
targets: - provider: gke-prod type: kubernetes priority: 1 credentials: file:~/.kube/prod.yaml - provider: runpod-eu type: runpod priority: 2 credentials: env:RUNPOD_EU_KEY-
env:NAMEreads environment variable NAME.file:PATHreads a file;~expands to the home directory and a relative path resolves against the working directory ofhull(use an absolute path forhull controllerin a container). -
The value has the provider’s native format:
Type Native location Override value runpodRUNPOD_API_KEYthe API key basetenBASETEN_API_KEYthe API key replicateREPLICATE_API_TOKENthe API token; cog loginstill readsREPLICATE_CLI_AUTH_TOKENor an existing loginkuberneteskubeconfig ( KUBECONFIG,~/.kube/config) or in-clusterkubeconfig YAML; kubernetes.contextpicks the context, else itscurrent-contextmodalMODAL_TOKEN_IDandMODAL_TOKEN_SECRET, or~/.modal.toml.modal.tomlTOML, profile tables only: theactive = trueprofile, else a lone profile nameddefault, neverMODAL_PROFILE(see below); it needstoken_idandtoken_secret(OAuth profiles andserver_urlare not read)docker~/.docker/config.jsonfor image pullsDocker config.json(auths,credsStoreorcredHelpers); a registry it has no entry for is pulled anonymously, and withdocker.pull: falsea missing image is pulled with it too -
An override replaces the native location; a missing or unreadable override fails, it never falls back.
hull doctornames the variable or path that is missing. -
State keeps the reference (never the value), so a target removed from the spec can still be torn down:
hull destroy --target <name>uses it and shows it in the confirmation. A plainhull destroyuses no stored reference: it stops before destroying anything, names each such target and prints the--targetcommand to run first. Add your own--stateand--snapshot-outto it; the hint asks for them instead of printing them, since a state URL can carry a password. -
The value is never logged, printed, stored in state or written to a plan; errors name only the variable or path. The one exception is RunPod, Baseten and Replicate traffic: the router signs such a target’s requests and probes with that target’s key, so it reaches the snapshot as
Authorization.RUNPOD_ENDPOINT_API_KEYandBASETEN_INFERENCE_API_KEYare process-wide and apply only to targets withoutcredentials, since another account’s endpoint would reject them;hull doctorsays so (see Security). -
Modal proxy auth tokens (
MODAL_PROXY_TOKEN_ID,MODAL_PROXY_TOKEN_SECRET) are traffic credentials, not deploy credentials, and are not overridden. -
A Modal override ignores
MODAL_PROFILE, which Modal itself reads before the active profile. It is process-wide while each override belongs to one target, often another account, so applying it to every override would fail targets whose file lacks that profile or quietly switch accounts. Mark the profile to use withactive = truein the override file.hull doctornames the profile each override uses, and the error for an override with no active profile says whenMODAL_PROFILEwas set but not used. Targets withoutcredentialskeep Modal’s own rules,MODAL_PROFILEfirst. -
With a Modal override, the
modal app stopthathull destroyruns sees only the override: the native~/.modal.toml,MODAL_PROFILE,MODAL_TOKEN_*andMODAL_OAUTH_*are hidden from it. Deploy, status, scale, logs andhull doctorrun the Modal SDK insidehull, and it still reads the native config (MODAL_CONFIG_PATH, default~/.modal.toml) even with an override: a malformed native file, one with several active profiles, or one with several profiles and none active whileMODAL_PROFILEis unset ordefaultfails every Modal target, overrides included (Modal’s own config check, run insideClient.from_credentials). SettingMODAL_PROFILEto one of the native profiles, or marking oneactive = true, gets override targets past that last case. A nativeserver_url(orMODAL_SERVER_URL) also applies to override targets, read from the native profile Modal picks, soMODAL_PROFILEstill selects that one. Only the tokens come from the override.
Service secrets are listed by name only and mirrored into each provider’s native secret store. hull deploy reads each value from the environment variable named after the secret in upper case, with - and . as _. Kubernetes, Modal, RunPod and Baseten pass it to the container under exactly the listed name (Docker uses that upper-case form instead; Replicate refuses secrets), so list the variable the program reads, such as HF_TOKEN. A valid environment variable name is letters, digits and underscores, not starting with a digit. Modal rejects any other name at deploy, so for a Modal target hull plan notes it and apply refuses it before calling Modal. For Kubernetes, RunPod and Baseten targets, hull validate, plan and deploy warn about it instead. Kubernetes still refuses a name that is not a valid Secret key, such as one with a space, and a container.env name its API server rejects (see Kubernetes). Docker refuses a container.env or docker.env name that is empty before any = or contains =, which the daemon would reject or split.
Route API keys
Section titled “Route API keys”route.auth.apiKeys.from names where keys live: env:NAME holds a comma-separated list, file:PATH one key per line (# starts a comment line; a relative path resolves against the working directory). Each key is hull_<id>_<secret>: the id is ASCII letters and digits, the secret printable ASCII without spaces. hull rejects any other shape, and a source that yields no keys, before it deploys or publishes a snapshot, and only blake3("<id>_<secret>") reaches the router. See Router overview.
Full example
Section titled “Full example”See examples/llama-8b/multihull.yaml in the repository or the architecture plan.