Skip to main content
Blaxel allows workspace admins to share resource images (e.g. sandbox images) across workspaces within the same account. When you share an image, only the metadata record is copied to the target workspace. The underlying storage remains in the source workspace, avoiding duplication and keeping billing simple. This is useful when you operate multiple workspaces (e.g. development, staging, production) and want to reuse the same custom images across them without rebuilding or re-pushing.

​
How it works

When you share an image from workspace A to workspace B:
  1. The image metadata record is copied to workspace B, pointing to the same underlying data in workspace A.
  2. Workspace B can use the shared image to deploy agents, MCP servers, batch jobs, and sandboxes, just like a locally-owned image.
  3. Storage billing stays with workspace A (the source).
  4. When new tags are pushed to the source image, they are automatically propagated to shared workspaces.
Shared images in the consuming workspace display a sourceWorkspace field indicating where the image originates from. In the Blaxel Console, shared images are marked with a badge showing the source workspace name.

​
Prerequisites

  • Both workspaces must belong to the same account.
  • You must be an admin of the source workspace.
  • You must also be an admin of the target workspace.
  • The image must be locally owned in the source workspace. You cannot re-share an image that was already shared to you from another workspace.

​
Share an image

​
Blaxel Console

  1. Navigate to the Images page in the source workspace.
  2. Click the actions menu (three dots) on the image you want to share.
  3. Select Share.
  4. In the popin, select the target workspace from the dropdown (only workspaces in the same account are listed).
  5. Click Share to confirm.
The shared image will immediately appear in the target workspace’s image list.

​
Blaxel CLI

bl share image <resourceType/imageName> --workspace <targetWorkspace>
For example, to share a sandbox image called my-template with the production workspace: 
bl share image sandbox/my-template --workspace production
You cannot share a specific tag. Sharing applies to the entire image (all tags). Tag-qualified references like sandbox/my-template:v1.0 are not accepted.

​
Management API

curl -X POST "https://api.blaxel.ai/v0/images/{resourceType}/{imageName}/share" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{"targetWorkspace": "production"}'

​
List shared workspaces

You can see which workspaces an image is currently shared with.

​
Blaxel Console

On the image detail page, shared workspaces are displayed with the ability to revoke sharing for each one.

​
Management API

curl -X GET "https://api.blaxel.ai/v0/images/{resourceType}/{imageName}/share" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE"

​
Unshare an image

Unsharing removes the metadata record from the target workspace. The image data in the source workspace is not affected.
After unsharing, any deployments in the target workspace that reference the shared image will fail on their next restart or scale-up. Make sure no active deployments depend on the image before unsharing.

​
Blaxel Console

  1. Navigate to the Images page in the source workspace.
  2. Open the image detail page.
  3. In the shared workspaces list, click Unshare next to the target workspace you want to revoke.

​
Blaxel CLI

bl unshare image <resourceType/imageName> --workspace <targetWorkspace>
For example: 
bl unshare image sandbox/my-template --workspace production

​
Management API

curl -X DELETE "https://api.blaxel.ai/v0/images/{resourceType}/{imageName}/share/{targetWorkspace}" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE"

​
Billing

Storage billing is tied to the source workspace. Metering and costs remain with the workspace that originally pushed the image, regardless of how many workspaces it is shared with. The consuming workspace pays nothing for image storage of shared images.

​
Constraints and limitations

  • Same account only: Images can only be shared between workspaces under the same account.
  • No re-sharing: A shared image cannot be re-shared from the consuming workspace to a third workspace. Only the original owner can share.
  • Deletion protection: You cannot delete an image (or individual tags) while it is shared with other workspaces. You must unshare it from all target workspaces first.
  • Whole image only: Sharing applies to the entire image with all its tags. You cannot share individual tags.
  • Admin-only: Both sharing and unsharing require admin permissions on both source and target workspaces.
Last modified on April 13, 2026