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 run is one execution of a prompt inside a sandbox. Each run has:
  • A sandbox (the Docker image the agent runs on)
  • A harness + model (the agent framework and LLM)
  • A prompt (instructions for the agent)

​
Create a run

from trelent_agents import Client, ClaudeCodeHarnessSpec

client = Client(client_id="...", client_secret="...")

run = client.runs.create(
    sandbox="translator:latest",
    harness=ClaudeCodeHarnessSpec(model="claude-sonnet-4-6"),
    prompt="Translate 'Hello world' to Spanish.",
)
harness is optional — it defaults to ClaudeCodeHarnessSpec(). See Harnesses.

​
Timeout

Runs have a default timeout of 1 hour. Override with timeout_seconds (min 60, max 86400): 
run = client.runs.create(
    sandbox="translator:latest",
    prompt="...",
    timeout_seconds=600,
)

​
Get a run

run = client.runs.get("run_1234567890")

​
List runs

runs = client.runs.list()
runs = client.runs.list(sandbox="translator:latest")

​
Poll for completion

while run.status not in ("completed", "failed", "cancelled"):
    run.refresh()

​
Run status

A run’s status is one of:
StatusMeaning
pendingQueued, not yet running
runningActively executing
completedFinished successfully
failedFinished with an error (see run.error)
timeoutExceeded timeout_seconds
cancelledCancelled via client.runs.cancel(...)

​
Get the result

Once run.status is "completed", the final response is available at run.result.output: 
print(run.result.output)
# => "Hola, mundo."

​
Cancel a run

client.runs.cancel(run.id)