Celesto custom templates with preinstalled packages

​

How Celesto custom templates work

• A base template. One of the built-in templates, such as coding-agent. Your template starts with the tools the base already includes.
• A build script. Shell commands that install what you need. Celesto runs the script each time it builds the template, not each time a computer starts.

​

Create a custom template and use it

from celesto import Template

template = Template.create(
    name="go-django-env",
    base_template_id="coding-agent",
    build_script="apt-get install -y golang-go\npip install django",
)
print(template.id, template.status)

template.wait(on_log=lambda text: print(text, end=""))

with template.create_computer() as computer:
    print(computer.run("go version").stdout)

from celesto import CloudComputer

with CloudComputer(template_id="tpl_0123456789ab") as computer:
    print(computer.run("go version").stdout)

​

Choose a base template

​

Choose the computer size for a custom template

template = Template.create(
    name="ml-env",
    build_script="pip install torch",
    vcpus=4,
    ram_mb=16384,
    disk_size_mb=61440,
)

​

Write the custom template build script

• The first failing command stops the build. The script runs in strict mode (set -euxo pipefail), so any command that fails ends the build and the error shows its line.
• List packages in the script. The build receives only the script text, so name each package directly, such as pip install django pytest. Commands that read local files, such as pip install -r requirements.txt or ./setup.sh, fail.
• Answer prompts in advance. Use apt-get install -y so apt doesn’t stop to ask yes or no. Celesto runs apt-get update for you before your script starts.
• Install services, start them later. The image keeps installed files, not running programs. Install a service such as PostgreSQL in the script, then start it on the computer when you need it.
• Stay within the limits. A script can be at most 64 KB, and a build can run for at most 30 minutes.

from celesto import Template

warnings = Template.lint("apt-get install golang-go\npip install -r requirements.txt")
for warning in warnings:
    print(f"line {warning.line}: {warning.message}")

line 1: `apt-get install` without `-y` waits for a confirmation that never comes; add `-y`.
line 2: This line references a file, but files can't be uploaded; list the packages directly.

​

Install code from your repositories

template = Template.create(
    name="flask-env",
    build_script=(
        "git clone --depth 1 https://github.com/pallets/flask /opt/app\n"
        "pip install /opt/app"
    ),
)

​

Fix a failed custom template build

from celesto import TemplateBuildError

try:
    template.wait()
except TemplateBuildError as error:
    print(error)                          # line number, exit code, and hint
    if error.failure:                     # None for timeouts and other non-script errors
        print(error.failure.line)         # also: line_number, exit_code, hint
    print(template.logs())                # the end of the build log

template.edit(build_script="apt-get install -y golang-go\npip install django")
template.rebuild().wait(on_log=lambda text: print(text, end=""))

​

Rebuild a custom template on a schedule

import os

from celesto import Template

template = Template.get(os.environ["TEMPLATE_ID"])
template.rebuild().wait()
print(f"{template.id} is {template.status}")

name: Rebuild Celesto template
on:
  schedule:
    - cron: "0 6 * * *" # every day at 06:00 UTC
  workflow_dispatch: # also run it by hand from the Actions tab

jobs:
  rebuild:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -U celesto
      - run: python rebuild_template.py
        env:
          CELESTO_API_KEY: ${{ secrets.CELESTO_API_KEY }}
          TEMPLATE_ID: tpl_0123456789ab

​

Custom templates vs snapshots

​

Manage custom templates

​

Custom template limits and errors

• 2 builds at a time. Each organization can have 2 builds queued or running. Creating or rebuilding a third raises CloudAPIError with status 429 (too many requests). Wait for one to finish, then try again.
• One build per template. Rebuilding while a build is queued or running raises CloudAPIError with status 409 (conflict). Call wait(), then rebuild().
• Unique names. Each name can be used once per organization, and a deleted template’s name is free again. A name already in use raises CloudAPIError with status 409.
• A finished build first. create_computer() needs at least one successful build. While the first build runs, it raises an error that tells you to call wait(). If the first build failed, the error tells you to fix the script and call rebuild().

​

Custom template fields