Skip to main content
POST
Create and start a rebuild

Authorizations

Authorization
string
header
required

API Key or Access Token, always sent as Authorization: Bearer <token>. The gateway recognizes the token type automatically.

Path Parameters

template_id
string<uuid>
required

Owning GMI Template identifier.

Query Parameters

idc_name
string

Filter by data center name, e.g. us-denver-1

Body

application/json
source
object
required

Manual Build source. Sandbox sources use the snapshot endpoint.

default_user
object

Runtime default identity for Sandboxes launched from this Build. Without it, Sandboxes run as docker run would: as the Dockerfile's final USER, else the image's USER, else root, in the final WORKDIR, else the image's, else /. Sandboxes run commands as a named account: an image USER given as a numeric uid (or uid:gid) needs a matching /etc/passwd entry in the image, otherwise the Build fails with a reason that names the USER. The group part is ignored. It is applied after all build commands and overrides the final Dockerfile USER at runtime; it does not change the identity of earlier build commands.

Recommended setup for a custom account: create it in the Dockerfile, give it a working directory it can access, and pass its uid, for example RUN useradd --uid 9999 --create-home --shell /bin/bash app, WORKDIR /home/app, and default_user: {username: app, uid: 9999}.

  • default_user changes the identity only, not the working directory or its permissions. If the account cannot enter the final working directory, commands cannot start there and the Build may fail; declare an accessible WORKDIR to fix it.
  • With uid, the account must already exist with that UID and an existing home directory; otherwise the Build fails. The platform does not change UID, ownership, groups, or sudo privileges.
  • A non-root username without uid may be rejected with HTTP 422 (Template.ProviderNotSupported); supply uid to avoid this. root may omit uid.
  • Invalid username, out-of-range uid, or root with a nonzero uid returns HTTP 400 (Parameter.Invalid).
  • A Build from a base template keeps the base template's user and working directory, as Docker FROM does; set default_user on the child Build to select another. Changing it requires a new Build.

When omitted, the template's default runtime identity is used. A Build response reports the requested setting; an omitted uid stays omitted.

commands
string[]

Shell command strings executed sequentially during the Build. They may run as a non-root account with passwordless sudo: prefix privileged commands with sudo, and set ownership of files that the runtime account must use. To control the build identity explicitly, use a Dockerfile source with USER instructions, as in a regular Dockerfile.

Maximum array length: 100
Required string length: 1 - 8192
envs
object

Environment variables available only during the Template Build. They are visible to subsequent build commands/steps and are not persisted into the resulting template artifact as sandbox runtime environment variables. Pass runtime env when creating a Sandbox instead. Write-only: values are never returned on Template or TemplateBuild responses. Keys must be unique (JSON object); the server orders them deterministically by key. Key names must match [A-Za-z_][A-Za-z0-9_]*.

build_timeout_sec
integer

Wall-clock budget for this Build in seconds. Omit or null to use the platform default (600). Allowed range: 60–3600. On expiry the Build is finalized as error with failure code TemplateBuild.TimedOut, its backing build in the selected IDC is cancelled, and its partial artifacts are reclaimed, best-effort.

Required range: 60 <= x <= 3600
start_cmd
string

Launch command persisted with the Build and applied when Sandboxes created from this Template start.

It runs as a boot script before the sandbox's main process, and the sandbox only becomes ready once it returns, so the command must terminate. A foreground long-running command (sleep infinity, a server started in the foreground) leaves the Sandbox stuck initializing and every exec against it rejected.

Appending & alone is not sufficient: a backgrounded process that still holds the inherited stdout/stderr keeps boot blocked just the same. Long-running processes must be backgrounded and detached from those streams, e.g. my-server > /var/log/my-server.log 2>&1 &.

Resume continues the saved processes without re-running this command.

Required string length: 1 - 8192
file_context
object

Response

The Build record is created and immediately addressable via GET /templates/{template_id}/builds/{id}; build progress is reported by status, not by the status code.

request_id
string
required

HTTP request correlation identifier.

data
object
required