Implementation:Bentoml BentoML Cloud BentoAPI

Knowledge Sources	Bentoml_BentoML
Domains	Cloud, Bento Management, File Transfer
Last Updated	2026-02-13 15:00 GMT

Overview

Implements the BentoAPI class that provides push, pull, list, and get operations for managing Bento packages on the BentoCloud remote store, including multi-part upload support and model dependency handling.

Description

This module provides the high-level API for synchronizing Bento packages between the local bento store and BentoCloud. The BentoAPI class is an immutable attrs frozen class that encapsulates a RestApiClient and a Spinner for progress display. The major operations are:

1. push(bento, force, bare, threads): Pushes a local Bento to BentoCloud. The process involves:
   • Model pushing: First pushes all dependent models concurrently using ThreadPoolExecutor. Handles both BentoML models (with local storage) and HuggingFace models.
   • Repository management: Creates the bento repository on BentoCloud if it does not exist.
   • Upload status checking: Skips upload if the bento already exists remotely with success status (unless force=True).
   • Bare mode: When bare=True, only pushes the manifest without the archive (for development).
   • Transmission strategy selection: Supports three strategies:
     • "proxy": Direct upload through the BentoCloud API.
     • "presigned_url": Upload to a pre-signed URL (e.g., S3).
     • Multi-part upload: For large bentos, splits the tar archive into chunks uploaded concurrently with retry logic (UPLOAD_RETRY_COUNT attempts per chunk). Completes with an ETag-based confirmation.
   • Tar creation: Creates a tar archive of the bento directory, excluding the ./models subdirectory (since models are pushed separately).
   • Progress tracking: Uses Rich progress bars to display upload progress.

1. pull(tag, force, with_models, bento_store): Pulls a Bento from BentoCloud to the local store.
   • Checks local store first; returns existing bento unless force=True.
   • Supports both proxy download and pre-signed URL download.
   • Downloads as a tar archive, extracts to a temporary directory, and saves to the local bento store.
   • Optionally resolves and downloads all model dependencies when with_models=True.

1. list(): Lists all bentos in the remote store, sorted by creation date (newest first).

1. get(name, version): Retrieves a specific bento by name and version. When version is None or "latest", returns the most recent version.

The module uses dependency injection via simple_di (@inject decorator) to resolve BentoMLContainer.tmp_bento_store_dir and BentoMLContainer.bento_store.

Usage

This class is used internally by the BentoML CLI and the BentoCloudClient. It is invoked when users run bentoml push, bentoml pull, bentoml.push(), or bentoml.pull().

Code Reference

Source Location

• Repository: Bentoml_BentoML
• File: src/bentoml/_internal/cloud/bento.py
• Lines: 1-584

Signature

@attrs.frozen
class BentoAPI:
    _client: RestApiClient
    spinner: Spinner

    def push(self, bento: Bento, *, force: bool = False, bare: bool = False, threads: int = 10) -> None: ...
    def pull(self, tag: str | Tag, *, force: bool = False, with_models: bool = False, bento_store: BentoStore = ...) -> Bento: ...
    def list(self) -> BentoWithRepositoryListSchema: ...
    def get(self, name: str, version: str | None) -> BentoSchema: ...

Import

from bentoml._internal.cloud.bento import BentoAPI

I/O Contract

Inputs

Name	Type	Required	Description
bento	Bento	Yes (for push)	The local Bento object to push to BentoCloud
tag	str or Tag	Yes (for pull)	Tag identifying the bento to pull (e.g., "my_service:v1")
force	bool	No (default: False)	Force push/pull even if already exists
bare	bool	No (default: False)	Push only manifest without archive (development mode)
threads	int	No (default: 10)	Number of concurrent threads for upload/model push
with_models	bool	No (default: False)	Whether to also pull dependent models
name	str	Yes (for get)	Bento repository name
version	str or None	No	Bento version; None or "latest" returns the most recent

Outputs

Name	Type	Description
(push)	None	Side effect: bento uploaded to BentoCloud
(pull)	Bento	The pulled Bento saved to local store
(list)	BentoWithRepositoryListSchema	List of all remote bentos sorted by creation date
(get)	BentoSchema	Schema for the requested bento

Usage Examples

from bentoml._internal.cloud.bento import BentoAPI
from bentoml._internal.cloud.client import RestApiClient

# Create API instance
rest_client = RestApiClient(endpoint="https://cloud.bentoml.com", api_token="xxx")
bento_api = BentoAPI(client=rest_client)

# Push a bento
bento = bentoml.get("my_service:latest")
bento_api.push(bento, force=True, threads=10)

# Pull a bento
pulled = bento_api.pull("my_service:v1", with_models=True)

# List remote bentos
bentos = bento_api.list()

# Get specific bento info
info = bento_api.get("my_service", "v1")

Related Pages

• Implementation:Bentoml_BentoML_Cloud_RestClient
• Implementation:Bentoml_BentoML_Public_API_Module