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. The provider handles the rest.

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 tells providers what language your app uses — 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.

When you deploy, the provider reads this file and provisions everything: the runtime, the start command, any databases or services you declared. You don't write shell scripts or Dockerfiles — the Launchfile is the contract.

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.

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/Launchfile View 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: 8000
    exposed: true
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: Tells the provider to restart the app 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.
Providers read your Launchfile and handle the infrastructure — you describe the what, they handle the how.