HubGuides
hub.yaml reference
Manifest fields, validation rules, and what deployment reads today.
hub.yaml is optional. Put it in the project folder and run hub validate to check it, or pass its text as manifest to the MCP tool hub_validate.
Deployment reads app when you omit --name, and services.*.port for a project with its own Dockerfile. The other fields below pass manifest validation but do not configure the current deployment pipeline. Use Compose for multiple services and volumes, environment commands for variables, and access commands for sharing.
app: my-app
services:
web:
port: 8000Top-level fields
Unknown fields are rejected. app and services are required; other fields default to an empty mapping or list.
| Field | Accepted value |
|---|---|
app | App name, up to 40 characters. login and api are reserved. --name overrides this name when deploying. |
services | Mapping of service names to the service fields below. At least one service is required. |
env | Mapping of environment variable names to strings, numbers, or booleans. Validation converts values to strings. |
secrets | List of environment variable names. Supply actual values through environment commands. |
uses | Mapping of aliases to resource or app references; see below. |
volumes | Mapping of volume names to absolute mount paths, such as data: /var/lib/data. |
public_paths | List of paths starting with /. This field does not change current app access. |
limits | Mapping with optional memory and cpu. Memory is a whole number followed by m or g, such as 512m or 1g. CPU is a number greater than 0 and at most 64. Current allocation follows your plan. |
Names start with a lowercase letter, use only a-z, 0-9, and -, and cannot end in - or contain --. Service names, resource aliases, and volume names allow up to 30 characters. Environment variable names match [A-Z_][A-Z0-9_]*.
access is rejected: set access per instance with hub app my-app access. Runtime policy belongs in Compose's x-hub-runtime, not in hub.yaml.
Service fields
| Field | Accepted value and default |
|---|---|
build | Nonempty build-context string. Defaults to . when image is absent. |
image | Nonempty image string. Cannot appear with build. |
command | Nonempty string. |
port | Integer from 1 to 65535. Only one service can have a port. For a Dockerfile project, this overrides EXPOSE and the fallback port 3000. |
health | Path starting with /. Requires port. |
schedule | Cron string with five whitespace-separated fields. Cannot appear with port. Validation checks the five-field shape, not cron semantics. |
Unknown service fields are rejected. Defining a worker, health path, or schedule here does not start or schedule it; configure services in Compose.
Resource references
Each uses value accepts a shorthand string or an object with from and optional env:
uses:
db: postgres
cache:
from: redis
env: CACHE_URL
api:
from: app:backend/stagingfrom accepts postgres, mongo, redis, app:<app>, or app:<app>/<instance>. An omitted instance means prod; instance names allow up to 20 characters under the same naming rules.
Default variable names are DATABASE_URL, MONGO_URL, and REDIS_URL for the three resources. App references use the alias in uppercase, replace hyphens with underscores, and append _URL; api becomes API_URL. Set env to override that default. Unknown object fields are rejected.
Each variable must have one source across env, secrets, and uses. Duplicate secret names and resource references that resolve to the same variable fail validation. These references do not provision resources or wire dependencies during deployment today; declare your database and its variables in Compose.