Quickstart

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

Authentication — Manage credentials and profiles
Harnesses — Pick a harness and model for your run
Runs — Learn more about run lifecycle and status
Imports & Exports — Move data into and out of runs
Forking — Branch work by forking runs

Getting started

Core concepts

Importers

Prerequisites

Build the sandbox

Create the project folder

Add a skill

Write the Dockerfile

Build and push

Create a run

Verify your sandbox

Create a run

Get the result

Next steps

​Prerequisites

​Build the sandbox

​Create the project folder

​Add a skill

​Write the Dockerfile

​Build and push

​Create a run

​Verify your sandbox

​Create a run

​Get the result

​Next steps

Prerequisites

Build the sandbox

Create the project folder

Add a skill

Write the Dockerfile

Build and push

Create a run

Verify your sandbox

Create a run

Get the result

Next steps