Manifest reference

Every valid field of apphaven.yaml, on one page. For worked examples and explanations, see The manifest and the Configuration pages; anything not listed here is rejected by validation.

Top level

Field	Type	Required	Description
version	int	no	Manifest schema version. Currently 1 (the default).
services	map of name → service	yes	At least one service.
volumes	map of name → volume	no	Volumes. Required only if a service references one.
proposals	list	no	Configuration recommendations, imported only from the production branch.
auth	object	no	Public-path suggestions for the app's access settings.

Service and volume names must match ^[a-zA-Z0-9][a-zA-Z0-9_\-]{0,63}$: 1–64 characters of letters, digits, _, and -, starting with a letter or digit. Use lowercase names.

services.<name>

Every service has a type, which decides its other fields:

Field	Type	Required	Description
type	string	yes	container or postgres.
depends_on	list of {service, condition}	no	Start ordering. Valid on every type.

type: container

→ Container services

Field	Type	Required	Description
image	string	conditional	Required unless build is set. Any pullable image reference. With build, names the build result.
build	object	conditional	Build from source; see build. A container service declares image or build.
ports	list of int	no	Ports the service listens on, each 1–65535.
env	map<string, string>	no	Environment variables. Values may use references.
volumes	list of {name, mount_path}	no	Volume mounts; see mounts.
healthcheck	object	no	See healthcheck.

build

Field	Type	Required	Description
dockerfile	string	no	Path to the Dockerfile, relative to context. Default Dockerfile.
context	string	no	Build context directory, relative to the repo root. Default ..
args	map<string, string>	no	Docker build args. Values may use references.

Service volume mounts

Field	Type	Required	Description
name	identifier	yes	A key of the top-level volumes map.
mount_path	string	yes	Absolute, canonical path inside the container: no .., . segments, trailing /, or //.

healthcheck

Field	Type	Required	Description
test	list of string	yes	["CMD", ...] or ["CMD-SHELL", "<shell command>"]. Runs inside the container.
interval	duration	no	Time between checks. Default 10s. 1s–5m.
timeout	duration	no	Per-check timeout. Default 3s. 1s–5m.
retries	int	no	Failures before unhealthy. Default 3. 1–20.
start_period	duration	no	Grace period before failures count. Default 0s. Up to 5m.

A duration is a positive whole number followed by s or m, e.g. 10s, 5m; start_period also accepts 0s.

type: postgres

→ Database

Field	Type	Required	Description
version	string	no	PostgreSQL major version. Supported: "17". Default "17".

version is the only field you set. image, ports, env, volumes, and healthcheck are managed by the platform and not accepted on a postgres service; storage comes from the deployment's storage budget. Up to four postgres services per app.

depends_on

→ Start order

Field	Type	Required	Description
service	identifier	yes	Another service in this manifest. The dependency graph must be acyclic.
condition	string	no	started (default) or healthy. healthy requires the target to have a healthcheck (managed databases have one built in).

volumes.<name>

→ Volumes

Field	Type	Required	Description
type	string	yes	ephemeral or persistent.

Storage comes from the deployment's storage budget; there is no per-volume size.

auth.public_paths

→ Public paths

Paths your repository asks to be reachable without an AppHaven login. This block is a suggestion and nothing more. It has no effect on what is served. Each entry appears in the app's Proposals section from the production branch and stays inactive until an administrator approves it and the branch next deploys. Prefer the general proposals section with explicit stable IDs for new recommendations.

auth:
  public_paths:
    - path: /api/*
      reason: Partner REST API, authenticated by our own API keys
    - path: /healthz
      reason: Uptime probe

Field	Type	Required	Description
path	string	yes	An exact path (/healthz, or / for the root path only) or a prefix ending in /* (/api/*). Up to 128 characters.
reason	string	yes	Why the path needs to be open. Shown to the administrator deciding whether to add it.

A path starts with / and uses letters, digits, ., _, ~, -, and /. The only wildcard is a single trailing /*. Up to 10 entries; an eleventh is a validation error.

Values in env

→ Connection references

env values and build.args are plain strings, and may contain references that are resolved when your app starts:

Syntax	Meaning
${service.<name>.<field>}	A connection detail of a postgres service in this manifest. Fields: url, host, port, user, password, database.
$${	Escapes a literal ${.

proposals

Optional list of configuration recommendations. Each item requires id (1–64 lowercase letters, digits, underscores or hyphens, starting with a letter), type, typed value, and reason (1–1000 characters). At most 50 entries including compatibility public-path suggestions. IDs must be unique. The supported types, value schemas, examples, limits and decision lifecycle are in Change proposals.

Only the configured production branch is imported. Unknown operations and malformed recommendations are authoring/import errors, but do not block an otherwise valid workload deployment. Workload fields still receive strict deployment validation. Accepted settings live in the console; editing or removing a recommendation never changes them automatically.