Templates / TemplateBase

Class: TemplateBase

Builder for AgentBox sandbox templates, and the entrypoint for the template API.

Exposed as Template, which can be called as a factory.

Extends

ClientFactory

Implements

TemplateFromImage
TemplateBuilder
TemplateFinal

Constructors

Constructor

new TemplateBase(options?): TemplateBase

Parameters

options?

TemplateOptions

Returns

TemplateBase

Overrides

ClientFactory.constructor

Methods

aptInstall()

aptInstall(packages, options?): TemplateBuilder

Install Debian/Ubuntu packages using apt-get.

Parameters

packages

string | string[]

Package name(s)

options?

fixMissing?

boolean

noInstallRecommends?

boolean

Returns

TemplateBuilder

Example

template.aptInstall('vim')
template.aptInstall(['git', 'curl', 'wget'])
template.aptInstall(['vim'], { noInstallRecommends: true })
template.aptInstall(['vim'], { fixMissing: true })

Implementation of

TemplateBuilder.aptInstall

betaDevContainerPrebuild()

betaDevContainerPrebuild(devcontainerDirectory): TemplateBuilder

Prebuild a devcontainer from the specified directory.

Parameters

devcontainerDirectory

string

Path to the devcontainer directory

Returns

TemplateBuilder

Example

template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .betaDevContainerPrebuild('/my-devcontainer')

Implementation of

TemplateBuilder.betaDevContainerPrebuild

betaSetDevContainerStart()

betaSetDevContainerStart(devcontainerDirectory): TemplateFinal

Start a devcontainer from the specified directory.

Parameters

devcontainerDirectory

string

Path to the devcontainer directory

Returns

TemplateFinal

Example

template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .startDevcontainer('/my-devcontainer')

// Prebuild and start
template
 .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
 .betaDevContainerPrebuild('/my-devcontainer')
 // Other instructions...
 .betaSetDevContainerStart('/my-devcontainer')

Implementation of

TemplateBuilder.betaSetDevContainerStart

bunInstall()

bunInstall(packages?, options?): TemplateBuilder

Install Bun packages using bun.

Parameters

packages?

string | string[]

Package name(s) or undefined for package.json

options?

Install options

dev?

boolean

g?

boolean

Returns

TemplateBuilder

Example

template.bunInstall('express')
template.bunInstall(['lodash', 'axios'])
template.bunInstall('tsx', { g: true })
template.bunInstall('typescript', { dev: true })
template.bunInstall()  // Installs from package.json

Implementation of

TemplateBuilder.bunInstall

copy()

copy(src, dest, options?): TemplateBuilder

Copy files or directories into the template.

Parameters

src

PathLike | PathLike[]

Source path(s)

dest

PathLike

Destination path

options?

Copy options

forceUpload?

true

gzip?

boolean

mode?

number

resolveSymlinks?

boolean

user?

string

Returns

TemplateBuilder

Example

template.copy('requirements.txt', '/home/user/')
template.copy(['app.ts', 'config.ts'], '/app/', { mode: 0o755 })

Implementation of

TemplateBuilder.copy

copyItems()

copyItems(items): TemplateBuilder

Copy multiple items with individual options.

Parameters

items

CopyItem[]

Array of copy items

Returns

TemplateBuilder

Example

template.copyItems([
  { src: 'app.ts', dest: '/app/' },
  { src: 'config.ts', dest: '/app/', mode: 0o644 }
])

Implementation of

TemplateBuilder.copyItems

fromAlpineImage()

fromAlpineImage(variant?): TemplateBuilder

Start from an Alpine-based Docker image.

Parameters

variant?

string = '3.24'

Alpine variant (default: '3.24')

Returns

TemplateBuilder

Example

Template().fromAlpineImage('3.24')

Implementation of

TemplateFromImage.fromAlpineImage

fromArchImage()

fromArchImage(variant?): TemplateBuilder

Start from an Arch Linux-based Docker image.

Defaults to latest: Arch is a rolling release and template provisioning runs pacman -Syu, so pinning a tag would not change the built result.

Parameters

variant?

string = 'latest'

Arch Linux variant (default: 'latest')

Returns

TemplateBuilder

Example

Template().fromArchImage('base-devel')

Implementation of

TemplateFromImage.fromArchImage

fromAWSRegistry()

fromAWSRegistry(image, credentials): TemplateBuilder

