Core Concepts

Launchables

View as Markdown

Launchables bundle compute hardware, software environments, and code into one-click deployable packages. Share a link, and anyone can spin up an identical environment.

What are Launchables?

A Launchable is a reproducible, shareable environment configuration. It captures everything needed to run a specific workload:

  • Details: Name and description
  • Default hardware configuration: GPU or CPU instance type, storage, and location
  • Software configuration: Runtime mode, image, setup script, and managed services
  • Source: Git repository, notebook, Markdown file, embedded files, or no attached code
  • Network: Secure links and exposed TCP/UDP ports
  • Launch parameters: Values supplied by each deployer
  • View access: Who can view and deploy the Launchable

Use cases: Tutorials, demos, workshops, team onboarding, reproducing research, and distributing GPU applications.

Creating a Launchable

Create a Launchable in the Brev Console using the Launchable builder. The builder presents the following sections in order.

Details

Enter a required Name and an optional Description. Choose the name carefully; it cannot be changed after the Launchable is created.

Default hardware configuration

Choose the compute configuration that deployers see by default:

  1. Select a GPU or CPU instance type.
  2. Set the Disk Storage (GiB).
  3. Optionally set a default location and, when available, a default sub-location.

Deployers can select another available compute configuration before deployment.

Software configuration

Choose how the Launchable configures its environment:

ModeConfiguration
VM ModeUse a VM with Python, CUDA, and Docker. You can install Jupyter on the host and add a setup script.
Single ContainerProvide a custom Docker image and, optionally, an entrypoint command.
Docker ComposeUpload a local Compose file or provide a GitHub or GitLab URL. You can install Jupyter on the host.
Single-node Kubernetes (Beta)Use a single-node Kubernetes cluster with kubectl and Helm. You can install the Kubernetes Dashboard and add a cluster initialization script.

Source

Choose how to provide code files:

OptionDescription
I don’t have any code filesCreate the environment without an attached code source.
I have code files in a git repositoryProvide a public repository, notebook, or Markdown file URL.
My code files are embedded in my container(s)Use code already included in the selected container or Kubernetes workload. This option is only shown for those runtime modes.

Use Launch parameters for deploy-time values such as API keys, image tags, model IDs, and other configuration. Parameters work with VM setup scripts, single containers, Docker Compose, and Kubernetes cluster initialization scripts.

Network

Configure how deployers access services:

  • Secure Link: Protect an HTTP service with Brev authentication. Specify its name and port, and optionally show it as a call-to-action on the deployment page.
  • TCP/UDP Ports: Expose a port or port range to all IP addresses or only the deployer’s IP address.

When Jupyter or the Kubernetes Dashboard is enabled in Software configuration, its secure link appears here but remains controlled by that earlier section.

Launch parameters

Launch parameters let a Launchable creator define values that each deployer provides when starting the Launchable. Use them for API keys, image tags, model IDs, feature flags, and other configuration that should not be fixed in the Launchable.

Creators configure Launch parameters. Deployers enter the corresponding Setup values before deployment. Brev passes the values as environment variables while the Launchable starts.

Launch parameters are launch-time inputs. They are not persistent, VM-wide environment variables or a replacement for a runtime secret manager.

Add Parameters

1

Open Launch Parameters

Create or edit a Launchable in the Brev Console, complete its runtime configuration, and open Launch parameters.

2

Add a Parameter

Select Add Parameter, then configure:

  • Name: The environment variable name, such as API_KEY or IMAGE_TAG.
  • Description: Guidance shown to deployers.
  • Required: Whether a value must be available before deployment.
  • Type: Text for free-form input or Choice for a predefined list.
  • Choices: The allowed values for a Choice parameter. Add at least one; values must be non-empty and unique.
  • Default: An optional value used when the deployer does not provide another. A Choice default must be one of its allowed values.

Parameter names must be unique within the Launchable. They must use uppercase letters, numbers, and underscores, and must begin with a letter or underscore. Names beginning with BREV_ are reserved.

3

Continue to View Access

Choose who can view and deploy the Launchable, then create it. When someone deploys the finished Launchable, Brev prompts for the configured Setup values.

Do not store reusable credentials as parameter defaults. Define the parameter without a default value and let each deployer supply their own credential.

Deploy with Setup Values

1

Open the Launchable

Open the Launchable’s deployment link and sign in to the Brev Console.

2

Enter Setup Values

In Setup values, enter every required value. Optional values can be left empty.

3

Deploy

Select the compute configuration and deploy the Launchable. Brev passes the supplied values only to the selected startup path.

Use Parameters by Runtime Mode

Parameters are available to the user-defined setup script as environment variables.

This example verifies that an API key was supplied without printing it:

$#!/usr/bin/env bash
$set -euo pipefail
$
$python3 - <<'PY'
$import os
$
$if not os.environ.get("API_KEY"):
$    raise RuntimeError("API_KEY is required")
$
$print("API_KEY is available during setup.")
$# Perform one-time initialization that uses the API key here.
$PY

Commands started by the setup script can read API_KEY from their environment. After setup finishes, the value is not automatically available in a later SSH session, and the setup script does not automatically run again when the VM restarts.

Value Lifetime and Visibility

Runtime modeWhere the value is availableWhat happens after startup
VM ModeUser-defined setup script environmentNot inherited by later SSH sessions or supplied again after a restart unless the script saves or passes the value elsewhere.
Single ContainerContainer environmentStored in the Docker container configuration and retained across that container’s restarts.
Docker ComposeCompose interpolation environment; service environment when explicitly passedCan be materialized in container configuration or other Docker metadata; not supplied again to later Compose runs.
Single-node KubernetesUser-defined cluster initialization script environmentNot inherited by later SSH sessions or added to Kubernetes workloads unless the script saves or passes the value elsewhere.

