Defining Template

The template builder exposes a chainable API for defining how an image is built: choosing a base image, running commands, copying files, setting environment variables, installing packages, and cloning repositories. In the current SDK shape, use the Novita client as the main entry point. In JavaScript and TypeScript, start with novita.template.new(). In Python, the same builder is available through novita.template.new() as well.

Private registry

To build from an image hosted in a private or cloud registry, pass credentials when selecting the base image. For a generic registry use fromImage / from_image with a username and password; dedicated helpers exist for AWS ECR, Google Container Registry, Oracle Cloud (OCI), and Huawei Cloud SWR.

Registry	Method (JS / Python)	Credentials
Generic (basic auth)	`fromImage` / `from_image`	`username`, `password`
AWS ECR	`fromAWSRegistry` / `from_aws_registry`	`accessKeyId`, `secretAccessKey`, `region`
Google GCR / GAR	`fromGCPRegistry` / `from_gcp_registry`	`serviceAccountJSON` (path, JSON string, or object)
Oracle OCI	`fromOCIRegistry` / `from_oci_registry`	`tenancyOcid`, `userOcid`, `fingerprint`, `privateKey`, `region`
Huawei Cloud SWR	`fromHuaweiCloudRegistry` / `from_huawei_cloud_registry`	`accessKeyId`, `secretAccessKey`, `region`

import { Novita } from 'novita-sandbox'

const novita = new Novita()

// Generic private registry (basic auth)
const template = novita.template.new().fromImage('myregistry.com/team/app:latest', {
  username: process.env.REGISTRY_USERNAME,
  password: process.env.REGISTRY_PASSWORD,
})

// AWS ECR
novita.template.new().fromAWSRegistry('123456789.dkr.ecr.us-west-2.amazonaws.com/app:latest', {
  accessKeyId: 'AKIA...',
  secretAccessKey: '...',
  region: 'us-west-2',
})

import os
from novita_sandbox import Novita

novita = Novita()

# Generic private registry (basic auth)
template = novita.template.new().from_image(
    "myregistry.com/team/app:latest",
    username=os.environ.get("REGISTRY_USERNAME"),
    password=os.environ.get("REGISTRY_PASSWORD"),
)

# AWS ECR
novita.template.new().from_aws_registry(
    "123456789.dkr.ecr.us-west-2.amazonaws.com/app:latest",
    access_key_id="AKIA...",
    secret_access_key="...",
    region="us-west-2",
)

Run command

runCmd / run_cmd runs a shell command during the build. It accepts a single command string or an array/list of commands (joined with &&), and an optional user to run as.

Parameter	Type	Description
`command`	string \| string[]	A command, or a list of commands joined with `&&`
`user` / options.user	string (optional)	User to run the command as (e.g. `root`)

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

template.run_cmd('apt-get update')
template.run_cmd(['pip install numpy', 'pip install pandas'])
template.run_cmd('apt-get install vim', user='root')

Copy files

copy includes local files or directories in the image. src may be a single path or a list of paths; dest is the destination in the template. Options control ownership, permissions, and upload behavior.

Parameter	Type	Description
`src`	path \| path[]	Source file(s) or directory path(s)
`dest`	path	Destination path in the template
`forceUpload` / `force_upload`	boolean (optional)	Force upload even if files are cached
`user`	string (optional)	Owner of the copied files
`mode`	number (optional)	File permissions, e.g. `0o755`
`resolveSymlinks` / `resolve_symlinks`	boolean (optional)	Resolve symlinks while copying

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

template.copy('requirements.txt', '/home/user/')
template.copy(['app.py', 'config.py'], '/app/', mode=0o755)

Set envs

setEnvs / set_envs sets environment variables from a key/value mapping.

Important: Environment variables defined with setEnvs / set_envs are available only during the template build, not at sandbox runtime.

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

template.set_envs({'APP_ENV': 'production', 'PORT': '8000'})

Package setup (pip, npm, bun, apt)

Dedicated helpers wrap common package managers. Each accepts a single package name or a list; when packages are omitted, the language helpers install from the current project (pip install . or package.json).

Method (JS / Python)	Options	Notes
`pipInstall` / `pip_install`	`g` (default true)	Installs globally by default; `g: false` installs with `--user`. No packages → `pip install .`
`npmInstall` / `npm_install`	`g`, `dev`	`g` for global (`-g`), `dev` for dev deps. No packages → installs from package.json
`bunInstall` / `bun_install`	`g`, `dev`	Same as npm but uses `bun`
`aptInstall` / `apt_install`	`noInstallRecommends` / `no_install_recommends`, `fixMissing` / `fix_missing`	Runs `apt-get update` then installs as root; packages are required

template.pipInstall('numpy')
template.pipInstall(['pandas', 'scikit-learn'])
template.pipInstall('numpy', { g: false })
template.pipInstall()

template.npmInstall('express')
template.npmInstall('tsx', { g: true })
template.npmInstall('typescript', { dev: true })

template.bunInstall(['lodash', 'axios'])

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

template.pip_install('numpy')
template.pip_install(['pandas', 'scikit-learn'])
template.pip_install('numpy', g=False)
template.pip_install()

template.npm_install('express')
template.npm_install('tsx', g=True)
template.npm_install('typescript', dev=True)

template.bun_install(['lodash', 'axios'])

template.apt_install(['git', 'curl', 'wget'])
template.apt_install(['vim'], no_install_recommends=True)

Git clone

gitClone / git_clone clones a repository into the image. Only the URL is required; an optional destination path and clone options are supported.

Parameter	Type	Description
`url`	string	Repository URL (required)
`path`	path (optional)	Destination path for the clone
`branch`	string (optional)	Branch to clone (adds `--single-branch`)
`depth`	number (optional)	Shallow-clone depth
`user`	string (optional)	User to run the clone as

Note:gitClone / git_clone has no dedicated auth parameters. For a private repository, embed credentials/token in the URL or set them up via a prior runCmd / setEnvs step.

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' })

template.git_clone('https://github.com/user/repo.git', '/app/repo')
template.git_clone(
    'https://github.com/user/repo.git',
    branch='main',
    depth=1,
)
template.git_clone('https://github.com/user/repo.git', '/app/repo', user='root')

Get started

Model APIs

Novita Sandbox

GPUs

Observability

Resources

Private registry

Run command

Copy files

Set envs

Package setup (pip, npm, bun, apt)

Git clone

​Private registry

​Run command

​Copy files

​Set envs

​Package setup (pip, npm, bun, apt)

​Git clone

Private registry

Run command

Copy files

Set envs

Package setup (pip, npm, bun, apt)

Git clone