Start from a Docker image in AWS ECR.

Parameters

image

string

Full ECR image path

credentials

AWS credentials

accessKeyId

string

region

string

secretAccessKey

string

Returns

TemplateBuilder

Example

Template().fromAWSRegistry(
  '123456789.dkr.ecr.us-west-2.amazonaws.com/myimage:latest',
  {
    accessKeyId: 'AKIA...',
    secretAccessKey: '...',
    region: 'us-west-2'
  }
)

Implementation of

TemplateFromImage.fromAWSRegistry

fromBaseImage()

fromBaseImage(): TemplateBuilder

Start from AgentBox's pinned default base image.

Returns

TemplateBuilder

Example

Template().fromBaseImage()

Implementation of

TemplateFromImage.fromBaseImage

fromBunImage()

fromBunImage(variant?): TemplateBuilder

Start from a Bun-based Docker image.

Parameters

variant?

string = 'latest'

Bun variant (default: 'latest')

Returns

TemplateBuilder

Example

Template().fromBunImage('1.3')

Implementation of

TemplateFromImage.fromBunImage

fromDebianImage()

fromDebianImage(variant?): TemplateBuilder

Start from a Debian-based Docker image.

Parameters

variant?

string = 'stable'

Debian variant (default: 'stable')

Returns

TemplateBuilder

Example

Template().fromDebianImage('bookworm')

Implementation of

TemplateFromImage.fromDebianImage

fromDockerfile()

fromDockerfile(dockerfileContentOrPath): TemplateBuilder

Parse a Dockerfile and convert it to Template SDK format.

Parameters

dockerfileContentOrPath

string

Dockerfile content or path

Returns

TemplateBuilder

Example

Template().fromDockerfile('Dockerfile')
Template().fromDockerfile('FROM python:3\nRUN pip install numpy')

Implementation of

TemplateFromImage.fromDockerfile

fromFedoraImage()

fromFedoraImage(variant?): TemplateBuilder

Start from a Fedora-based Docker image.

Parameters

variant?

string = '44'

Fedora variant (default: '44')

Returns

TemplateBuilder

Example

Template().fromFedoraImage('44')

Implementation of

TemplateFromImage.fromFedoraImage

fromGCPRegistry()

fromGCPRegistry(image, credentials): TemplateBuilder

Start from a Docker image in Google Container Registry.

Parameters

image

string

Full GCR/GAR image path

credentials

GCP service account credentials

serviceAccountJSON

string | object

Returns

TemplateBuilder

Example

Template().fromGCPRegistry(
  'gcr.io/myproject/myimage:latest',
  { serviceAccountJSON: 'path/to/service-account.json' }
)

Implementation of

TemplateFromImage.fromGCPRegistry

fromImage()

fromImage(baseImage, credentials?): TemplateBuilder

Start from a custom Docker image.

Parameters

baseImage

string

Docker image name

credentials?

Optional credentials for private registries

password

string

username

string

Returns

TemplateBuilder

Example

Template().fromImage('python:3')

// With credentials (optional)
Template().fromImage('myregistry.com/myimage:latest', {
  username: 'user',
  password: 'pass'
})

Implementation of

TemplateFromImage.fromImage

fromNodeImage()

fromNodeImage(variant?): TemplateBuilder

Start from a Node.js-based Docker image.

Parameters

variant?

string = 'lts'

Node.js variant (default: 'lts')

Returns

TemplateBuilder

Example

Template().fromNodeImage('24')

Implementation of

TemplateFromImage.fromNodeImage

fromPythonImage()

fromPythonImage(version?): TemplateBuilder

Start from a Python-based Docker image.

Parameters

version?

string = '3'

Python version (default: '3')

Returns

TemplateBuilder

Example

Template().fromPythonImage('3')

Implementation of

TemplateFromImage.fromPythonImage

fromTemplate()

fromTemplate(template): TemplateBuilder

Start from an existing AgentBox template.

Parameters

template

string

AgentBox template ID or alias

Returns

TemplateBuilder

Example

Template().fromTemplate('my-base-template')

Implementation of

TemplateFromImage.fromTemplate

fromUbuntuImage()

fromUbuntuImage(variant?): TemplateBuilder

Start from an Ubuntu-based Docker image.

Parameters

variant?

string = 'latest'

Ubuntu variant (default: 'latest')

Returns

TemplateBuilder

Example

