---
url: https://cubesandbox.com/guide/template-aliases.md
---
# 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`:

```python
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:

```bash
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:

```python
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:

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

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

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

Clear the alias:

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

The SDKs expose the same operation:

::: code-group

```python [Python]
from cubesandbox import Template

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

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

```ts [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:

::: code-group

```python [Python]
sandbox = Sandbox.create(template="python-runtime")
```

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

```ts [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:

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

Example response:

```json
{
  "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.