Tags and metadata

Say what each sandbox is for, and find the ones of one run, one team or one branch.

A sandbox can have tags, words such as run-7f3a or team-infra, and metadata, keys with a value each, such as repo: honzabit/agental. A template can have them too, and every sandbox on it has the template's as well as its own.

• A tag is lowercase letters, digits and hyphens, 1 to 63 characters, not starting or ending with a hyphen. One sent in capitals is kept in lowercase. A sandbox or a template has 30 of its own at most.
• A metadata key is lowercase letters, digits, _, . and -, 1 to 40 characters, starting with a letter or a digit. Keys starting agental. are kept for agental. A value is up to 500 characters. 50 keys of its own at most.
• A sandbox shows its template's tags and its own as tags, and its template's metadata with its own over it as metadata. A key it sets itself wins over its template's. ownTags and ownMetadata are its own alone.
• A change to a template's reaches every sandbox on it at once, running or not. A sandbox put on another template has that template's from then on.
• A fork has its source's own, as they were. A sandbox made from a snapshot has only what its create and its template give it.

Give them as it is made#

curl -X POST https://agental.io/v1/sandboxes \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Idempotency-Key: run-7f3a-a" \
  -H "Content-Type: application/json" \
  -d '{"name":"parallel-a","tags":["run-7f3a","branch-auth"],"metadata":{"repo":"honzabit/agental","branch":"claude/auth-refresh"}}'

POST /v1/templates takes tags and metadata the same way, for every sandbox made from it.

Find the sandboxes with a tag#

curl -X GET "https://agental.io/v1/sandboxes?tag=run-7f3a&metadata[repo]=honzabit/agental" \
  -H "Authorization: Bearer $AGENTAL_API_KEY"

• tag can be sent more than once, and a sandbox is listed when it has every one: ?tag=run-7f3a&tag=claude.
• metadata[key]=value lists the ones with that value for that key, for each key sent.
• A sandbox's template's tags and metadata count as its own here.

Change them#

curl -X PUT https://agental.io/v1/sandboxes/{id}/tags/reviewed \
  -H "Authorization: Bearer $AGENTAL_API_KEY"

curl -X PATCH https://agental.io/v1/sandboxes/{id} \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"branch":"claude/auth-refresh-2","reviewer":null}}'

• PUT …/tags/{tag} adds one tag and DELETE takes it away, leaving the others as they are, so two agents tagging one sandbox at once do not undo each other.
• PATCH with tags puts them in place of its own. With metadata it merges them in: a key with a value is set, a key with null is taken away, and the keys not named are left.
• A template's are changed the same way, at /v1/templates/{id}/tags/{tag} and PATCH /v1/templates/{id}. Its template's tags are taken off a sandbox only on the template.
• A key needs sandbox.update to change a sandbox's, and template.write to change a template's.

From the CLI#

agental create --name parallel-a --tag run-7f3a,branch-auth --meta repo=honzabit/agental
agental list --tag run-7f3a
agental tags sbx_2a9a47e50daec64a add reviewed
agental meta sbx_2a9a47e50daec64a set branch=claude/auth-refresh-2
agental meta sbx_2a9a47e50daec64a unset reviewer
agental template tags claude-code add claude

agental tags <sandbox-id> and agental meta <sandbox-id> with nothing after them show what it has, its template's marked. In the console, a sandbox's and a template's are in their Tags view, and a tag in the Sandboxes list is a link to the sandboxes that have it. Every lifecycle event carries the sandbox's tags and metadata as they were when it was written, and a change to a sandbox's own is the event sandbox.labels_changed; a change to a template's is one template.labels_changed, saying what was added and taken away, and its sandboxes are sent nothing.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]