Template().fromUbuntuImage('24.04')

Implementation of

TemplateFromImage.fromUbuntuImage

gitClone()

gitClone(url, path?, options?): TemplateBuilder

Clone a Git repository.

Parameters

url

string

Repository URL

path?

PathLike

Optional destination path

options?

Clone options

branch?

string

depth?

number

user?

string

Returns

TemplateBuilder

Example

template.gitClone('https://github.com/user/repo.git', '/app/repo')
template.gitClone('https://github.com/user/repo.git', undefined, {
  branch: 'main',
  depth: 1
})
template.gitClone('https://github.com/user/repo.git', '/app/repo', {
  user: 'root'
})

Implementation of

TemplateBuilder.gitClone

makeDir()

makeDir(path, options?): TemplateBuilder

Create directories.

Parameters

path

PathLike | PathLike[]

Directory path(s)

options?

Directory options

mode?

number

user?

string

Returns

TemplateBuilder

Example

template.makeDir('/app/data', { mode: 0o755 })
template.makeDir(['/app/logs', '/app/cache'])
template.makeDir('/app/data', { mode: 0o755, user: 'root' })

Implementation of

TemplateBuilder.makeDir

makeSymlink()

makeSymlink(src, dest, options?): TemplateBuilder

Create a symbolic link.

Parameters

src

PathLike

Source path (target)

dest

PathLike

Destination path (symlink location)

options?

Symlink options

force?

boolean

user?

string

Returns

TemplateBuilder

Example

template.makeSymlink('/usr/bin/python3', '/usr/bin/python')
template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { user: 'root' })
template.makeSymlink('/usr/bin/python3', '/usr/bin/python', { force: true })

Implementation of

TemplateBuilder.makeSymlink

npmInstall()

npmInstall(packages?, options?): TemplateBuilder

Install Node.js packages using npm.

Parameters

packages?

string | string[]

Package name(s) or undefined for package.json

options?

Install options

dev?

boolean

g?

boolean

Returns

TemplateBuilder

Example

template.npmInstall('express')
template.npmInstall(['lodash', 'axios'])
template.npmInstall('tsx', { g: true })
template.npmInstall('typescript', { dev: true })
template.npmInstall()  // Installs from package.json

Implementation of

TemplateBuilder.npmInstall

pipInstall()

pipInstall(packages?, options?): TemplateBuilder

Install Python packages using pip.

Parameters

packages?

string | string[]

Package name(s) or undefined for current directory

options?

Install options

g?

boolean

Install globally as root (default: true). Set to false for user-only installation with --user flag

Returns

TemplateBuilder

Example

template.pipInstall('numpy')  // Installs globally (default)
template.pipInstall(['pandas', 'scikit-learn'])
template.pipInstall('numpy', { g: false })  // Install for user only
template.pipInstall()  // Installs from current directory

Implementation of

TemplateBuilder.pipInstall

remove()

remove(path, options?): TemplateBuilder

Remove files or directories.

Parameters

path

PathLike | PathLike[]

Path(s) to remove

options?

Remove options

force?

boolean

recursive?

boolean

user?

string

Returns

TemplateBuilder

Example

template.remove('/tmp/cache', { recursive: true, force: true })
template.remove('/tmp/cache', { recursive: true, force: true, user: 'root' })

Implementation of

TemplateBuilder.remove

rename()

rename(src, dest, options?): TemplateBuilder

Rename or move a file or directory.

Parameters

src

PathLike

Source path

dest

PathLike

Destination path

options?

Rename options

force?

boolean

user?

string

Returns

TemplateBuilder

Example

template.rename('/tmp/old.txt', '/tmp/new.txt')
template.rename('/tmp/old.txt', '/tmp/new.txt', { user: 'root' })

Implementation of

TemplateBuilder.rename

runCmd()

Call Signature

runCmd(command, options?): TemplateBuilder

Run a shell command.

Parameters

command

string

Command string

options?

Command options

user?

string

Returns

TemplateBuilder

Example

template.runCmd('apt-get update')
template.runCmd(['pip install numpy', 'pip install pandas'])
template.runCmd('apt-get install vim', { user: 'root' })

Implementation of

TemplateBuilder.runCmd

Call Signature

runCmd(commands, options?): TemplateBuilder

Run multiple shell commands.

Parameters

commands

string[]

Array of command strings

options?

Command options

user?

string

Returns

