Skip to content

Code Template

GLLM Tools sandbox template builder module.

Exposes the provider-agnostic BaseTemplateBuilder interface and the shared models. Concrete provider builders are imported directly from their modules (e.g. code_template.e2b_template_builder) so that importing this package does not pull in every provider SDK.

RegistryAuth = Annotated[BasicAuth | AwsAuth | GcpAuth, Field(discriminator='type')] module-attribute

Discriminated union of registry credential styles, keyed on the type tag.

Each variant carries exactly its own fields (no not-applicable leftovers) and is validated on construction (e.g. AwsAuth requires region).

AwsAuth

Bases: BaseModel

AWS ECR auth via IAM credentials.

E2B exchanges these for a registry token server-side; other backends translate to a basic login client-side.

Attributes:

Name Type Description
type Literal['aws']

Discriminator tag.
access_key_id str

AWS access key ID (identifier, not secret).
secret_access_key SecretStr

AWS secret access key. Redacted in repr/logs; reveal at the SDK boundary via reveal_secret_key().
region str

ECR region.

reveal_secret_key()

Return the secret access key in plain text (use only at the SDK boundary).

BaseTemplateBuilder

Bases: ABC

Provider-agnostic, build-time companion to BaseSandbox.

Implementations produce a reusable template reference for one sandbox provider. The interface is uniform; the mechanism is delegated to each provider. supports_build makes the asymmetry explicit so callers can branch up front instead of relying on methods that silently do nothing.

provider abstractmethod property

The backend this builder targets; stamped into every TemplateRef.

Returns:

Name Type Description
SandboxProvider SandboxProvider

The provider identifier.

Raises:

Type Description
NotImplementedError

If the property is not implemented in the subclass.

supports_build abstractmethod property

Whether this provider can build templates.

Returns:

Name Type Description
bool bool

True if build() produces a reusable reference (E2B,
bool

OpenSandbox); False if the provider has no template mechanism (Bedrock).

Raises:

Type Description
NotImplementedError

If the property is not implemented in the subclass.

build(spec) abstractmethod

Produce or refresh the template described by spec.

Providers that cannot build return a result with status=UNSUPPORTED and template_ref=None rather than raising.

Parameters:

Name Type Description Default
spec TemplateSpec

Provider-neutral build inputs.

 required

Returns:

Name Type Description
TemplateBuildResult TemplateBuildResult

The structured build outcome.

Raises:

Type Description
NotImplementedError

If the method is not implemented in the subclass.

ensure(spec)

Idempotently ensure the template exists. Never raises.

Flow
  1. Fast path: if not force_rebuild and a usable reference resolves, return SKIPPED.
  2. Otherwise build(spec).
  3. If the build failed (non-forced) but a usable reference now resolves, treat it as SKIPPED (a concurrent builder may have won the race).

Any exception is caught and returned as FAILED so the runtime can fall back to a default sandbox rather than crashing.

Parameters:

Name Type Description Default
spec TemplateSpec

Provider-neutral build inputs.

 required

Returns:

Name Type Description
TemplateBuildResult TemplateBuildResult

The structured outcome (template_ref is
TemplateBuildResult

None only for FAILED/UNSUPPORTED).

is_usable(template_id) abstractmethod

Whether a usable template resolves for template_id.

"Usable" means it can back a sandbox creation — for E2B the alias exists with at least one tag; for OpenSandbox a Ready snapshot of that name exists.

Parameters:

Name Type Description Default
template_id str

The template handle to check.

 required

Returns:

Name Type Description
bool bool

True if the template is usable for sandbox creation.

Raises:

Type Description
NotImplementedError

If the method is not implemented in the subclass.

BasicAuth

Bases: BaseModel

Username/password auth (Docker Hub, GHCR, Harbor, any registry with basic auth).

The only mode OpenSandbox supports natively.

Attributes:

Name Type Description
type Literal['basic']

Discriminator tag.
username str

Registry username (identifier, not secret).
password SecretStr

Registry password or token. Redacted in repr/logs; reveal at the SDK boundary via reveal_password().

reveal_password()

Return the password in plain text (use only at the SDK boundary).

GcpAuth

Bases: BaseModel

