# 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](#1-what-it-does).
2. [Name it in `tools`](#2-name-it-in-tools).
3. [Keep a sandbox between requests](#3-keep-a-sandbox-between-requests).
4. [Read what it bills on](#4-read-what-it-bills-on).

This page is one helper. The list of helpers, and how the charge adds up, sit in [Helpers](/docs/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.

| | |
|---|---|
| Type | `opendunes:shell` |
| Routes | `/v1/responses` and `/v1/messages` |
| A step | one command run |
| Steps | at most 30 a request |
| Bills on | each second of sandbox, in DA |

On `/v1/chat/completions`, a request that names the helper is refused with a `400` and nothing runs. [Bash](/docs/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.

```python
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"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "Add 1200, 450 and 3300 with a command and give me the total.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    input: PROMPT,
    tools: [{ type: "opendunes:shell" }],
    max_tool_calls: 5,
  }),
});
const answer = await response.json();

for (const item of answer.output) {
  if (item.type === "message") console.log(item.content[0].text);
}
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	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."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")
	body, err := json.Marshal(map[string]any{
		"model": model,
		"input": prompt,
		"tools": []map[string]string{
			{"type": "opendunes:shell"},
		},
		"max_tool_calls": 5,
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var answer struct {
		Output []struct {
			Type    string `json:"type"`
			Content []struct {
				Text string `json:"text"`
			} `json:"content"`
		} `json:"output"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	for _, item := range answer.Output {
		if item.Type == "message" {
			fmt.Println(item.Content[0].Text)
		}
	}
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
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."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "input": "'"$PROMPT"'",
    "tools": [
      {
        "type": "opendunes:shell"
      }
    ],
    "max_tool_calls": 5
  }'
```

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 key: `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](/docs/reference/containers) shows both.

## 4. Read what it bills on

One charge, in DA, from your balance, 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 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:

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

<div class="dont">
<p>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.</p>
</div>

<div class="do">
<p>Name a <code>max_cost</code> when the task has a size you know, and ask the model to finish each command quickly.</p>
</div>