TemplateBuilder

Implementation of

TemplateBuilder.runCmd

setEnvs()

setEnvs(envs): TemplateBuilder

Set environment variables. Note: Environment variables defined here are available only during template build.

Parameters

envs

Record<string, string>

Environment variables

Returns

TemplateBuilder

Example

template.setEnvs({ NODE_ENV: 'production', PORT: '8080' })

Implementation of

TemplateBuilder.setEnvs

setReadyCmd()

setReadyCmd(readyCommand): TemplateFinal

Set or update the ready check command.

Parameters

readyCommand

string | ReadyCmd

Command to check readiness

Returns

TemplateFinal

Example

// Using a string command
template.setReadyCmd('curl http://localhost:8000/health')

// Using ReadyCmd helpers
import { waitForPort, waitForFile, waitForProcess } from '@abox-dev/sdk'

template.setReadyCmd(waitForPort(3000))

template.setReadyCmd(waitForFile('/tmp/ready'))

template.setReadyCmd(waitForProcess('nginx'))

Implementation of

TemplateBuilder.setReadyCmd

setStartCmd()

setStartCmd(startCommand, readyCommand): TemplateFinal

Set the start command and ready check.

Parameters

startCommand

string

Command to run on startup

readyCommand

string | ReadyCmd

Command to check readiness

Returns

TemplateFinal

Example

// Using a string command
template.setStartCmd(
  'node app.js',
  'curl http://localhost:8000/health'
)

// Using ReadyCmd helpers
import { waitForPort, waitForURL } from '@abox-dev/sdk'

template.setStartCmd(
  'python -m http.server 8000',
  waitForPort(8000)
)

template.setStartCmd(
  'npm start',
  waitForURL('http://localhost:3000/health', 200)
)

Implementation of

TemplateBuilder.setStartCmd

setUser()

setUser(user): TemplateBuilder

Set the user for subsequent commands.

Parameters

user

string

Username

Returns

TemplateBuilder

Example

template.setUser('root')

Implementation of

TemplateBuilder.setUser

setWorkdir()

setWorkdir(workdir): TemplateBuilder

Set the working directory.

Parameters

workdir

PathLike

Working directory path

Returns

TemplateBuilder

Example

template.setWorkdir('/app')

Implementation of

TemplateBuilder.setWorkdir

skipCache()

skipCache(): this

Skip cache for all subsequent build instructions from this point.

Returns

this

Example

Template().skipCache().fromPythonImage('3')

Implementation of

TemplateBuilder.skipCache

assignTags()

static assignTags(targetName, tags, options?): Promise<TemplateTagInfo>

Assign tag(s) to an existing template build.

Parameters

targetName

string

Template name in 'name:tag' format (the source build to tag from)

options?

ConnectionOpts

Authentication options

Returns

Promise<TemplateTagInfo>

Tag info with buildId and assigned tags

Example

// Assign a single tag
await Template.assignTags('my-template:v1.0', 'production')

// Assign multiple tags
await Template.assignTags('my-template:v1.0', ['production', 'stable'])

build()

static build(template, name, options?): Promise<BuildInfo>

Build and deploy a template to AgentBox infrastructure.

Parameters

template

TemplateClass

The template to build

name

string

Template name in 'name' or 'name:tag' format

options?

BuildOptions

Optional build configuration options

Returns

Promise<BuildInfo>

Example

const template = Template().fromPythonImage('3')

// Build with single tag in name
await Template.build(template, 'my-python-env:v1.0')

// Build with multiple tags
await Template.build(template, 'my-python-env', { tags: ['v1.0', 'stable'] })

buildInBackground()

static buildInBackground(template, name, options?): Promise<BuildInfo>

Build and deploy a template to AgentBox infrastructure without waiting for completion.

Parameters

template

TemplateClass

The template to build

name

string

Template name in 'name' or 'name:tag' format

options?

BuildOptions

Optional build configuration options

Returns

Promise<BuildInfo>

Example

const template = Template().fromPythonImage('3')

// Build with single tag in name
const data = await Template.buildInBackground(template, 'my-python-env:v1.0')

// Build with multiple tags
const data = await Template.buildInBackground(template, 'my-python-env', { tags: ['v1.0', 'stable'] })

exists()

static exists(name, options?): Promise<boolean>

Check if a template with the given name exists.

Parameters

name

string

Template name to check

options?

ConnectionOpts

