Bash
Let the model run bash commands in a sandbox through the Messages route, and pay for the seconds it runs.
This page is one helperHelperA tool run for you when a model reaches for it mid-answer: a web search, a page read, a sandbox. Named opendunes:‹name›.More on Helpers →. The list of helpers, and how the charge adds up, sit in Helpers.
1. What it does
The model writes a bash command, OpenDunes runs it in a sandbox that belongs to your account, and the output goes back to the model. It reads the output, then runs another command or answers. Files a command writes stay in the sandbox, where you can read them.
| Type | opendunes:bash |
| Route | /v1/messages |
| A step | one command run |
| Steps | at most 30 a request |
| Bills on | each second of sandbox, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → |
The helper works on /v1/messages and nowhere else. On /v1/chat/completions and /v1/responses, a request that names it is refused with a 400 and nothing runs; Shell is the helper for /v1/responses.
2. Name it in tools
Souk Bot has the model print a short list for a shop's page. The sample allows five steps and prints the model's reply and the charge.
import json
import os
import urllib.request
API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/messages"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "With a command, print the numbers 1 to 5 joined by commas."
body = {
"model": MODEL,
"max_tokens": 1024,
"messages": [{"role": "user", "content": PROMPT}],
"tools": [{"type": "opendunes:bash"}],
"max_tool_calls": 5,
}
request = urllib.request.Request(
ADDRESS,
data=json.dumps(body).encode(),
headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request) as response:
answer = json.load(response)
for block in answer["content"]:
if block["type"] == "text":
print(block["text"])
print(answer["usage"]["cost"])The answer is a 200. The model's commands and their output are blocks in content, and you send none of them back. Name the helper by its type, opendunes:bash; any other spelling of the type is a 400.
The files a command left are read without charge, with an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →: GET /v1/containers/{id}/files lists them, and GET /v1/containers/{id}/files/{file}/content returns one file's bytes. The sandbox's id comes back in the helper's result. Sandbox files shows both.
3. Read what it bills on
One charge, in DA, from your balanceBalanceWhat you can spend, in DA.More on Balance and charges →, the moment the answer ends: the model's tokens and the seconds the sandbox ran. usage.cost carries the whole of it. The Plugins tab of your dashboard's Gateway page lists the helper with its price.
A sandbox bills by the clock, not by the step, so a sandbox has a spend cap. Before the model starts, OpenDunes holds money from your wallet for the words and the answer, and writes the cap into the request.
| Your request | The hold |
|---|---|
names no stop_server_tools_when | writes two conditions: the step count, 30 or your max_tool_calls, and a max_cost equal to half of what the wallet has left after the answer's hold; the helper stops at whichever comes first |
names stop_server_tools_when with a max_cost | holds that cap whole; when the wallet cannot pay it, the answer is a 402 that says what the request needs |
names stop_server_tools_when without a max_cost | keeps your conditions and adds the cap |
A cap is a condition on the request:
{
"stop_server_tools_when": [
{ "type": "step_count_is", "step_count": 8 },
{ "type": "max_cost", "max_cost_in_dollars": 0.05 }
]
}When the steps or the cap run out, the model answers with what it has gathered.
Don't let a command wait on something that may never finish. The sandbox bills each second until a step or the cap stops it.
Name a max_cost when the task has a size you know, and keep max_tool_calls low.