Template Aliases

A template alias is a stable, human-readable name for a CubeSandbox template. Instead of putting a generated ID such as tpl-01abc... in application configuration, you can use a name such as python-runtime:

from cubesandbox import Sandbox

with Sandbox.create(template="python-runtime") as sandbox:
    print(sandbox.commands.run("python3 --version").stdout)

Aliases are useful when a template is rebuilt or replaced. Applications can keep using the stable alias while an operator moves it to the new template.

Rules and behavior

An alias:

• contains only lowercase letters, digits, and hyphens;
• starts with a letter or digit;
• is between 1 and 64 characters;
• must not start with the reserved tpl- or snap- prefix;
• belongs to one READY template at a time;
• cannot be assigned to a snapshot.

Examples of valid aliases are python, python-3-12, and app-v2. Values such as MyApp, my_app, -my-app, and tpl-custom are invalid.

Each template has at most one alias. Assigning an alias that currently belongs to another template transfers it to the target template and clears it from the previous owner. Treat this as a deployment change: existing sandboxes are unaffected, while subsequent operations using the alias resolve to the new template.

Assign an alias while creating a template

Pass --alias when creating a template from an OCI image:

cubemastercli tpl create-from-image \
  --image ghcr.io/example/python-runtime:3.12 \
  --alias python-runtime \
  --writable-layer-size 2G \
  --expose-port 49983 \
  --probe 49983 \
  --probe-path /health

The template ID is still generated by the server. The alias becomes usable after the template reaches READY and claims it successfully.

When using the CubeAPI-compatible SDK template builders, the E2B-style name field is used as the stable alias:

from cubesandbox import Template

job = Template.build(
    image="ghcr.io/example/python-runtime:3.12",
    name="python-runtime",
    writable_layer_size="2G",
    exposed_ports=[49983],
    probe_port=49983,
    probe_path="/health",
)
print(job.template_id)

Set, change, or clear an alias

Set or change an alias on an existing READY template:

cubemastercli tpl set-alias tpl-01abc --alias python-runtime

The first argument may be the generated template ID or its current alias:

cubemastercli tpl set-alias python-runtime --alias python-runtime-v2

Clear the alias:

cubemastercli tpl set-alias tpl-01abc --clear

The SDKs expose the same operation:

Python

from cubesandbox import Template

Template.set_alias("tpl-01abc", "python-runtime")
Template.set_alias("tpl-01abc", None)  # Clear

Go

info, err := client.SetTemplateAlias(ctx, "tpl-01abc", "python-runtime")
if err != nil {
    panic(err)
}
_, err = client.SetTemplateAlias(ctx, info.TemplateID, "") // Clear

Node.js

import { Template } from "@cubesandbox/sdk";

await Template.setAlias("tpl-01abc", "python-runtime");
await Template.setAlias("tpl-01abc", null); // Clear

Use and inspect an alias

An alias can be passed anywhere a template identifier is accepted, including sandbox creation:

Python

sandbox = Sandbox.create(template="python-runtime")

Go

sandbox, err := client.Create(ctx, cubesandbox.CreateOptions{
    TemplateID: "python-runtime",
})

Node.js

const sandbox = await Sandbox.create({ template: "python-runtime" });

Template list and detail responses expose the configured alias in the aliases array. You can also resolve an alias directly through CubeAPI:

curl http://<cubeapi-host>:3000/templates/aliases/python-runtime

Example response:

{
  "templateID": "tpl-01abc",
  "public": false
}

Safe rollout pattern

For a low-risk template update:

1. Build the new template without changing the alias used by production.
2. Wait until the new template is READY and validate it by its generated ID.
3. Assign the production alias to the new template.
4. Create a test sandbox using the alias and verify it resolves as expected.
5. Keep or delete the old template according to your rollback policy.

Changing an alias does not modify or restart sandboxes that already exist.