4.4. Squad Template Catalog¶

The Squad Template Catalog lets you discover and install pre-built squad templates published to a GitHub-backed catalog — the same multi-source registry that distributes individual agent profiles. A catalog ships ready-made team recipes (for example, an "Open-source code review crew" or a "Korean translation team") so you can add a fully configured squad without building it from scratch.

Catalog templates are installed locally and then behave exactly like any other user template: you can apply, export, or delete them. Built-in templates remain read-only.

Browsing the catalog¶

Open the Catalog page from the sidebar.
Select the Squad Templates tab.
Each card shows the template's icon, name, category, description, tags, author, version, and the source it came from.

If you have configured more than one registry source, filter chips let you narrow the grid to a single source. Use Refresh to re-fetch the latest index (this bypasses the local cache).

Squad templates and agent profiles are distributed through one shared list of registry sources. Adding, removing, enabling, or disabling a source under Settings → Registry Sources affects both the Community (agents) tab and the Squad Templates tab at once. There is no separate source list for squad templates.

Installing a template¶

Click Install on a card. Backend.AI GO fetches the template JSON from the source, verifies its content (see Content verification), validates its schema version, and writes it under your local squad-templates directory. Once installed:

The card shows Installed instead of Install, plus a verification badge (Verified / Unverified).
The template appears in the template gallery (Squad → New Squad) with a From catalog badge, alongside built-in and locally-created templates.

If a source requires verification and the template has no valid checksum or signature — or a checksum/signature does not match — the install is blocked with a clear error and nothing is written.

Models referenced by installed templates¶

Catalog templates carry each agent's model preferences. If an installed template references a model you do not have locally, that agent automatically falls back to the default model set in Settings → Models — so an installed template is always usable even before you download its preferred models. The Squad Templates tab shows a reminder of this behavior above the grid.

Uninstalling a template¶

A catalog template is a user template once installed, so you remove it the same way you remove any user template:

In the template gallery (Squad → New Squad), use the Delete action on the template card and confirm.

Built-in templates cannot be deleted. Deleting an installed catalog template only removes your local copy; you can re-install it from the catalog at any time.

Publishing a squad template to a catalog¶

Authoring a catalog is a pure data exercise — there is no app release or backend service involved. A catalog is just a GitHub repository served over raw.githubusercontent.com.

1. Author the template JSON¶

Export a squad you have built (Save as template, then Export from the gallery) to get a valid template JSON, or hand-author one following the template JSON schema. Place it at a stable path in your catalog repository, for example:

your-catalog/
├── index.json
├── code-assistants/
│   └── python-expert.json        # an agent profile
└── squad-templates/
    └── code-review-crew.json     # a squad template

The conventional location for squad templates is a top-level squad-templates/ directory, but any relative path works as long as the index points at it.

2. List it in `index.json` with `kind: "squad_template"`¶

The catalog's index.json carries summary entries for both agent profiles and squad templates in one list. Mark each squad-template entry with "kind": "squad_template":

{
  "version": 1,
  "updatedAt": "2026-05-28T00:00:00Z",
  "profiles": [
    {
      "path": "code-assistants/python-expert.json",
      "name": "Python Expert",
      "category": "code_assistant",
      "kind": "agent_profile"
    },
    {
      "path": "squad-templates/code-review-crew.json",
      "name": "Code Review Crew",
      "description": "Security, performance, and style reviewers as one team.",
      "category": "review",
      "author": "your-org",
      "icon": "🔐",
      "tags": ["review", "code-quality"],
      "version": "1.0.0",
      "kind": "squad_template"
    }
  ]
}

The index format is additive and backward-compatible:

An entry without a kind field defaults to agent_profile, so existing agent-only catalogs (such as lablup/agent-catalog) keep working unchanged.
Older app versions that do not understand squad_template still parse new indexes; they simply ignore the kinds they do not handle.

The index entry carries only summary fields for the card display. The full agent roster, prompts, tools, and model preferences live in the template JSON at path, which is fetched only when the user installs.

3. Add your source in the app¶

Open Settings → Registry Sources, add your repository (owner, repo, branch, label), and the app validates that the repo contains a valid index.json. Your squad templates then appear in the Squad Templates tab. Because the source list is shared, your agent profiles (if any) appear in the Community tab from the same source.

Content verification (checksums and signatures)¶

Backend.AI GO can verify the integrity (the bytes were not altered) and, optionally, the authenticity (the bytes were published by a trusted author) of catalog resources before installing them. The same verification path covers both agent profiles and squad templates, so a single scheme protects the whole catalog.

Verification is additive and backward-compatible: existing unsigned catalogs keep working. A source only enforces verification when you turn it on (see Requiring verification per source).

Publishing a verified resource¶

For each resource, record a checksum (and, optionally, a signature) in the catalog index.json entry:

Checksum (integrity). A sha256:<hex> digest of the exact bytes of the resource file the entry points at. Compute it over the file as served:

printf 'sha256:%s\n' "$(sha256sum squad-templates/code-review-crew.json | cut -d' ' -f1)"

Put the result in the entry's checksum field.

Signature (authenticity, optional). A detached Ed25519 signature over the same bytes, base64-encoded, in the entry's signature field. Configure the matching base64 public key as the source's trust anchor in the app (Settings → Registry Sources → Verification settings → Signing public key). When both a signature and a trust anchor are present, the signature is verified; a mismatch blocks the install.

