> ## Documentation Index
> Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom bundle

Create a bundle to serve several models as one unit, to configure speculative decoding, or to validate and share a named configuration. A bundle is a reusable, named `ModelBundle` resource that combines one or more model and profile pairs.

Creating a bundle does not serve it. Once the bundle passes validation, deploy it with a `ModelDeployment` as described in [Deploy a bundle](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle).

<Note>
  A bundle is optional. To serve a single model, pair it with a profile and deploy it directly. See [Deploy a single model](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-single-model).
</Note>

## Prerequisites

Before authoring a bundle, complete the quickstart that applies to you:

<CardGroup cols={2}>
  <Card icon="list-check" href="/docs/en/v2.1.1/sambastack/getting-started/hosted" title="Quickstart - Hosted">
    System set up for hosted SambaStack
  </Card>

  <Card icon="list-check" href="/docs/en/v2.1.1/sambastack/getting-started/on-prem" title="Quickstart - On-prem">
    System set up for on-prem SambaStack
  </Card>
</CardGroup>

Additionally:

* Review the [ModelBundle](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model-bundle) field reference, including [model configurations](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model-bundle#model-configurations) and [legalizer results](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model-bundle#legalizer-results).
* Identify the models and profiles to include, and confirm each pair is compatible. See [Identify available models and profiles](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview#identify-available-models-and-profiles).
* Review [Supported models and bundles](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/supported-models-and-bundles) for the available model checkpoints.
* Review [Deploying with speculative decoding](/docs/en/v2.1.1/sambastack/service-administration/performance/deploy-with-speculative-decoding) if you are configuring speculative decoding pairs.

## Create the bundle

<Steps>
  <Step title="Create the YAML file">
    Create a YAML file for your ModelBundle:

    ```yaml theme={}
    apiVersion: sambanova.ai/v1alpha1
    kind: ModelBundle
    metadata:
      name: mb-gpt120
    spec:
      modelConfigs:
      - model: gpt-oss-120b:1
        profile: gpt-oss-fp8-dyt
        batchingConfig:
          8k:
            batch_sizes: [2]
          32k:
            batch_sizes: [2]
          64k:
            batch_sizes: [2]
          128k:
            batch_sizes: [2]
    ```

    For multi-model bundles with speculative decoding, see the [ModelBundle structure](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model-bundle#structure) example.
  </Step>

  <Step title="Apply the ModelBundle">
    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl apply -f <modelbundle-file>.yaml
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> apply -f <modelbundle-file>.yaml
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify legalizer validation">
    The legalizer automatically runs when you apply the bundle and validates whether the configuration fits in RDU memory.

    <Tabs>
      <Tab title="Hosted">
        ```bash theme={}
        kubectl describe modelbundle <bundle-name>
        ```
      </Tab>

      <Tab title="On Premise">
        ```bash theme={}
        kubectl -n <namespace> describe modelbundle.sambanova.ai <bundle-name>
        ```
      </Tab>
    </Tabs>

    <Tabs>
      <Tab title="Successful validation">
        ```text theme={}
        Status:
          Conditions:
            Last Transition Time:  2026-06-22T21:11:05.689262+00:00
            Message:               ModelBundle is Valid
            Observed Generation:   1
            Reason:                ValidationSucceeded
            Status:                True
            Type:                  Valid
        ```
      </Tab>

      <Tab title="Failed validation">
        ```text theme={}
        Status:
          Conditions:
            Last Transition Time:  2026-06-22T21:11:54.975311+00:00
            Message:               <error-details>
            Reason:                ValidationFailed
            Status:                False
            Type:                  Valid
        ```

        The `Message` field contains error details, including legalizer errors if any.
      </Tab>
    </Tabs>

    To read the legalizer result directly, including memory utilization and any warnings:

    ```bash theme={}
    kubectl get modelbundle <bundle-name> -o jsonpath='{.status.legalizerInfo}'
    ```

    For the full status structure and field descriptions, see [Legalizer results](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model-bundle#legalizer-results).
  </Step>
</Steps>

<Warning>
  Do not proceed to deployment until the bundle shows `ValidationSucceeded`.
</Warning>

## Troubleshooting

A bundle is validated by the legalizer before it can be deployed. For the errors and warnings it reports and how to resolve them, see [Legalizer validation failures](/docs/en/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/troubleshooting#legalizer-validation-failures).

## Next steps

<CardGroup cols={2}>
  <Card icon="layer-group" href="/docs/en/v2.1.1/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle" title="Deploy a bundle">
    Serve the bundle you just created
  </Card>

  <Card icon="cube" href="/docs/en/v2.1.1/sambastack/service-administration/model-deployment/custom-resources/model-bundle" title="ModelBundle">
    Full field reference for the bundle resource
  </Card>
</CardGroup>