# hub.yaml reference

Source: https://docs.myhub.host/hub-yaml

`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](https://docs.myhub.host/deploy/compose) for multiple services and volumes, [environment commands](https://docs.myhub.host/environment) for variables, and [access commands](https://docs.myhub.host/access) for sharing.

```yaml title="hub.yaml"
app: my-app
services:
  web:
    port: 8000
```

## Top-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](https://docs.myhub.host/environment).                                                                                                  |
| `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](https://docs.myhub.host/instances) with `hub app my-app access`. Runtime policy belongs in Compose's [`x-hub-runtime`](https://docs.myhub.host/deploy/compose#runtime-policy), 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](https://docs.myhub.host/deploy/compose).

## Resource references

Each `uses` value accepts a shorthand string or an object with `from` and optional `env`:

```yaml
uses:
  db: postgres
  cache:
    from: redis
    env: CACHE_URL
  api:
    from: app:backend/staging
```

`from` 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.