Requires

Declares required resource dependencies. The app will not start without them. Value is an array; each entry is a string (shorthand) or an object.

A string shorthand (requires: [postgres]) expands to [{ type: "postgres" }].

An object entry is one of two kinds, distinguished by its marker field: a backing service (has type:) that the provider provisions and wires, or a host capability (has host:) that the provider grants or refuses — see Host capabilities.

requires:
  - type: postgres
    version: ">=15"
    set_env:
      DATABASE_URL: $url
      DB_HOST: $host
      DB_PASSWORD: $password

Resource naming

By default, a resource's name is its type. Expression references like $postgres.host use this name. When an app requires multiple instances of the same type, use the name field to distinguish them:

requires:
  - type: postgres
    name: primary-db
    set_env:
      PRIMARY_DB_URL: $url
  - type: postgres
    name: analytics-db
    set_env:
      ANALYTICS_DB_URL: $url

References use the name: $primary-db.host, $analytics-db.host. Without name, two resources of the same type would be ambiguous.

Version constraints

The version field uses semver range syntax (as defined by node-semver):

Resource configuration

The config map passes provisioning hints to the platform. Keys and semantics are resource-type-specific:

requires:
  - type: postgres
    version: ">=15"
    config:
      extensions: [pgvector, postgis]
      shared_buffers: 256MB
  - type: redis
    config:
      maxmemory: 256mb
      maxmemory-policy: allkeys-lru

The platform interprets these hints when provisioning the resource. Unknown keys are ignored by platforms that don't support them.

Expression wiring

Values in set_env use the expression syntax. Inside a requires or supports block, bare $prop references resolve against the enclosing resource's property vocabulary.

Real-world examples: See how Ghost, Metabase, and Miniflux declare their database requirements. Browse all apps →

Host capabilities

A requires/supports entry can request a host capability — a privileged grant from the machine the app runs on — instead of a backing service. A capability entry is marked with host:. The provider grants it (mounts or forwards the underlying coordinate and populates the capability's properties) or refuses the deployment with a clear message; it never provisions anything. See PROVIDERS.md for the provider-side contract.

requires:
  - postgres                              # backing service → provision + wire
  - host: { container_runtime: docker }   # capability      → grant or refuse
    set_env:
      DOCKER_HOST: $url
supports:
  - host: { container_runtime: any }      # optional — deploy, probe, degrade

Rules:

• The host: marker is required on every privileged entry. An entry's kind is machine-extractable from the file itself: a bare string or type: entry is a backing service; a host: entry is a capability. Anyone — tooling or a human reviewer — can list an app's full privilege surface with zero extra tooling. launchfile validate prints it as host capabilities requested: […].
• The value names an interface, never a product. container_runtime: docker means "the Docker Engine API" — a Podman-compatible socket satisfies it — exactly as requires: postgres names a wire protocol, not a vendor. container_runtime: any is runtime-agnostic. The vocabulary is open: unknown capability names and values are tolerated by parsers; a provider that cannot grant a required capability it does not understand refuses.
• Required vs optional is requires vs supports. A capability in requires must be granted or the provider refuses to deploy the component. A capability in supports is optional: the app deploys without it, probes its env vars at startup, and degrades gracefully.
• Wiring uses set_env, exactly as for backing services. A granted capability exposes provider-supplied properties (below); bare $prop references inside the entry resolve against the enclosing capability's properties.

Capability properties

Like resource properties, a granted capability exposes a standard set of properties the provider computes from how it granted the capability:

Properties a provider cannot supply resolve to the empty string, matching unknown resource properties.

Capability vocabulary

network, filesystem, and privileged are the entry-form spelling of the legacy host block keys — they are grant/refuse capabilities like any other. That block is deprecated in launch/v1 and removed in launch/v2 (D-58); entries are the form to write. Existing files using the block stay valid and keep their meaning for the whole of launch/v1 — see Migrating off the host: block.