Authentication options

Returns

Promise<boolean>

True if the name exists, false otherwise

Example

const exists = await Template.exists('my-python-env')
if (exists) {
  console.log('Template exists!')
}

getBuildStatus()

static getBuildStatus(data, options?): Promise<TemplateBuildStatusResponse>

Get the status of a build.

Parameters

data

Pick<BuildInfo, "templateId" | "buildId">

Build identifiers

options?

GetBuildStatusOptions

Authentication options

Returns

Promise<TemplateBuildStatusResponse>

Example

const status = await Template.getBuildStatus(data, { logsOffset: 0 })

getTags()

static getTags(templateId, options?): Promise<TemplateTag[]>

Get all tags for a template.

Parameters

templateId

string

Template ID or name

options?

ConnectionOpts

Authentication options

Returns

Promise<TemplateTag[]>

Array of tag details including tag name, buildId, and creation date

Example

const tags = await Template.getTags('my-template')
for (const tag of tags) {
  console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`)
}

removeTags()

static removeTags(name, tags, options?): Promise<void>

Remove tag(s) from a template.

Parameters

name

string

Template name

options?

ConnectionOpts

Authentication options

Returns

Promise<void>

Example

// Remove a single tag
await Template.removeTags('my-template', 'production')

// Remove multiple tags from a template
await Template.removeTags('my-template', ['production', 'staging'])

toDockerfile()

static toDockerfile(template): string

Convert a template to Dockerfile format. Note: Templates based on other AgentBox templates cannot be converted to Dockerfile.

Parameters

template

TemplateClass

The template to convert

Returns

string

Dockerfile string representation

Throws

Error if the template is based on another AgentBox template

toJSON()

static toJSON(template, computeHashes?): Promise<string>

Convert a template to JSON representation.

Parameters

template

TemplateClass

The template to convert

computeHashes?

boolean = true

Whether to compute file hashes for cache invalidation

Returns

Promise<string>

JSON string representation of the template

Class: TemplateBase ​

Extends ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

options? ​

Returns ​

Overrides ​

Methods ​

aptInstall() ​

Parameters ​

packages ​

options? ​

fixMissing? ​

noInstallRecommends? ​

Returns ​

Example ​

Implementation of ​

betaDevContainerPrebuild() ​

Parameters ​

devcontainerDirectory ​

Returns ​

Example ​

Implementation of ​

betaSetDevContainerStart() ​

Parameters ​

devcontainerDirectory ​

Returns ​

Example ​

Implementation of ​

bunInstall() ​

Parameters ​

packages? ​

options? ​

dev? ​

g? ​

Returns ​

Example ​

Implementation of ​

copy() ​

Parameters ​

src ​

dest ​

options? ​

forceUpload? ​

gzip? ​

mode? ​

resolveSymlinks? ​

user? ​

Returns ​

Example ​

Implementation of ​

copyItems() ​

Parameters ​

items ​

Returns ​

Example ​

Implementation of ​

fromAlpineImage() ​

Parameters ​

variant? ​

Returns ​

Example ​

Implementation of ​

fromArchImage() ​

Parameters ​

variant? ​

Returns ​

Example ​

Implementation of ​

fromAWSRegistry() ​

Parameters ​

image ​

credentials ​

accessKeyId ​

region ​

secretAccessKey ​

Returns ​

Example ​

Class: TemplateBase

Extends

Implements

Constructors

Constructor

Parameters

options?

Returns

Overrides

Methods

aptInstall()

Parameters

packages

options?

fixMissing?

noInstallRecommends?

Returns

Example

Implementation of

betaDevContainerPrebuild()

Parameters

devcontainerDirectory

Returns

Example

Implementation of

betaSetDevContainerStart()

Parameters

devcontainerDirectory

Returns

Example

Implementation of

bunInstall()

Parameters

packages?

options?

dev?

g?

Returns

Example

Implementation of

copy()

Parameters

src

dest

options?

forceUpload?

gzip?

mode?

resolveSymlinks?

user?

Returns

Example

Implementation of

copyItems()

Parameters

items

Returns

Example

Implementation of

fromAlpineImage()

Parameters

variant?

Returns

Example

Implementation of

fromArchImage()

Parameters

variant?

Returns

Example

Implementation of

fromAWSRegistry()

Parameters

image

credentials

accessKeyId

region

secretAccessKey

Returns

Example