> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle.md).

> [!NOTE]
>
> A bundle is optional. To serve a single model, pair it with a profile and deploy it directly. See [Deploy a single model](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-single-model.md).

## Prerequisites

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

> [card] [Quickstart - Hosted](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/getting-started/hosted.md)
>
> System set up for hosted SambaStack

> [card] [Quickstart - On-prem](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/getting-started/on-prem.md)
>
> System set up for on-prem SambaStack

Additionally:

* Review the [ModelBundle](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/custom-resources/model-bundle.md) field reference, including [model configurations](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/custom-resources/model-bundle.md#model-configurations) and [legalizer results](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/custom-resources/model-bundle.md#legalizer-results).
* Identify the models and profiles to include, and confirm each pair is compatible. See [Identify available models and profiles](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/deploying-models-and-bundles/overview#identify-available-models-and-profiles).
* Review [Supported models and bundles](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/supported-models-and-bundles.md) for the available model checkpoints.

## Create the bundle

**1. 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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/custom-resources/model-bundle.md#structure) example.

**2. Apply the ModelBundle**

> [tab] Hosted
>
> ```bash theme={}
> kubectl apply -f <modelbundle-file>.yaml
> ```

> [tab] On Premise
>
> ```bash theme={}
> kubectl -n <namespace> apply -f <modelbundle-file>.yaml
> ```

**3. Verify legalizer validation**

The legalizer automatically runs when you apply the bundle and validates whether the configuration fits in RDU memory.

> [tab] Hosted
>
> ```bash theme={}
> kubectl describe modelbundle <bundle-name>
> ```

> [tab] On Premise
>
> ```bash theme={}
> kubectl -n <namespace> describe modelbundle.sambanova.ai <bundle-name>
> ```

> [tab] 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] 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.

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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/custom-resources/model-bundle.md#legalizer-results).

> [!WARNING]
>
> Do not proceed to deployment until the bundle shows `ValidationSucceeded`.

## 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](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/deploying-models-and-bundles/troubleshooting.md#legalizer-validation-failures).

## Next steps

> [card] [Deploy a bundle](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deploy-a-bundle.md)
>
> Serve the bundle you just created

> [card] [ModelBundle](https://docs.sambanova.ai/docs/en/v2.3.2/sambastack/service-administration/model-deployment/custom-resources/model-bundle.md)
>
> Full field reference for the bundle resource