Skip to main content
This guide walks you through building a sandbox, pushing it to the registry, and running an agent.
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

​
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-slim

RUN apt-get update \
    && apt-get install -y translate-shell

COPY skills/ /skills/

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. 
export IMAGE=agents.trelent.com/translator:latest

docker build -t $IMAGE .
docker push $IMAGE

​
Register the sandbox

After pushing, register the sandbox with Trelent so you can create runs against it. 
from trelent_agents import Client

client = Client()

client.sandboxes.register("translator:latest")

​
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()

sandboxes = client.sandboxes.list()
print(sandboxes)
# => ["translator:latest", ...]

​
Create a run

A run executes a prompt inside your sandbox using the model you specify. 
sandbox = "translator:latest"

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

print(run.id, run.status)

​
Get the result

Poll until the run completes, then read the result: 
while run.status != "complete":
    run.refresh()

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

​
Next steps

  • Runs — Learn more about run lifecycle and status
  • Imports & Exports — Move data into and out of runs
  • Forking — Branch work by forking runs