Docs · Start

homeport.yaml reference

homeport.yaml is an optional file in your app’s folder that overrides what homeport detects: the build, the output, how your binary is started, a release command and extra processes. Most apps never need one.

The file

It is read from the app’s folder (the repo root unless you chose a folder inside it), and only under the name homeport.yaml. homeport.yml is not read.
It must be a regular file, not a symlink.
Keys it does not know are ignored, so check the spelling of the ones below.
The build settings in the dashboard (install, build, output, run, and binary or static) win over the file.

homeport.yaml

build:
  command: go build -o server ./cmd/api
  artifact: server
run: serve --port $PORT
release: migrate up
processes:
  worker: work --queue default

Every key

homeport.yaml keys
Key	Type	Default	What it does
`build.command`	string	Detected (see Detection)	The build command, run with sh after the install step.
`build.artifact`	path	`server` (rsc-kit: from its marker)	Where the build leaves your binary, relative to the app’s folder.
`build.image`	image reference	Detected	A build image of your own. Needs build.command.
`static`	folder	none	Serve this folder as a static site instead of running a binary.
`run`	string	none	Arguments your binary is started with.
`release`	string	none	Arguments for a one-off run of your binary before each release goes live.
`processes`	map	none	Up to 4 extra long-running processes, such as a queue worker.

build.command

Replaces the detected build command. It runs in /bin/sh after the install step (for example bun install --frozen-lockfile), in the toolchain image homeport picked, or in build.image.

build.artifact

The path of the binary your build produces. Letters, digits, ., _, - and /, and no ... Setting it turns off the fallback that looks for a static site in build, dist or out when no binary appears.

build:
  command: bun build --compile ./src/index.ts --outfile app
  artifact: app

build.image

Builds in an image you name instead of the detected toolchain, for a stack homeport does not detect. It takes precedence over all detection, has no install step, and requires build.command. A plain image reference of up to 255 characters, with an optional tag and @sha256: digest.

build:
  image: rust:1.90
  command: cargo build --release && cp target/release/api server

static

Makes the app a static site served from this folder (it must contain an index.html). Use it when your build writes its site somewhere homeport would not look, or to serve a folder of a plain HTML site.

static: public

run

Arguments added to your binary when it starts: run: serve --port $PORT starts ./server serve --port 8100, say. It is not run through a shell. It may use letters, digits, spaces, . _ : / = @ , + - $ { }, and only two variables, $PORT and $HOST. Ignored for static sites.

release

Arguments for a one-off run of your binary against the new release, before it takes traffic: database migrations, typically. If it fails, the deploy stops and the previous release keeps serving. It has up to 10 minutes.

Write the arguments only: release: migrate up, not ./bin migrate up.
For Laravel the binary is FrankenPHP, and artisan runs through its php-cli: release: php-cli artisan migrate --force.
No shell and no variables: letters, digits, spaces and . _ : / = @ , + - only, so no &&.

processes

Extra processes that run beside your app from the same binary, each with its own arguments. A process is a name and its arguments, or a map with run and optional limits:

processes:
  worker: queue work
  scheduler:
    run: schedule work
    memory: 128M
    cpu: 25%

Process fields
Field	Rule
name	Lowercase letters and digits, starting with a letter, up to 15 characters. Not `web` or `release`.
`run`	Required. Arguments to your binary, with the same rules as release.
`memory`	Optional, like `256M` or `1G`. Not more than the app’s own size.
`cpu`	Optional, like `50%`.

Examples

An rsc-kit site exported as files

Nothing to write: rsc-kit 0.29.6 and newer says it is an export in .output/rsc-kit.json. On an older rsc-kit, say so yourself:

homeport.yaml

static: dist

A Go service whose main package is not at the root

homeport.yaml

build:
  command: CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o server ./cmd/server