Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trelent.com/llms.txt

Use this file to discover all available pages before exploring further.

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.