Sandboxes

A sandbox is a Docker image that defines your agent’s environment. The agent has built-in tools: read_file, write_file, and bash. Any programs you add to the sandbox become tools the agent can invoke.

Structure

A typical sandbox includes:

/skills/ — Markdown files describing what the agent can do
CLI tools installed via the Dockerfile
A keep-alive CMD that exits on the shutdown signal

FROM python:3.12-alpine

RUN apk add --no-cache bash curl gawk \
    && curl -sL https://git.io/trans -o /usr/local/bin/trans \
    && chmod +x /usr/local/bin/trans

COPY skills/ /skills/
WORKDIR /workspace

CMD ["sh", "-c", "while true; do if [ -f /shutdown/terminate ]; then exit 0; fi; sleep 1; done"]

The agent reads /skills/ to learn what it can do, then runs tools via bash.

Sandbox images should be based on a shell-friendly distro (Alpine or Debian slim) and must include bash.

Build and push

Image tag format

Every image must be tagged with your client ID as the first path segment. The registry uses this prefix to scope images to your org, and a push without it will be rejected.

The full tag follows this exact shape:

<registry-url>/<client-id>/<image-name>:<image-tag>

For example, if your client ID is acme-corp and you’re pushing a translator image:

registry.trelent.com/acme-corp/translator:latest

When you later reference the sandbox in client.runs.create(sandbox=...), you use just the <image-name>:<image-tag> portion (translator:latest) — the client ID prefix is implied.

Push to the registry

Images are auto-registered as sandboxes on push. Log in to the registry with your client credentials:

export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"

# Note the <client-id> prefix — this is REQUIRED
export IMAGE=registry.trelent.com/$CLIENT_ID/translator:latest

echo "$CLIENT_SECRET" | docker login registry.trelent.com -u "$CLIENT_ID" --password-stdin
docker build -t $IMAGE .
docker push $IMAGE

No separate registration call is needed — pushing the image makes the sandbox available to runs.

List sandboxes

from trelent_agents import Client

client = Client(client_id="...", client_secret="...")

for image in client.images.list():
    print(image.name, image.tags)

Each result is a RegistryImage with a name and a list of tags.

Getting started

Core concepts

Importers

Structure

Build and push

Image tag format

Push to the registry

List sandboxes

​Structure

​Build and push

​Image tag format

​Push to the registry

​List sandboxes

Structure

Build and push

Image tag format

Push to the registry

List sandboxes