Images
GET /containers returns the imageCatalog deployed and available to your account. Select a returned ID when creating a container; an omitted body uses the default Node image.
POST /containers
Content-Type: application/json
Authorization: Bearer mb_<your-key>
Idempotency-Key: <unique-operation-key>
{"catalogId":"python"}
Catalog IDs can include node, python, rust, go, and devops. Use only images advertised by the deployment; a catalog definition alone does not mean an image is available. Image selection does not change resource sizes or deadlines.
Custom images
First read GET /images for buildsEnabled, limits, and usage. When enabled, send a multipart POST with name, a text dockerfile, and an optional context file.
FROM mainbrella:base
RUN mkdir -p /workspace
WORKDIR /workspace
Use one build stage starting with FROM mainbrella:base. Dockerfiles are limited to 16 KiB; optional .tar.gz context to 512 KiB. Retain /bin/sh and GNU coreutils from the base image for execution and file operations.
| Request | Result |
|---|---|
POST /images | 202 with an image record. Build status progresses through queued, building, publishing, ready, or failed. |
GET /images/{id} | The owned image and its build status. |
GET /images/{id}/logs | Logs and status for that build. |
DELETE /images/{id} | Deletes an owned image; active builds cannot be deleted. Running containers remain. |
Launch only once the image is ready, using {"imageId":"…"} instead of catalogId. Inspect build logs when a build fails. Current defaults are ten builds per UTC month, three saved images, and a 300-second build deadline; always use the limits returned by the API.
Versions and tags
Each successful build has an immutable image ID and digest. The source API adds owner-scoped tags: PUT /images/tags/{tag} with {"imageId":"…"}, GET /images/tags/{tag} to resolve it, and DELETE to remove the tag. Tags move; pin the resolved image ID when creating a sandbox so retries use the same version. These routes require migration and deployment.
The source JS/Python SDKs expose image builds, status, logs, deletion and tags through client.images. Build admission remains conditional on images.customBuilds; tags do not enable builds.
Cache reuse and private bases
Source build options accept cacheFrom, an owned ready image ID, and baseImage, a JSON object containing a digest-pinned ghcr.io or docker.io image reference and optional username/password. The Dockerfile still begins with FROM mainbrella:base. New builds export cache metadata; older images may have no reusable cache. The selected base must retain Mainbrella's shell and GNU tooling.
Check privateRegistriesEnabled from GET /images before authenticated imports. Credentials are used once during trusted image preparation and are absent from customer build artifacts. Builds require an operator-configured private build repository. These additions need migration, configuration and live qualification. See the JavaScript and Python build options.