Your First Launchfile — Learn Launchfile

What is a Launchfile?

A Launchfile is a single file that describes how to deploy your application. It lives in your project root and is called Launchfile — no extension, just like a Dockerfile or Makefile.

Instead of writing platform-specific configs for every hosting provider, you describe what your app needs and let the provider figure out how to set it up. One file, any platform.

You declare your app's runtime, how to start it, what databases it depends on, what environment variables it expects — and that's it. That single declaration is enough to deploy it.

Build it up

Let's build the smallest source-based Launchfile, one line at a time.

Every Launchfile starts with a name. It follows kebab-case convention.

name: my-app

The runtime declares the language or environment your app runs in — node, python, ruby, go, etc.

name: my-app
runtime: node

Add a start command and you're done. This is a complete, valid Launchfile.

version: launch/v1
name: my-api
runtime: node
commands:
  start: "node server.js"

Or pull a prebuilt image

There's a second path. When you don't have source code to build — you're deploying a third-party app, or something you've already published to a registry — swap the runtime and commands pair for a single image field.

Source-based

name: my-app
runtime: node
commands:
  start: "node server.js"

Prebuilt image

name: my-app
image: ghcr.io/org/my-app:latest

Everything else — env vars, ports, databases, health checks — works the same either way. The only difference is how your code gets into the container. Lesson 7 shows how image, build, and runtime can combine for more advanced cases.

How it works

The basics

The file is called Launchfile (no extension) and lives in your project root — right next to package.json or requirements.txt.

This one file is the complete contract for running your app: the runtime, the start command, any databases or services it needs. You don't write shell scripts or Dockerfiles — you declare what the app needs, and that's enough to deploy it.

The version: launch/v1 line is optional. Your Launchfile works without it, but including it pins the schema version you wrote against — good practice as the spec evolves.

Under the hood

So how does "what your app needs" become a running app? That's the job of a provider.

A provider is the piece that reads your Launchfile and runs your app on a specific kind of infrastructure — there's one for Docker, one for local macOS dev, one for a cloud platform, and so on. Each provider translates the same declarations ("I need Postgres", "expose port 3000") into whatever that infrastructure actually does to deliver them.

That's the whole point of describing your app instead of scripting a deploy: one Launchfile runs anywhere, and the provider handles the how. You'll see this idea referenced throughout the course — but you never have to think about a specific provider to write a correct Launchfile.

In the wild

Most catalog apps take the prebuilt path — they're third-party projects distributed as Docker images, not your own source code. CyberChef is a simple example: just an image, a port, and a restart policy.

cyberchef/LaunchfileView on GitHub

version: launch/v1
name: cyberchef
description: "Web app for data encoding, decoding, encryption, and analysis"
repository: https://github.com/gchq/CyberChef
logo: https://raw.githubusercontent.com/gchq/CyberChef/master/src/web/static/images/logo/cyberchef.svg

image: ghcr.io/gchq/cyberchef:latest
provides:
  - protocol: http
    port: 8080
    exposed: true
health: /
restart: always

image:: Instead of building from source, CyberChef uses a prebuilt Docker image.
provides:: Declares an HTTP endpoint on port 8000, exposed to the internet.
restart: always: Declares that the app should be restarted if it crashes.

Try it: npx launchfile up cyberchef to launch this app locally.View in catalog

Check your understanding

What must every Launchfile have at a minimum?

Key takeaways

A Launchfile is a YAML file called Launchfile in your project root.
The minimum is a name plus a way to run your code.
Source-based apps use runtime + commands.start. Prebuilt apps use image.
You describe the what; the infrastructure handles the how (see "Under the hood" above).