bl deploy
Build, push, and deploy your project to Blaxel
Synopsis
Deploy your Blaxel project to the cloud.
This command packages your code, builds a container image, and deploys it
to your workspace. The deployment process includes:
- Reading configuration from blaxel.toml (or the —config file)
- Packaging source code (respects .blaxelignore)
- Building container image with your runtime and dependencies
- Uploading to Blaxel’s container registry
- Creating or updating the resource in your workspace
- Streaming build and deployment logs (interactive mode)
The command reads its configuration from blaxel.toml, or from the file passed
with —config. By default, it looks for that file in the current directory. Use
-d to specify a subdirectory containing it (useful for monorepo setups).
Use —dockerfile to select a Dockerfile, or set build.dockerfile in blaxel.toml
(the flag wins). Paths are relative to the project 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 and one project per
deploy (use —recursive=false when the config lists child packages). 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 project directory (-d, or the
current directory), and the file must exist and parse. It is uploaded as
blaxel.toml, so the build reads it too. It deploys that one project, so
—config implies —recursive=false. Config files in the same directory share
one build context; give each its own Dockerfile with build.dockerfile.
If the blaxel.toml contains an ‘image’ field pointing to a registry image,
the platform will pull the image and transform it via metamorph before deploying.
For private registries, supply credentials via —registry-cred or —docker-config.
Interactive vs Non-Interactive:
- Interactive (default): Shows live logs and deployment progress with TUI
- Non-interactive (—yes or CI): Runs without interactive UI, suitable for automation.
Returns once the code is submitted: exit 0 means accepted, not deployed.
- Non-interactive with —wait: Waits for this build and rollout (up to —timeout)
and exits 1 with the cause, failing Dockerfile step, a short log tail and a next
command if it fails or times out. Interactive mode always waits.
With —wait and -o json (or yaml), a failure adds resources[].diagnostics (code,
phase, cause, step, source, logTail, next). An unchanged redeploy creates no new revision:
—wait reports that in resources[].note and exits 0. If no build starts within 3
minutes of the upload, —wait stops with DEPLOY_TIMEOUT instead of waiting for —timeout.
Environment Variables and Secrets:
Use -e to load .env files or -s to pass secrets directly via command line.
Secrets are injected into your container at runtime and never stored in images.
Monorepo Support:
Use -d to deploy a specific subdirectory, or -R to recursively deploy
all projects in a monorepo (looks for blaxel.toml in subdirectories).
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