{
  "path": "squad-templates/code-review-crew.json",
  "name": "Code Review Crew",
  "kind": "squad_template",
  "checksum": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "signature": "QmFzZTY0LWVuY29kZWQgRWQyNTUxOSBzaWduYXR1cmU="
}

A resource may carry just a checksum, just a signature, both, or neither.

Requiring verification per source¶

Each source has a Require content verification toggle under Settings → Registry Sources → Verification settings:

Off (default for existing and public GitHub sources). Unsigned resources install, but the app marks them Unverified in the catalog (never a green "Verified" check). A resource that does carry a checksum/signature is still verified, and any mismatch always blocks the install, regardless of this toggle.
On. Every install from this source must pass verification. A resource with no checksum or signature is blocked with a clear, localized error, as is any checksum or signature mismatch.

This is safe by default: a mismatched checksum or signature is never installed, and turning on "Require content verification" is an explicit, per-source administrator action.

What the badges mean¶

After installing, the catalog card shows a verification badge:

Verified — the content's checksum (and signature, when a trust anchor is configured) matched.
Unverified — the resource installed on transport trust alone (no checksum/signature, and the source does not require verification).
Unverified — trusted source — verification is intentionally bypassed because the source is transport-trusted (a self-hosted catalog you fully control over an authenticated transport — see Authenticating to a self-hosted catalog). This bypass is explicit, safe by default, and audit-logged; it is never shown as a green "Verified" check.

Why this matters even though templates are "just config"¶

A squad template is pure configuration (system prompts, tool flags, and model preferences) and cannot execute arbitrary code on import, and installation always re-runs the same content validation and limits as a local import (size caps, agent count, field-length checks) and forces a non-built-in user template. However, configuration is not entirely benign — a tampered system prompt or tool-permission set could nudge an agent toward unsafe behavior, and a typo-squatted or compromised source could serve malicious content over otherwise valid TLS. Verifying integrity (and, ideally, authenticity) closes that gap.

Authenticating to a self-hosted (Go Enterprise) catalog¶

The public lablup/agent-catalog is fetched anonymously over GitHub TLS. An on-premise / self-hosted "Go Enterprise" catalog usually sits behind an access boundary — a bearer token, an API key, mTLS, or a private CA. Backend.AI GO can target such a server and present credentials to it. This applies uniformly to both agent profiles and squad templates, since they share one source list.

Adding a self-hosted source¶

Open Settings → Registry Sources → Add source and turn on Self-hosted catalog server. Instead of owner/repo/branch, enter the server's full base URL (e.g. https://catalog.corp.internal/). After the source is added, expand its Transport authentication panel to configure the rest.

Per-source authentication methods¶

Pick an Authentication method on the source:

None (anonymous) — the default; no credentials sent. Use for open intranet mirrors.
Bearer token — sends Authorization: Bearer <token>.
API key header — sends a configurable header (e.g. X-API-Key: <value>).
Basic auth — sends Authorization: Basic … (username here, password in the keychain).
Client certificate (mTLS) — presents a PEM client identity (certificate + private key) for PKI-based enterprises.

Custom CA and proxy¶

For a server fronted by a corporate private CA, set the source's Custom CA certificate path (a .pem/.crt bundle), or rely on the global Settings → General → Custom CA certificate path. An optional Proxy URL routes the fetch through an egress proxy. There is intentionally no "skip TLS verification" option — always use a proper CA bundle.

Where credentials are stored¶

Per-source secrets (bearer token, API-key value, basic password, mTLS client identity) are stored only in your operating system's keychain (with an encrypted-file fallback in headless mode). They are never written to sources.json, never logged, and never sent back to the UI. The settings panel only shows whether a credential is currently set, and lets you replace or clear it.

The signature-verification bypass for transport-trusted sources¶

An enterprise that fully controls both the catalog server and the transport (mTLS or an authenticated reverse proxy on a private network) may decide that per-resource signatures are redundant. It can run a source with Require content verification turned off ("transport-trusted, unsigned"). This bypass is:

Safe by default — a freshly-added self-hosted source is created with verification required; turning it off is a conscious admin action.
Visible — bypassed installs show "Unverified — trusted source" in the catalog, never a green "Verified" check.
Audit-logged — the bypass is recorded.

The recommended posture is not to bypass: configure the source's signing public key (trust anchor) and keep verification on, so you get both transport authentication and content authenticity.

Securing the catalog endpoint itself¶

A self-hosted catalog is just a static host serving index.json and resource JSON. If you front it with Backend.AI GO's own Management API, note that BGO's inbound auth defaults to open and binding to 0.0.0.0 only warns. The catalog endpoint must enforce its own inbound authentication — a Management-API token, reverse-proxy auth, or a network ACL. Do not leave it world-readable just because it is "internal."

How it works¶

Browsing reuses the shared aggregated registry index, the HTTP fetch + cache layer, and the multi-source storage already used for agent profiles. The only squad-specific pieces are the kind discriminator on index entries, an install handler that lands the template via the squad template storage layer, and the Squad Templates tab. Both the desktop (Tauri) and headless (REST) builds support the full browse-and-install flow; the REST endpoint is POST /api/v1/squad-registry/install.