Skip to content
Trailer.devDocumentation

Search is only available in production builds. Try building and previewing the site to test it out locally.

Recommendations

The Recommendations page showing the catalog grid of recommendation cards, the server selector, and the search, official, installed, local, type, and sort filters.

Recommendations are small programs that inspect an image or workspace draft and either suggest or automatically apply changes to it. Each recommendation declares a type (image or workspace) and a runtime that holds its match-and-recommend logic.

When a recommendation matches a draft:

  • If auto-apply is on, the change is applied to the draft and reported as an applied result.
  • If auto-apply is off, the recommendation is returned as a suggestion the user can accept or ignore.

The Recommendations page is where administrators browse catalog servers, install recommendations, configure them, and (on self-hosted instances) install local recommendations from disk.

Recommendation types

Section titled “Recommendation types”
TypeApplies to
imageImage drafts
workspaceWorkspace drafts

Runtimes

Section titled “Runtimes”

A recommendation’s logic is loaded from source code in one of three runtimes:

RuntimeValue
Starlarkstarlark
Gogo
WebAssemblywasm

The source is fetched per recommendation. Catalog recommendations are shallow-cloned from a Git tag (the installed version) and pinned to the commit hash recorded at install time. If the tag’s hash later changes, the recommendation fails to load and is disabled automatically.

Browsing the catalog

Section titled “Browsing the catalog”

The list pulls recommendations from a catalog server. The default catalog is https://catalog.trailer.dev. The set of catalog servers is configured on the Settings page. When more than one server is configured, a server selector appears at the top of the list.

Available controls:

  • Search by name, description, or author. When the Local filter is active, search matches the name only.
  • Official: show only recommendations marked official by the catalog.
  • Installed: show only recommendations already installed from the selected server.
  • Local: switch to local recommendations stored on this instance.
  • Type: filter by image or workspace.
  • Sort: by name, author, official, or stars.

Catalog browsing and install actions require administrator access.

Installing and configuring

Section titled “Installing and configuring”

Open a recommendation to reach its configuration page.

For a catalog recommendation:

  • Pick a version from the dropdown to install it. Installing pins the recommendation to that version’s commit hash.
  • Once installed, change the version from the same dropdown, or uninstall it.
  • Deprecated recommendations (no versions available from the catalog) cannot be installed.

Installed recommendations expose:

  • Auto-apply: when on, matches are applied to the draft automatically. When off, matches are returned as suggestions.
  • Enabled: when on, the recommendation is loaded and active. When off, it is unloaded and does not run.
  • Configuration: a YAML editor whose contents are passed to the recommendation’s match and recommend functions. Save to persist changes.

Local recommendations

Section titled “Local recommendations”

On self-hosted (non-cloud) instances, an administrator can install a recommendation directly from the filesystem with the “Install local” action. Local recommendations are read from a file:// URL on the host running the server.

The local recommendation form collects:

  • Name
  • URL (must start with file://, e.g. file:///path/to/recommendation)
  • Runtime (starlark, go, or wasm)
  • Type (image or workspace)
  • Author
  • Version
  • Import (the module path; required for Go recommendations, which are mounted under src/<import>)
  • Auto-apply and Enabled toggles
  • Optional: description, icon URL, and configuration

Local recommendations can be edited in place from the same form and uninstalled from their configuration page. They are loaded from disk only on non-cloud instances.

How matching works

Section titled “How matching works”

When an image or workspace draft is evaluated, the server runs every enabled recommendation of the matching type that has not already been applied or ignored for that draft. Each recommendation’s match function decides whether it applies. Matches are then either applied (auto-apply or explicitly requested) or returned as suggestions, along with any errors from a recommendation that failed to run.

Section titled “Related Pages”