Skip to content

Spec schema

Export the schema and point your editor at it for completion and validation:

Terminal window
hull schema --out multihull.schema.json
# yaml-language-server: $schema=./multihull.schema.json
apiVersion: multihull/v1
name: llama-8b

See The spec for the section-by-section description.

Top-level document. Schema id: https://multihull.pages.dev/schema/v1/multihull.schema.json.

Field Type Default Constraints
apiVersion const "multihull/v1" required
name string required max length 40, pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
container Container required
resources Resources required
scaling Scaling {"concurrency":null,"replicas":{"max":1,"min":1}}
reliability Reliability {"minWarmProviders":2,"overprovision":1.4,"fallbackScaleToZero":false,"spot":false}
targets array of TargetSpec required min items 1
route Route required
Field Type Default Constraints Description
from string required pattern ^(env|file):.+$ env:NAME (comma-separated keys) or file:PATH (one key per line, # comments). Keys are hull_<id>_<secret>; only blake3("<id>_<secret>") reaches the snapshot. A source that yields no keys is refused.
Field Type Default Constraints
apiKeys ApiKeys, nullable null
Field Type Default Constraints
no fields
Field Type Default Constraints
context string "."
target "docker" | "cog" "docker"
Field Type Default Constraints
image string, nullable null
build Build, nullable null
command array of string, nullable null
port integer 8000 min 1, max 65535
health Health {"path":"/health","initialDelaySeconds":30}
env map of string to string {}
secrets array of string []
Field Type Default Constraints
image string, nullable null
host string "127.0.0.1"
hostPort integer, nullable null
env map of string to string {}
network string, nullable null
pull boolean true
Field Type Default Constraints
policy "priority" | "weighted" | "ewma_latency" | "locality" "priority"
retryOn array of "5xx" | "timeout" | "capacity" | "connect" ["5xx","timeout","capacity"]
maxRetries integer 2 min 0
Field Type Default Constraints
path string "/health"
initialDelaySeconds integer 30 min 0
Field Type Default Constraints
context string, nullable null
namespace string "default"
keda boolean false
prometheusUrl string "http://prometheus-operated.monitoring.svc:9090"
serviceType "LoadBalancer" | "NodePort" | "ClusterIP" "LoadBalancer"
nodePort integer, nullable null
endpoint string, nullable null
Field Type Default Constraints
environment string "main"
region string, nullable null
registrySecret RegistrySecret, nullable null
setupDockerfileCommands array of string []
Field Type Default Constraints
usernameEnv string required pattern ^[A-Za-z_][A-Za-z0-9_]*$
passwordEnv string required pattern ^[A-Za-z_][A-Za-z0-9_]*$
Field Type Default Constraints
minWarmProviders integer 2 min 0
overprovision number 1.4 min 1
fallbackScaleToZero boolean false
spot boolean false
Field Type Default Constraints
min integer 1 min 0
max integer 1 min 1
Field Type Default Constraints
owner string, nullable null
Field Type Default Constraints
gpu array of GPU []
gpuCount integer 1 min 1
memory string, nullable null
Field Type Default Constraints
hostname string required
protocol "openai" | "http" "openai"
failover Failover {"policy":"priority","retryOn":["5xx","timeout","capacity"],"maxRetries":2}
auth Auth, nullable null
sticky Sticky, nullable null
Field Type Default Constraints
dataCenters array of string []
Field Type Default Constraints
concurrency integer, nullable null
replicas Replicas {"min":1,"max":1}
Field Type Default Constraints
key string required
ttl string "30m"
mode "endpoint" | "provider" "endpoint"
onUnhealthy "rehome" | "fail" "rehome"
fallbackKey string, nullable null
Field Type Default Constraints
min integer, nullable null
max integer, nullable null
Field Type Default Constraints Description
provider string required min length 1
type "kubernetes" | "modal" | "runpod" | "baseten" | "replicate" | "docker" required
priority integer required min 1
replicas TargetReplicas, nullable null
weight integer 1 min 1
credentials string, nullable null Where this target’s provider credentials come from instead of the native location: env:NAME reads environment variable NAME, file:PATH reads a file (~ expands, a relative path resolves against the working directory). The value uses the provider’s native format: the API key or token for RunPod, Baseten and Replicate, kubeconfig YAML for Kubernetes, .modal.toml for Modal, Docker config.json for Docker registry pulls. The value is never logged, stored in state or put in a plan.
kubernetes KubernetesBlock, nullable null
modal ModalBlock, nullable null
runpod RunpodBlock, nullable null
baseten BasetenBlock, nullable null
replicate ReplicateBlock, nullable null
docker DockerBlock, nullable null
  • "L4"
  • "A10G"
  • "A100-40"
  • "A100-80"
  • "H100"
  • "H200"
  • "B200"
multihull.schema.json
{
"$defs": {
"ApiKeys": {
"additionalProperties": false,
"properties": {
"from": {
"description": "`env:NAME` (comma-separated keys) or `file:PATH` (one key per line, `#` comments). Keys are `hull_<id>_<secret>`; only `blake3(\"<id>_<secret>\")` reaches the snapshot. A source that yields no keys is refused.",
"pattern": "^(env|file):.+$",
"title": "From",
"type": "string"
}
},
"required": [
"from"
],
"title": "ApiKeys",
"type": "object"
},
"Auth": {
"additionalProperties": false,
"properties": {
"apiKeys": {
"anyOf": [
{
"$ref": "#/$defs/ApiKeys"
},
{
"type": "null"
}
],
"default": null
}
},
"title": "Auth",
"type": "object"
},
"BasetenBlock": {
"additionalProperties": false,
"properties": {},
"title": "BasetenBlock",
"type": "object"
},
"Build": {
"additionalProperties": false,
"properties": {
"context": {
"default": ".",
"title": "Context",
"type": "string"
},
"target": {
"default": "docker",
"enum": [
"docker",
"cog"
],
"title": "Target",
"type": "string"
}
},
"title": "Build",
"type": "object"
},
"Container": {
"additionalProperties": false,
"properties": {
"image": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Image"
},
"build": {
"anyOf": [
{
"$ref": "#/$defs/Build"
},
{
"type": "null"
}
],
"default": null
},
"command": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Command"
},
"port": {
"default": 8000,
"maximum": 65535,
"minimum": 1,
"title": "Port",
"type": "integer"
},
"health": {
"$ref": "#/$defs/Health",
"default": {
"path": "/health",
"initialDelaySeconds": 30
}
},
"env": {
"additionalProperties": {
"type": "string"
},
"default": {},
"title": "Env",
"type": "object"
},
"secrets": {
"default": [],
"items": {
"type": "string"
},
"title": "Secrets",
"type": "array"
}
},
"title": "Container",
"type": "object"
},
"DockerBlock": {
"additionalProperties": false,
"properties": {
"image": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Image"
},
"host": {
"default": "127.0.0.1",
"title": "Host",
"type": "string"
},
"hostPort": {
"anyOf": [
{
"maximum": 65535,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Hostport"
},
"env": {
"additionalProperties": {
"type": "string"
},
"default": {},
"title": "Env",
"type": "object"
},
"network": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Network"
},
"pull": {
"default": true,
"title": "Pull",
"type": "boolean"
}
},
"title": "DockerBlock",
"type": "object"
},
"Failover": {
"additionalProperties": false,
"properties": {
"policy": {
"default": "priority",
"enum": [
"priority",
"weighted",
"ewma_latency",
"locality"
],
"title": "Policy",
"type": "string"
},
"retryOn": {
"default": [
"5xx",
"timeout",
"capacity"
],
"items": {
"enum": [
"5xx",
"timeout",
"capacity",
"connect"
],
"type": "string"
},
"title": "Retryon",
"type": "array"
},
"maxRetries": {
"default": 2,
"minimum": 0,
"title": "Maxretries",
"type": "integer"
}
},
"title": "Failover",
"type": "object"
},
"GPU": {
"enum": [
"L4",
"A10G",
"A100-40",
"A100-80",
"H100",
"H200",
"B200"
],
"title": "GPU",
"type": "string"
},
"Health": {
"additionalProperties": false,
"properties": {
"path": {
"default": "/health",
"title": "Path",
"type": "string"
},
"initialDelaySeconds": {
"default": 30,
"minimum": 0,
"title": "Initialdelayseconds",
"type": "integer"
}
},
"title": "Health",
"type": "object"
},
"KubernetesBlock": {
"additionalProperties": false,
"properties": {
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Context"
},
"namespace": {
"default": "default",
"title": "Namespace",
"type": "string"
},
"keda": {
"default": false,
"title": "Keda",
"type": "boolean"
},
"prometheusUrl": {
"default": "http://prometheus-operated.monitoring.svc:9090",
"title": "Prometheusurl",
"type": "string"
},
"serviceType": {
"default": "LoadBalancer",
"enum": [
"LoadBalancer",
"NodePort",
"ClusterIP"
],
"title": "Servicetype",
"type": "string"
},
"nodePort": {
"anyOf": [
{
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Nodeport"
},
"endpoint": {
"anyOf": [
{
"pattern": "^https?://\\S+$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Endpoint"
}
},
"title": "KubernetesBlock",
"type": "object"
},
"ModalBlock": {
"additionalProperties": false,
"properties": {
"environment": {
"default": "main",
"title": "Environment",
"type": "string"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Region"
},
"registrySecret": {
"anyOf": [
{
"$ref": "#/$defs/RegistrySecret"
},
{
"type": "null"
}
],
"default": null
},
"setupDockerfileCommands": {
"default": [],
"items": {
"type": "string"
},
"title": "Setupdockerfilecommands",
"type": "array"
}
},
"title": "ModalBlock",
"type": "object"
},
"RegistrySecret": {
"additionalProperties": false,
"properties": {
"usernameEnv": {
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"title": "Usernameenv",
"type": "string"
},
"passwordEnv": {
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
"title": "Passwordenv",
"type": "string"
}
},
"required": [
"usernameEnv",
"passwordEnv"
],
"title": "RegistrySecret",
"type": "object"
},
"Reliability": {
"additionalProperties": false,
"properties": {
"minWarmProviders": {
"default": 2,
"minimum": 0,
"title": "Minwarmproviders",
"type": "integer"
},
"overprovision": {
"default": 1.4,
"minimum": 1,
"title": "Overprovision",
"type": "number"
},
"fallbackScaleToZero": {
"default": false,
"title": "Fallbackscaletozero",
"type": "boolean"
},
"spot": {
"default": false,
"title": "Spot",
"type": "boolean"
}
},
"title": "Reliability",
"type": "object"
},
"Replicas": {
"additionalProperties": false,
"properties": {
"min": {
"default": 1,
"minimum": 0,
"title": "Min",
"type": "integer"
},
"max": {
"default": 1,
"minimum": 1,
"title": "Max",
"type": "integer"
}
},
"title": "Replicas",
"type": "object"
},
"ReplicateBlock": {
"additionalProperties": false,
"properties": {
"owner": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Owner"
}
},
"title": "ReplicateBlock",
"type": "object"
},
"Resources": {
"additionalProperties": false,
"properties": {
"gpu": {
"default": [],
"items": {
"$ref": "#/$defs/GPU"
},
"title": "Gpu",
"type": "array"
},
"gpuCount": {
"default": 1,
"minimum": 1,
"title": "Gpucount",
"type": "integer"
},
"memory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Memory"
}
},
"title": "Resources",
"type": "object"
},
"Route": {
"additionalProperties": false,
"properties": {
"hostname": {
"title": "Hostname",
"type": "string"
},
"protocol": {
"default": "openai",
"enum": [
"openai",
"http"
],
"title": "Protocol",
"type": "string"
},
"failover": {
"$ref": "#/$defs/Failover",
"default": {
"policy": "priority",
"retryOn": [
"5xx",
"timeout",
"capacity"
],
"maxRetries": 2
}
},
"auth": {
"anyOf": [
{
"$ref": "#/$defs/Auth"
},
{
"type": "null"
}
],
"default": null
},
"sticky": {
"anyOf": [
{
"$ref": "#/$defs/Sticky"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"hostname"
],
"title": "Route",
"type": "object"
},
"RunpodBlock": {
"additionalProperties": false,
"properties": {
"dataCenters": {
"default": [],
"items": {
"type": "string"
},
"title": "Datacenters",
"type": "array"
}
},
"title": "RunpodBlock",
"type": "object"
},
"Scaling": {
"additionalProperties": false,
"properties": {
"concurrency": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Concurrency"
},
"replicas": {
"$ref": "#/$defs/Replicas",
"default": {
"min": 1,
"max": 1
}
}
},
"title": "Scaling",
"type": "object"
},
"Sticky": {
"additionalProperties": false,
"properties": {
"key": {
"title": "Key",
"type": "string"
},
"ttl": {
"default": "30m",
"title": "Ttl",
"type": "string"
},
"mode": {
"default": "endpoint",
"enum": [
"endpoint",
"provider"
],
"title": "Mode",
"type": "string"
},
"onUnhealthy": {
"default": "rehome",
"enum": [
"rehome",
"fail"
],
"title": "Onunhealthy",
"type": "string"
},
"fallbackKey": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Fallbackkey"
}
},
"required": [
"key"
],
"title": "Sticky",
"type": "object"
},
"TargetReplicas": {
"additionalProperties": false,
"properties": {
"min": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min"
},
"max": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max"
}
},
"title": "TargetReplicas",
"type": "object"
},
"TargetSpec": {
"additionalProperties": false,
"properties": {
"provider": {
"minLength": 1,
"title": "Provider",
"type": "string"
},
"type": {
"enum": [
"kubernetes",
"modal",
"runpod",
"baseten",
"replicate",
"docker"
],
"title": "Type",
"type": "string"
},
"priority": {
"minimum": 1,
"title": "Priority",
"type": "integer"
},
"replicas": {
"anyOf": [
{
"$ref": "#/$defs/TargetReplicas"
},
{
"type": "null"
}
],
"default": null
},
"weight": {
"default": 1,
"minimum": 1,
"title": "Weight",
"type": "integer"
},
"credentials": {
"anyOf": [
{
"pattern": "^(env:[A-Za-z_][A-Za-z0-9_]*|file:\\S.*)$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Where this target's provider credentials come from instead of the native location: `env:NAME` reads environment variable NAME, `file:PATH` reads a file (`~` expands, a relative path resolves against the working directory). The value uses the provider's native format: the API key or token for RunPod, Baseten and Replicate, kubeconfig YAML for Kubernetes, `.modal.toml` for Modal, Docker `config.json` for Docker registry pulls. The value is never logged, stored in state or put in a plan.",
"title": "Credentials"
},
"kubernetes": {
"anyOf": [
{
"$ref": "#/$defs/KubernetesBlock"
},
{
"type": "null"
}
],
"default": null
},
"modal": {
"anyOf": [
{
"$ref": "#/$defs/ModalBlock"
},
{
"type": "null"
}
],
"default": null
},
"runpod": {
"anyOf": [
{
"$ref": "#/$defs/RunpodBlock"
},
{
"type": "null"
}
],
"default": null
},
"baseten": {
"anyOf": [
{
"$ref": "#/$defs/BasetenBlock"
},
{
"type": "null"
}
],
"default": null
},
"replicate": {
"anyOf": [
{
"$ref": "#/$defs/ReplicateBlock"
},
{
"type": "null"
}
],
"default": null
},
"docker": {
"anyOf": [
{
"$ref": "#/$defs/DockerBlock"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"provider",
"type",
"priority"
],
"title": "TargetSpec",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"apiVersion": {
"const": "multihull/v1",
"title": "Apiversion",
"type": "string"
},
"name": {
"maxLength": 40,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"title": "Name",
"type": "string"
},
"container": {
"$ref": "#/$defs/Container"
},
"resources": {
"$ref": "#/$defs/Resources"
},
"scaling": {
"$ref": "#/$defs/Scaling",
"default": {
"concurrency": null,
"replicas": {
"max": 1,
"min": 1
}
}
},
"reliability": {
"$ref": "#/$defs/Reliability",
"default": {
"minWarmProviders": 2,
"overprovision": 1.4,
"fallbackScaleToZero": false,
"spot": false
}
},
"targets": {
"items": {
"$ref": "#/$defs/TargetSpec"
},
"minItems": 1,
"title": "Targets",
"type": "array"
},
"route": {
"$ref": "#/$defs/Route"
}
},
"required": [
"apiVersion",
"name",
"container",
"resources",
"targets",
"route"
],
"title": "ServiceSpec",
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://multihull.pages.dev/schema/v1/multihull.schema.json"
}