Mainbrella Launch Manifest

Draft 0.1 · Supported by Mainbrella today

An open YAML recipe to prepare, launch, and preview a public GitHub repository. For developers and AI agents.

Examples

Choose the repository in Run a repository, then paste its YAML at the configuration step.

Static website · Python

Serve MDN’s example website with Python’s built-in HTTP server.

repo: mdn/beginner-html-site-styled
ref: 6c7a360ddb4a0d75be06044bf8a914f260ff10c7
catalogId: python
size: lite
cwd: .
startCommand: |-
  exec python3 -m http.server 8080 --bind 0.0.0.0
port: 8080

Install, build, preview · Node

Build this website using its committed npm lockfile, then serve the result with Vite. Setup finishes before the server starts.

repo: mainbrella/web
ref: 7ea2144684b53795fd03bafb4a5523c867fd5de7
catalogId: node
size: small
cwd: .
setupCommand: |-
  set -Eeuo pipefail
  npm ci
  npm run build
startCommand: |-
  exec ./node_modules/.bin/vite preview --host 0.0.0.0 --port 4173 --strictPort
port: 4173

Terminal only · Go

Open the GitHub CLI source in a Go machine to explore or build from the terminal. Omitting both startCommand and port requests a shell without a web preview.

repo: cli/cli
ref: ec5b512045db67e5a2a4ff4a1b02660b2fb24390
catalogId: go
size: lite

These examples are pinned to source commits and checked against the format. Execution in a Mainbrella machine has not been verified.

Field reference

A manifest is one mapping. Only repo is required. Omit unused fields rather than giving them null or empty values. Unknown fields are rejected.

Mainbrella Launch Manifest draft 0.1 fields
Field	Type / default	Meaning and constraints
`repo`	string · required	Public GitHub repository as `owner/repository`. Owner: 1–39 letters, digits, or hyphens, beginning with a letter or digit. Repository: 1–100 letters, digits, underscores, dots, or hyphens; cannot be `.` or `..`. Mainbrella also accepts GitHub HTTPS URLs on import.
`ref`	string · default branch	Commit, branch, or tag; 1–200 characters without ASCII whitespace or control characters. Prefer a full immutable commit SHA for repeatable launches.
`catalogId`	string · inferred	`node`, `python`, `rust`, `go`, or `devops`. Mainbrella suggests a runtime from manifests in `cwd`; ambiguous projects fall back to Node. This selects a runtime family, not a pinned image version.
`size`	string · `small`	`lite`, `small`, `medium`, `large`, or `xl`. Choose enough memory for installation and builds as well as the running app.
`cwd`	string · `.`	Directory relative to `/workspace/repo`; at most 200 characters. Use `.` or slash-separated names containing letters, digits, underscores, dots, or hyphens, such as `apps/web`. Absolute paths, empty segments, and `.` / `..` path segments are rejected.
`setupCommand`	string · skipped	Bash script to install dependencies and build. Nonempty after trimming; at most 4,096 characters after trimming, with no NUL character. Use a literal block scalar (`\|-`) to preserve newlines.
`startCommand`	string · omitted	Bash script that starts the HTTP server in the foreground. Same string rules as `setupCommand`. Requires `port`.
`port`	integer · omitted	HTTP preview port from 1024 to 65535. Requires `startCommand`. The app must listen on this exact port and bind to `0.0.0.0`.

For a monorepo, set cwd: apps/web when the install and start scripts belong in that directory. If dependencies must be installed at the repository root, explicitly change directories in setupCommand; the start script still begins in cwd.

What a runner does

Validate the mapping, resolve the repository and ref, and select the runtime and size.
Clone the resolved commit to /workspace/repo.
Run setupCommand, when supplied, from cwd. Continue only if it succeeds.
Run startCommand, when supplied, from cwd in a separate Bash process. Keep the server running and check HTTP readiness at / on port.
Provide a terminal and, for a ready HTTP server, an optional preview link.

Setup and start share files, but shell exports and directory changes from setup do not carry into start. Put required environment variables in each script. Use the repository’s lockfile and check its build prerequisites; a runtime selection alone does not guarantee every native compiler or system package.

In Mainbrella, setup has a 15-minute limit and startup checks readiness for about 60 seconds. The server runs in its own tmux session and writes to /workspace/.mainbrella-preview.log. A failed setup or start leaves the terminal available for repair.

Preview links last at most 15 minutes and do not extend the machine’s lifetime. The preview proxy strips cookies and Authorization headers, so cookie sessions and bearer-authenticated apps need another access method. See the full launch contract for platform behavior.

For developers and tool builders

YAML and JSON represent the same data. Use one document with unique keys, scalar strings, and an integer port. YAML aliases and custom tags are unsupported. Comments are welcome; they do not become launch data.

The draft 0.1 JSON Schema validates canonical data: normalize a GitHub URL to owner/repository and trim scripts first. JSON Schema checks the mapping; the YAML parser must also reject duplicate keys, multiple documents, aliases, and unsupported tags. Mainbrella’s parser and validator implement these import rules.

To enable schema hints in a compatible editor, put this comment at the top of your YAML file:

# yaml-language-server: $schema=https://mainbrella.com/schemas/launch-manifest-0.1.json

Save a recipe as mainbrella.yaml if you like, then paste its contents into Mainbrella. Draft 0.1 is a launch request, so it includes repo even when saved inside that repository. Mainbrella does not automatically discover this file.

The version belongs to the specification and schema URL. Do not add schemaVersion or $schema as a mapping field. Changes to this contract will get a new schema version rather than silently changing 0.1.

This is an openly documented Mainbrella format, available for other tools to implement. Mainbrella is its current runner. A repository-owned manifest that references Dockerfiles, Compose services, or Dev Containers is a future extension; those fields are not part of draft 0.1. Existing project definitions can inform the commands you write today.

Keep credentials, tokens, and launch IDs out of recipes. A manifest describes commands to review; importing it does not authorize execution. In Mainbrella, running starts only after you sign in, review the configuration, and choose Run repository.

Run your first repository Set up your agent