Writing a Launchfile

A Launchfile is a YAML file called Launchfile (no extension) that lives in your project root. It declares what your application needs — the platform handles the rest.

File structure

Every Launchfile has a name field. Everything else is optional and additive — you pay complexity cost only for the complexity you actually have.

# The simplest valid Launchfile
name: my-app
runtime: node
commands:
  start: "node server.js"

Declaring resources

Use requires for resources your app cannot run without, and supports for optional enhancements:

requires:
  - type: postgres
    set_env:
      DATABASE_URL: $url

supports:
  - type: redis
    set_env:
      CACHE_URL: $url

The $url expression resolves to the resource's connection URL at deploy time. See the expression syntax reference for all available patterns.

Environment variables

The env block declares app-owned environment variables with optional defaults, descriptions, and generators:

env:
  PORT:
    default: "3000"
  API_KEY:
    required: true
    description: "Third-party API key"
  SESSION_SECRET:
    generator: secret
    sensitive: true

Lifecycle commands

commands.start is one of six lifecycle slots — build, release, start, seed, test, and bootstrap — each with its own failure semantics. Source mode adds install and dev for running natively during development:

commands:
  build: "npm run build"
  release: "npx prisma migrate deploy"
  start: "node server.js"

See Lesson 5 for what each slot's failure costs you, and the spec for the full contract.

Storage

The storage block declares named volumes. Mark data that must survive redeploys as persistent, and volumes whose content only the operator can supply (a music library, a photo collection) with content: operator — the provider binds a directory you pass at launch (--storage music=~/Music) or refuses, never starts with an empty library:

storage:
  data:
    path: /var/lib/app/data
    persistent: true
  music:
    path: /music
    content: operator

env:
  DATA_DIR: $storage.data.path   # the volume's real provisioned path

See Lesson 4 and the spec.

Source origin

repository declares where the app's source lives, with an optional #ref fragment pinning the baseline revision:

repository: https://github.com/acme/my-app#v2.1.0

Host capabilities

Apps that need privileged host access — the Docker socket, the host network, the host filesystem — declare it as a host:-marked entry in requires or supports. The provider grants the capability or refuses the deployment; nothing degrades silently:

requires:
  - host: { container_runtime: docker }
    set_env:
      DOCKER_HOST: $url

Multi-component apps

For apps with multiple services (e.g., a backend API + a frontend), use the components map:

name: my-platform
components:
  api:
    runtime: node
    provides:
      - protocol: http
        port: 3000
    requires: [postgres]
    commands:
      start: "node api.js"
  web:
    runtime: node
    depends_on:
      - component: api
        condition: healthy
    provides:
      - protocol: http
        port: 3001
        exposed: true

Learn more

This guide covers the basics. For the full field reference, see the specification. For real-world patterns, browse the examples.