Free-text Setup values are masked in the Console and encrypted in transit and at rest. Brev never persists plaintext during the control-plane handoff: it keeps only a short-lived encrypted record, deletes it after setup, and expires it within one hour if cleanup fails. The workload receives plaintext at runtime and may persist it.

Brev’s cleanup does not remove copies created by your workload. A value can persist if a script writes it to a file, shell profile, service definition, log, command, or container configuration.

Protect Sensitive Values

  • Do not print credentials with echo, env, or printenv, and do not enable shell tracing with set -x. Setup output is captured in logs.
  • Do not interpolate secrets into image names, labels, or commands. Pass them through the container environment only when the application needs them.
  • Treat anyone with root or administrator access, Docker socket or Docker group access, or access to the receiving process or container as potentially able to read runtime credentials.
  • Use project-scoped credentials with minimum permissions and usage limits.
  • Use a runtime secret manager when an application needs a credential continuously, must rotate it, or must retrieve it again after a restart.

Troubleshooting

ProblemResolution
A required value cannot be submittedEnter a non-empty Setup value before deploying.
The setup script cannot find a parameterCheck that the script uses the exact uppercase parameter name.
A value is missing from a Compose serviceAdd the parameter name under that service’s environment section.
A value is missing after you connect with SSHThis is expected in VM Mode. Setup values are scoped to startup unless your setup deliberately persists them.

View access

Choose who can view and deploy the Launchable:

  • Turn on Publish to community to make the Launchable discoverable by everyone.
  • Leave it off and select Anyone with the link (default) or Only my organization to limit visibility.

After all required sections are complete, select Create Launchable to generate the shareable link.

Runtime Modes

Choose how your Launchable configures the instance environment:

VM Mode

Run directly on the instance. Best for flexible environments and full VM access.

  • Optional Jupyter on the host
  • Optional setup script
  • Python, CUDA, and Docker included
Single Container

Run a custom Docker image. Best for a reproducible application contained in one image.

  • Optional entrypoint command
  • Code can be attached or embedded
Docker Compose

Run a multi-container application from a Compose file.

  • Local file or GitHub/GitLab URL
  • Optional Jupyter on the host
Single-node Kubernetes (Beta)

Run a single-node Kubernetes cluster with kubectl and Helm.

  • Optional Kubernetes Dashboard
  • Optional cluster initialization script
  • Code can be attached or embedded

Exploring Launchables

The Launchables tab in the Brev Console provides a fully indexed, searchable collection of shared launchables. Browse curated picks or search to find GPU environment templates you can deploy with one click.

Browsing

When you open the Explore view within the Launchables tab, the page displays curated sections:

  • Featured: Hand-picked launchables highlighted with a blue badge (up to six shown).
  • Trending This Week: Popular launchables ranked by recent activity (up to three shown, with green rank badges).
  • All Time Popular: Most popular launchables overall (up to six shown, with yellow rank badges).

Each launchable card displays: name, author, description, cost per hour, view count, and deploy count. Click any card to go directly to the deploy page.

A row of cloud provider logos shows available compute backing (AWS, Google Cloud, Crusoe, Lambda, Nebius, Hyperstack, Oracle, and others).

Searching and Filtering

The search bar accepts free-text queries across launchable names, containers, models, workflows, and GPUs. Press Enter or click the search icon to execute.

Two optional filters narrow results further:

FilterDescription
GPU NameFilter by specific GPU type (dynamically populated from available instance types).
Cloud ProviderFilter by cloud provider, such as AWS or GCP.

Changing a filter triggers an immediate search. Active filters appear as dismissible badges below the search bar. Click Clear all to reset and return to the curated browse view.

Results display in a responsive grid with infinite scroll (results load automatically as you scroll).

You can deep-link to filtered results by adding query parameters: ?gpuType=A100 or ?cloud=AWS. This is useful for embedding links in documentation or READMEs that take users directly to relevant launchables.

Sharing and Access Levels

Control who can view and deploy your launchables with three access levels:

Access LevelVisibilityUse Case
Only my organizationOnly members of your organization.Team collaboration, internal tools
Anyone with the linkAnyone with the direct link.Workshops, selective distribution.
Everyone (published)Discoverable by all users in Explore search results.Open-source projects, community resources

Set visibility during creation in the View access section, or change it later from the My Launchables tab. New launchables default to Anyone with the link. To make a launchable discoverable in Explore, turn on Publish to community.

Managing Launchables

All your Launchables display under the Launchables tab. From there, you can:

ActionDescription
View MetricsSee views and deployment counts for each Launchable.
Change AccessChange visibility between Only my organization, Anyone with the link, and Everyone (published). Publishing opens a confirmation; switching away from published shows a warning that the Launchable will no longer display in search results.
PreviewSee the deployment page that users will experience.
Copy Markdown BadgeEmbed a “Launch on Brev” button in READMEs and documentation.
Show ConfigurationView hardware and software details.
DeletePermanently remove a Launchable.

Embedding Launchables

Add a launch badge to any markdown file to let users deploy with one click:

1[![Launch on Brev](https://brev-assets.s3.us-west-1.amazonaws.com/nv-lb-dark.svg)](https://brev.nvidia.com/launchable/deploy?launchableID=your-launchable-id)

What’s Next

Environments

Learn about preconfigured software environments.

Custom Containers

Run Docker workloads with GPU access.