A ready image is a starting point, not a saved workspace
Installing the same tools at the start of every task uses part of a short container session. A custom image can move that setup into a build. It gives future machines a prepared starting environment; it does not save the files or processes from an existing machine.
Ask what is available
GET /containers returns the deployed imageCatalog. Select a returned ID such as node or python when creating a container. A runtime name appearing in documentation does not establish that its image has been published in a particular deployment.
For custom builds, start with GET /images. It returns buildsEnabled, account limits, usage, and owned images. An integration should use that response to decide whether it can submit a new build rather than showing a build action that the deployment cannot fulfill.
Build, then launch
The current build contract accepts a multipart name, text Dockerfile, and optional compressed context. The Dockerfile must begin with FROM mainbrella:base, after optional comments, and use one build stage. It is limited to 16 KiB; the optional .tar.gz context is limited to 512 KiB.
FROM mainbrella:base
RUN mkdir -p /workspace
WORKDIR /workspaceThis minimal example creates a working directory. A useful image adds the tools required by the workload while retaining /bin/sh and GNU coreutils, which the execution and file endpoints depend on.
POST /images returns 202 and an image record. The build can progress through queued, building, publishing, and ready, or end in failed. Read the owned image’s status and logs. An accepted build request is not yet a launchable image.
Once the status is ready, send its imageId when creating the container, instead of a catalogId. The two selectors are mutually exclusive. The current default allowance is ten builds per UTC month and three saved images, with a 300-second build deadline; the API’s returned limits govern the account.
Keep results outside the image lifecycle
A custom image does not change the machine’s CPU, memory, disk, or plan deadlines. Files written by a running task still disappear after stop. Deleting an owned image leaves its already-running containers in place, and an active build cannot be deleted.
Keep the environment definition and durable task results separately. The image describes what a new workspace starts with. The files exported by the agent describe what the task produced.
Request details: Images and API reference. The agent setup workflow selects available runtimes and verifies command execution and binary file transfer before cleanup.