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.

This guide walks you through building a sandbox, pushing it to the registry, and running an agent against it.
A sandbox defines what tools your agent can use. The agent has built-in tools like read_file, write_file, and bash. Any programs you add to the sandbox become tools the agent can invoke by running commands through bash.

​
Prerequisites

Install Docker and the Trelent SDK: 
# Install Docker: https://docs.docker.com/get-docker/
pip install trelent-agents
You’ll also need Trelent credentials (a client ID and secret). See Authentication.

​
Build the sandbox

A sandbox is a Docker image containing the tools and skills your agent needs.

​
Create the project folder

mkdir translator-agent
cd translator-agent

​
Add a skill

Skills are markdown files that teach the agent what it can do and how. The agent reads these at runtime. 
mkdir skills
Create skills/translate.md: 
# Translate

You can translate text using the `trans` CLI.

## Examples

trans -b en:es "Hello, world"
trans -b es:en "Hola, mundo"

Supported languages: en, es, fr, de, it, pt, ru, zh, ja, ko.

​
Write the Dockerfile

Install the translate-shell CLI and copy in your skills. Create Dockerfile: 
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"]

​
Build and push

Build the image and push it to the Trelent registry. Pushing auto-registers the image as a sandbox.
The image tag must be prefixed with your client ID: <registry-url>/<client-id>/<image-name>:<image-tag>. Pushes without the client-ID prefix are rejected.
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"

# <client-id> prefix 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
When referencing the sandbox in the SDK you drop the registry + client-ID prefix and just use translator:latest. No separate registration step is needed.

​
Create a run

Now that your sandbox is registered, you can create runs against it.

​
Verify your sandbox

Confirm your sandbox appears in the list: 
from trelent_agents import Client

client = Client(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

images = client.images.list()
for image in images:
    print(image.name, image.tags)
# => translator ['latest']

​
Create a run

A run executes a prompt inside your sandbox using a harness (the agent framework) and a model (the underlying LLM). 
from trelent_agents import Client, ClaudeCodeHarnessSpec

client = Client(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

run = client.runs.create(
    sandbox="translator:latest",
    harness=ClaudeCodeHarnessSpec(model="claude-sonnet-4-6"),
    prompt="""
Read /skills/translate.md to learn what tools you have.
Translate "The weather is nice today." to Spanish.
""",
)

print(run.id, run.status)
harness is optional — it defaults to ClaudeCodeHarnessSpec() with claude-sonnet-4-6. See Harnesses for the full list.

​
Get the result

Poll until the run completes, then read the result: 
while run.status not in ("completed", "failed", "cancelled"):
    run.refresh()

print(run.result.output)
# => "El clima está agradable hoy."

​
Next steps