GCP Artifact/Container Registry auth via a service-account JSON.

E2B handles the exchange server-side; other backends translate to a basic login.

Attributes:

Name Type Description
type Literal['gcp']

Discriminator tag.
service_account_json SecretStr

Service-account credentials, given as either the JSON content or a filesystem path to the JSON file. Redacted in repr/logs; use resolved_service_account_json() to get the content uniformly regardless of which form was provided.

resolved_service_account_json()

Return the service-account JSON content, reading a file if a path was given.

Returns:

Name Type Description
str str

The JSON content (the value verbatim when it is not a readable path).

SandboxProvider

Bases: str, Enum

Sandbox backend that produced (or would produce) a template reference.

A str enum so it serializes as a plain value ("e2b") across service boundaries and compares to plain strings.

Attributes:

Name Type Description
E2B

E2B backend (reference is an alias).
OPENSANDBOX

OpenSandbox backend (reference is a snapshot name).
BEDROCK

Bedrock AgentCore (no template; never emits a reference).

TemplateBuildResult

Bases: BaseModel

Structured, provider-agnostic result of a template build/ensure.

Attributes:

Name Type Description
status TemplateBuildStatus

Outcome of the operation.
template_ref TemplateRef | None

Self-describing reference to pass to the sandbox-creating service. None for FAILED or UNSUPPORTED.
detail str

Human-readable note (why skipped / unsupported / error head).
stage Stage | None

The failing stage for a FAILED result (typically Stage.TEMPLATE_BUILD), so callers get a structured category instead of a bare detail string. None for non-failure outcomes.
logs str

Build output captured for debugging, when available.

TemplateBuildStatus

Bases: Enum

Outcome of a template build/ensure operation.

Attributes:

Name Type Description
SUCCESS

The template was built and is ready.
SKIPPED

The template was already usable; no rebuild was needed.
UNSUPPORTED

The provider cannot build templates.
FAILED

A build was attempted and failed.

TemplateRef

Bases: BaseModel

Self-describing, serializable reference to a built template.

Produced by a build-time TemplateBuilder and consumed by a (possibly separate) sandbox-creating service. It carries the provider so the consumer can dispatch to the right create() without the original TemplateSpec or builder. Being a plain model, it survives a DB row / message-queue hop between services.

Attributes:

Name Type Description
provider SandboxProvider

Which backend produced the reference.
value str

The provider-native reference — an E2B alias name or an OpenSandbox snapshot name (the stable template_id handle, resolved to a concrete snapshot id at create time). Never a raw snapshot id.

TemplateSpec

Bases: BaseModel

Provider-neutral inputs for building a sandbox template.

The standard input is a container image registry reference (image + optional registry_auth); each builder resolves it to a provider-native reference (E2B alias, OpenSandbox snapshot/image, ...). packages are baked in on top when the provider supports it.

Attributes:

Name Type Description
template_id str

Stable handle for the template (E2B alias name / OpenSandbox snapshot name).
image str | None

Container image registry reference to build from (e.g. "python:3.12" or "123.dkr.ecr.us-west-2.amazonaws.com/img:tag"). This is the standard, preferred input.
registry_auth RegistryAuth | None

Credentials for pulling image from a private registry. None for public images.
packages list[str] | None

pip packages to bake in. Treated as trusted (the caller pre-validates). If None/empty, no install step runs.
start_cmd str | None

Command the sandbox runs at boot (E2B/OpenSandbox do not run the image ENTRYPOINT). When image is set and this is None, the builder defaults to the code-interpreter start command (E2B start command / OpenSandbox DEFAULT_CI_ENTRYPOINT). Ignored by Bedrock.
ready_cmd str | None

E2B-only — shell readiness check paired with start_cmd; defaults to waiting on the code-interpreter port. Ignored by OpenSandbox/Bedrock.
base_template str | None

DEPRECATED — use image. Legacy base to build from (E2B base alias / OpenSandbox base image). Kept for backward compatibility; will be removed.
dockerfile str | None

DEPRECATED — use image. Legacy Dockerfile path/content (honored by E2B, ignored by OpenSandbox). Kept for backward compatibility; will be removed.
force_rebuild bool

Rebuild even if the template already exists.