Docs
⌘K
Templates ›

Rename template

PATCH/v1/templates/{id}

Renames a template, or changes its tags and metadata, or both. A new name changes nothing else. Its tags and metadata are every sandbox's on it, at once, running or not, without a restart: GET /v1/sandboxes/{id} shows them. A key a sandbox sets itself wins over the template's.

RequestTypeScript
  1. import { Agental } from "agental-sdk";
  3. const agental = new Agental();
  4. const template = await agental.templates.get("tpl_0123456789abcdef");
  5. await template.rename("ci-2");
Answer200 OK · Template
  1. {
  2. "id": string,
  3. "name": string,
  4. "default": boolean,
  5. "start": {
  6. "size": "tiny" | "small" | "medium" | "large",
  7. "snapshotId": string | null,
  8. "ttlSeconds": integer | null,
  9. },
  10. "variables": string[],
  11. "hidden": string[],
  12. "files": string[],
  13. "network": {
  14. "outbound": "open" | "blocked" | "allowlist",
  15. "allow": string[],
  16. },
  17. "ssh": {
  18. "enabled": boolean,
  19. "enabledAt": string | null,
  20. "keys": SshKey[],
  21. },
  22. … 6 more
  23. }

Template changed.

Path

idrequired
string
 e.g. "tpl_0123456789abcdef"

Headers

Authorizationrequired
Bearer key
An API key that may make this call.

Body

name
string
Its new name. Left out, it keeps its name.
tags
array of string
Its tags, in place of the ones it has: every sandbox on it has them at once. An empty list removes them. A sandbox's own tags stay. e.g. ["run-7f3a","branch-auth"]
metadata
object
Merged into its metadata: a key with a value is set, a key with null is removed. Every sandbox on it has the change at once, except for a key it sets itself, which stays as it set it. e.g. {"branch":"claude/auth-refresh","ticket":null}

Returns

200 Template changed.

Template15 fields
id
string
name
string
default
boolean
Whether this is the account's default: the template a sandbox is on when none is chosen.
More It cannot be deleted or renamed.
start
TemplateStart3 fields
size
tinysmallmediumlarge
The size a sandbox made from the template is, when the create names none.
snapshotId
stringnull
The snapshot a sandbox made from the template starts as, when the create names none.
More Null starts a new machine.
ttlSeconds
integernull
Seconds a sandbox made from the template runs after each start before it is stopped, when the create names none.
More Null is the deployment's default.
variables
string[]
The names of its variables.
More A value is read one at a time.
hidden
string[]
Of its variables, the ones kept out of the sandbox.
files
string[]
The paths of its secret files.
More Contents are read one at a time.
network
TemplateNetwork2 fields
outbound
openblockedallowlist
What a sandbox on the template may reach outside itself, before its own addresses.
More open is the internet, which is what a sandbox has when nothing is asked. blocked lets nothing out: names still resolve, and no connection leaves. allowlist lets out only what goes to an address in allow. It is enforced outside the sandbox, on the server it runs on, so nothing running in the sandbox can change it, root included. What reaches the sandbox is not affected: commands, files and its public addresses work as before. Whatever this says, no sandbox reaches another sandbox or a private network, or delivers mail on port 25.
allow
string[]
The IPv4 addresses and ranges an allowlist lets out to, over any protocol and port.
More Empty for open and blocked.
ssh
TemplateSsh3 fields
enabled
boolean
Whether a sandbox made from the template has SSH turned on as it is made, as PUT /v1/sandboxes/{id}/ssh would: GET /v1/sandboxes/{id}/ssh then says where to connect.
enabledAt
stringnull
keys
SshKey[]4 fields
The public keys let in to a sandbox's machine as it is made, as POST /v1/sandboxes/{id}/ssh/keys would, in the order they were added.
More At most 50.
id
string
What the key is named by when it is removed: the SHA-256 of the key, written so that it can stand in a path.
fingerprint
string
The same, as ssh-keygen -l prints it.
type
string
comment
stringnull
What follows the key on its line.
More Null when nothing does.
revision
integer
Raised by every change to its variables, files and outbound rule.
More A sandbox that has it at another revision is not up to date with it.
sandboxes
integer
How many sandboxes are on it.
tags
string[]
Tags every sandbox on it has, on top of its own.
More A change reaches them all at once, running or not.
metadata
object
Metadata every sandbox on it has, for the keys it does not set itself.
More A change reaches them all at once, running or not.
createdAt
string
updatedAt
string

Errors and other answers

400invalid_request the name, path or value is not one that can be kept.
400invalid_path the path leads out of the working folder.
404 Not found.
409name_taken the account has a template of that name.
409default_template default keeps its name.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Get templateDelete template →