ImageBuilder¶

class baseten.sandbox.ImageBuilder¶

Bases: object

An image described as a Dockerfile and the files it copies in.

Push it with ImageClient.push(). Start one with ImageBuilder.from_registry().

A builder never changes: each method returns a new builder with the instruction appended, so one builder can safely be the base of several. Invalid input raises ValueError at the call that takes it.

The Dockerfile it pushes ends by copying in the sandbox API binary and making it the entrypoint, unless the builder already did either, since a sandbox needs it running to be reached. dockerfile() shows the Dockerfile exactly as pushed.

Parameters:: state (_BuilderState)

add_file(destination, content, *, context_name=None, mode=420)¶

Add a file with the given content to the build context and append COPY ["<name>", "<destination>"].

The name is the file’s name in the context.

Parameters:

destination (str) – Path of the file in the image.
content (str | bytes) – Content of the file. A string is written as UTF-8.
context_name (str | None) – Name in the build context. Defaults to the destination’s basename, with a suffix such as `` (1)`` if another entry already has that name.
mode (int) – Unix permission bits of the file in the image.

Return type:

ImageBuilder

add_local_dir(source_path, destination, *, context_name=None)¶

Add a local directory to the build context and append COPY ["<name>", "<destination>"].

The name is the directory’s name in the context. As with any COPY of a directory, its contents are copied into the destination, not the directory itself. It is read when pushed, with files keeping their permissions, a link to a file within the directory stored as a copy of the file, a link to a file outside it failing the push, and a link to a directory stored as an empty directory. Everything in it is added: no .dockerignore or default ignore rules apply.

Parameters:

source_path (str) – Local directory to add.
destination (str) – Path to copy its contents to in the image.
context_name (str | None) – Name in the build context. Defaults to the source’s basename, with a suffix such as `` (1)`` if another entry already has that name.

Return type:

ImageBuilder

add_local_file(source_path, destination, *, context_name=None)¶

Add a local file to the build context and append COPY ["<name>", "<destination>"].

The name is the file’s name in the context. The file is read when pushed, keeping its permissions, and a symbolic link is read as the file it points to.

Parameters:

source_path (str) – Local file to add.
destination (str) – Path to copy it to in the image.
context_name (str | None) – Name in the build context. Defaults to the source’s basename, with a suffix such as `` (1)`` if another entry already has that name.

Return type:

ImageBuilder

apk_add(*args)¶

Append RUN apk add --no-cache <args>.

Parameters:: args (str)
Return type:: ImageBuilder

apt_install(*args)¶

Append an apt-get install of the packages as one step.

The step is RUN apt-get update && apt-get install -y --no-install-recommends <args> && rm -rf /var/lib/apt/lists/*, so the package lists add nothing to the image.

Parameters:: args (str)
Return type:: ImageBuilder

arg(name, default=None)¶

Append ARG <name>, or ARG <name>="<default>" escaped as in env().

Parameters:

name (str)
default (str | None)

Return type:

ImageBuilder

property base_image: str¶: The image this builder starts from.

cargo_install(*args)¶

Append RUN cargo install <args>.

Parameters:: args (str)
Return type:: ImageBuilder

composer_install(*args)¶

Append RUN composer require <args>.

Parameters:: args (str)
Return type:: ImageBuilder

copy(source, destination)¶

Append COPY ["<source>", "<destination>"], copying from the build context.

Parameters:

source (str)
destination (str)

Return type:

ImageBuilder

dockerfile()¶

Give the Dockerfile, exactly as it is pushed.

Return type:: str

dockerfile_lines(*lines)¶

Append each line verbatim.

For anything the other methods do not cover, such as comments, CMD, or a heredoc. A line may contain newlines, and nothing is checked or escaped.

Parameters:: lines (str)
Return type:: ImageBuilder

entrypoint(*args)¶

Append ENTRYPOINT ["<arg>", ...], in exec form.

The image then runs this instead of the sandbox API binary, so it must start that itself for the sandbox to be reachable.

Parameters:: args (str)
Return type:: ImageBuilder

env(variables)¶

Append ENV <name>="<value>" for each variable.

" and \ in the value are escaped. $ is left as is, so the build expands variables in it, as in {"PATH": "/opt/bin:$PATH"}.

Parameters:: variables (Mapping[str, str])
Return type:: ImageBuilder

expose(*ports)¶

Append EXPOSE <port> for each port.

Parameters:: ports (int)
Return type:: ImageBuilder

classmethod from_registry(base_image, *, sandbox_api_image=None)¶

Start a builder from a registry image, as FROM <base_image>.

Parameters:

base_image (str) – Registry image to start from.
sandbox_api_image (str | None) – Image to copy the sandbox API binary from, when the Dockerfile does not bring it in itself. Defaults to ghcr.io/blaxel-ai/sandbox:latest.

Return type:

ImageBuilder

gem_install(*args)¶

Append RUN gem install --no-document <args>.

Parameters:: args (str)
Return type:: ImageBuilder

go_install(*packages)¶

Append RUN go install <package> && go install <package> ....

One go install per package, since one call can only install packages from a single module.

Parameters:: packages (str)
Return type:: ImageBuilder

label(labels)¶

Append LABEL <key>="<value>" for each label, escaped as in env().

Parameters:: labels (Mapping[str, str])
Return type:: ImageBuilder

npm_install(*args)¶

Append RUN npm install <args>.

With no arguments, appends RUN npm install, to install from the working directory’s package.json.

Parameters:: args (str)
Return type:: ImageBuilder

pip_install(*args)¶

Append RUN pip install <args>.

Parameters:: args (str)
Return type:: ImageBuilder

pipx_install(*packages)¶

Append RUN pipx install <package> && pipx install <package> ..., one per package.

Parameters:: packages (str)
Return type:: ImageBuilder

run_commands(*commands)¶

Append RUN <command> for each command, in shell form.

Parameters:: commands (str)
Return type:: ImageBuilder

user(user)¶

Append USER <user>.

Parameters:: user (str)
Return type:: ImageBuilder

uv_install(*args)¶

Append RUN uv pip install --system <args>.

Parameters:: args (str)
Return type:: ImageBuilder

workdir(path)¶

Append WORKDIR <path>.

Parameters:: path (str)
Return type:: ImageBuilder