opendunes
Helpers · 3 min
Copy page ▾

Shell

Let the model run commands in a sandbox in the middle of its answer, and pay for the seconds it runs.

  1. What it does.
  2. Name it in tools.
  3. Keep a sandbox between requests.
  4. Read what it bills on.

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

Typeopendunes:shell
Routes/v1/responses and /v1/messages
A stepone command run
Stepsat most 30 a request
Bills oneach second of sandbox, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →

On /v1/chat/completions, a request that names the helper is refused with a 400 and nothing runs. Bash is the same sandbox in the shape the Messages route expects.

2. Name it in tools

Souk Bot totals a shop's day. The sample asks for a small report, 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/responses"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Add 1200, 450 and 3300 with a command and give me the total."

body = {
    "model": MODEL,
    "input": PROMPT,
    "tools": [{"type": "opendunes:shell"}],
    "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 item in answer["output"]:
    if item["type"] == "message":
        print(item["content"][0]["text"])
print(answer["usage"]["cost"])

The answer is a 200. The model's command and its output are items in output, and you send none of them back. Name the helper by its type, opendunes:shell; any other spelling of the type is a 400.

3. Keep a sandbox between requests

A request without a sandbox gets a new one. To work in the same sandbox again, name it in the helper's parameters:

JSON
{
  "type": "opendunes:shell",
  "parameters": {
    "environment": {
      "type": "container_reference",
      "container_id": "souk-reports"
    }
  }
}

A name is yours alone. Another account that sends the same name gets a sandbox of its own, and a sandbox is never shown to an account that did not make it.

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

4. 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. A command that waits on a slow download or a loop bills every second it waits. 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 requestThe hold
names no stop_server_tools_whenwrites 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_costholds 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_costkeeps your conditions and adds the cap

A cap is a condition on the request:

JSON
{
  "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

Don't leave a command that waits, such as a server that never exits, to the model. The sandbox bills each second until a step or the cap stops it.

Do

Name a max_cost when the task has a size you know, and ask the model to finish each command quickly.