> ## 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.

# Sandboxes

> Sandboxes define what tools your agent can use.

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

```dockerfile theme={null}
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.

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

## Build and push

### Image tag format

<Warning>
  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.
</Warning>

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:

```bash theme={null}
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

```python theme={null}
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`.