bl push
Build and push a container image to the Blaxel registry
Synopsis
Build and push a container image to the Blaxel registry without creating a deployment.
This command packages your code, uploads it, and builds a container image that
is stored in the workspace registry. Unlike ‘bl deploy’, this command does NOT
create or update any resource (agent, function, sandbox, or job).
The process includes:
- Reading configuration from blaxel.toml (or the —config file)
- Packaging source code (respects .blaxelignore)
- Uploading to Blaxel’s build system via presigned URL
- Building container image
- Streaming build logs until the image is ready
If the blaxel.toml contains an ‘image’ field pointing to a registry image
(e.g. docker.io/myorg/myapp:latest), the platform will pull the image and
transform it for the target runtime via metamorph. If the same image was
already built, the build is triggered again by default. Use —skip-build to
skip the build if the image was already built.
Use —memory and —volume (MiB) to size the temporary build or import worker.
These flags override [build].memoryMb and [build].volumeMb in blaxel.toml.
Omitting both uses project settings or platform defaults; —volume 0 requests
memory-backed scratch. These settings do not change runtime resources.
Use —dockerfile to select a Dockerfile, or set build.dockerfile in blaxel.toml
(the flag wins). Paths are relative to the source directory (-d, or the current
directory) and must stay inside it. The build context is unchanged, so COPY paths
are unaffected. A custom Dockerfile needs a source build, not an image import.
It and its adjacent .dockerignore are uploaded even if .blaxelignore excludes them.
Use —config to read a config file other than blaxel.toml, such as
blaxel-v2.toml. The path is relative to the source directory (-d, or the current
directory), and the file must exist and parse. A source build uploads it as
blaxel.toml, so the build reads it too.
For private registries, supply credentials via —registry-cred or —docker-config.
Examples
Options
Options inherited from parent commands
SEE ALSO
- bl - Blaxel CLI - manage and deploy AI agents, sandboxes, and resources
Last modified on November 3, 2026