Build

How to build the template

Build and wait for completion

The build method builds the template and waits for the build to complete. It returns build information including the template ID and build ID.

JavaScript & TypeScript

const buildInfo = await Template.build(template, 'my-template', {
  cpuCount: 2, // CPU cores
  memoryMB: 2048, // Memory in MB
  skipCache: false, // Configure cache skip (except for files)
  onBuildLogs: defaultBuildLogger(), // Log callback receives LogEntry objects
  apiKey: 'your-api-key', // Override API key
  domain: 'your-domain', // Override domain
})

// buildInfo contains: { name, templateId, buildId }

Disk size is not a per-sandbox setting. Unlike cpuCount/cpu_count and memoryMB/memory_mb, there is no disk-size parameter, neither on the template build nor on Sandbox.create. A sandbox’s disk size is determined by your team’s tier limit and applied when the template is built (see Build limits). diskSizeMB only ever appears in API response payloads (for example on sandbox and template info), never as an input. To get a larger disk, raise your tier or contact [e-mail].

Build in background

The buildInBackground method starts the build process and returns immediately without waiting for completion. This is useful when you want to trigger a build and check its status later.

JavaScript & TypeScript

const buildInfo = await Template.buildInBackground(template, 'my-template', {
  cpuCount: 2,
  memoryMB: 2048,
})

// Returns immediately with: { name, templateId, buildId }

Check build status

Use getBuildStatus to check the status of a build started with buildInBackground.

JavaScript & TypeScript

const status = await Template.getBuildStatus(buildInfo, {
  logsOffset: 0, // Optional: offset for fetching logs
})

// status contains: { status: 'building' | 'ready' | 'error', logEntries: [...] }

Example: Background build with status polling

JavaScript & TypeScript

// Start build in background
const buildInfo = await Template.buildInBackground(template, 'my-template', {
  cpuCount: 2,
  memoryMB: 2048,
})

// Poll for build status
let logsOffset = 0
let status = 'building'

while (status === 'building') {
  const buildStatus = await Template.getBuildStatus(buildInfo, {
    logsOffset,
  })

  logsOffset += buildStatus.logEntries.length
  status = buildStatus.status

  buildStatus.logEntries.forEach(
    (logEntry) => console.log(logEntry.toString())
  )

  // Wait for a short period before checking the status again
  await new Promise(resolve => setTimeout(resolve, 2000))
}

if (status === 'ready') {
  console.log('Build completed successfully')
} else {
  console.error('Build failed')
}