App Properties

The $app.* namespace exposes platform-injected properties of the deployed app itself. These are resolved at deploy time by whichever provider is running the app, so a Launchfile can reference its own public URL without hardcoding environment-specific values.

The values are determined by the provider's routing strategy at deploy time. A Cloudflare Tunnel deployment might resolve $app.url to https://myapp.example.com; a local development provider might resolve it to http://myapp.lvh.me:10001; a Kubernetes deployment behind an Ingress might resolve it to https://myapp.k8s.internal. The Launchfile stays the same.

The standard set above is the portable vocabulary every provider must support. Providers MAY expose additional $app.* properties (e.g. $app.region, $app.deployment_id) as platform-specific extensions; portable Launchfiles should use only the standard set. Unknown $app.* properties resolve to empty string, matching the behavior of unknown resource properties (see L-4).

$app.url differs from $components.<this>.url in two ways. First, it gives the public URL — the address external users reach the app on — not the internal component port. Second, it works in single-component mode where there is no component name to reference. Use $app.url for public-facing values (auth callback URLs, webhook registration, public-facing email links) and $components.<name>.url for internal cross-component wiring.

Similarly, $app.port is the allocated external port that the platform exposes; provides[].port is the container port the component binds inside its sandbox. They can differ — a component might bind 3000 while the platform exposes 10001.

$app.authority, $app.scheme, and $app.tls are derived directly from $app.url, so a provider that can resolve the URL can resolve all three. $app.authority is the WHATWG URL host — the hostname plus the port, with the port omitted when it is the default for the scheme (:443 under https, :80 under http). $app.scheme is the URL scheme (http or https); $app.tls is the boolean form of that scheme (true when https, else false), provided for apps whose config expects a literal SSL on/off flag rather than a scheme string. Prefer $app.url for the single-string case; reach for these three only when an app needs the public address split into its component fields.

Example use:

env:
  PUBLIC_URL: $app.url                # Drupal, BookStack, Mealie, Firefly III
  BETTER_AUTH_URL: $app.url           # better-auth callback base
  OAUTH_REDIRECT_URI: "${app.url}/oauth/callback"
  WEBHOOK_URL: "${app.url}/webhooks/incoming"

  # Apps that need the public address split into separate fields (HedgeDoc):
  CMD_DOMAIN: $app.authority          # public host[:port] HedgeDoc serves from
  CMD_PROTOCOL_USESSL: $app.tls       # whether the public URL is HTTPS
  CMD_URL_ADDPORT: "false"            # authority already carries the public port

Per-endpoint properties

$app.* describes the app's primary endpoint only. An app that publishes more than one endpoint reaches the others through $app.endpoints.<name>.*, where <name> is the provides entry's name: (named endpoints) and the entry is exposed: true (D-63):

The six are the standard $app.* set less name, each defined per endpoint exactly as App Properties defines it for the primary, and each is a public address: $components.<name>.* stays the component-side address. Five rules:

1. A provider computes every endpoint's address through the same derivation it uses for $app.*. Where a provider publishes a per-endpoint address, the primary endpoint's $app.endpoints.<name>.url is $app.url — the same value, never a second computation.
2. scheme, tls and url read the entry's effective listener (Native TLS): an active certificate binding makes them read https and true.
3. Unnamed endpoints are not addressable — add a name:. An endpoint name is app-wide: the same name on two components is a validation error naming both.
4. Anything else resolves "" with a validate warning naming it: an unknown name, a named endpoint that is not exposed: true, $app.endpoints with no name, $app.endpoints.<name> with no property, a property outside the six, and an endpoint the provider publishes no address for (@launchfile/macos-dev and @launchfile/aws today, where this reaches the primary too and $app.url keeps its own value). A tcp/udp endpoint's "" url and scheme are a defined answer and draw no warning.
5. An orchestrator-supplied publication context asserts the primary endpoint's address only (D-58 rule 4): while one is supplied, every other named endpoint resolves "".

# gitea — the clone URL wants the published SSH address in two pieces
provides:
  - name: web
    protocol: http
    port: 3000
    exposed: true
  - name: ssh
    protocol: tcp
    port: 22
    exposed: true
env:
  GITEA__server__ROOT_URL:
    default: $app.url                        # the primary — same value as $app.endpoints.web.url
  GITEA__server__SSH_DOMAIN:
    default: $app.endpoints.ssh.host         # the published SSH hostname
  GITEA__server__SSH_PORT:
    default: $app.endpoints.ssh.port         # the published SSH port, not 22