> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run code in a sandbox

> Your agent pays for an isolated container, with or without a GPU, runs commands in it, and ends it.

Your agent pays BlockRun for an isolated container on Modal, runs commands in it, and ends it. Each step is one paid call, made the same way as any [paid API call](https://docs.anchorage.com/agentic-banking/guides/call-a-paid-api.md). In the catalog, this is BlockRun's **CPU and GPU sandboxes** service.

## Prerequisites

* A budget that allows the merchant BlockRun. The default allow-all budget does.
* A wallet on the rail [Crypto payments](https://docs.anchorage.com/agentic-banking/concepts/payments.md) names for sandboxes.

## Create, run, check, end

Every call is a `POST` with a JSON body. Give each new call its own idempotency key, status checks included. A repeated key usually returns the first call's answer, and on rare occasions asks BlockRun again, which can run a command a second time. See [Idempotency](https://docs.anchorage.com/agentic-banking/concepts/payments.md#idempotency). To retry a failed call, follow [Errors and retries](https://docs.anchorage.com/agentic-banking/reference/errors-and-retries.md).

| Step | Endpoint | Body |
| - | - | - |
| Create | `https://blockrun.ai/api/v1/modal/sandbox/create` | Optionally `image`, `gpu`, `cpu`, `memory`, and `timeout`. Returns a `sandbox_id`. |
| Run a command | `https://blockrun.ai/api/v1/modal/sandbox/exec` | `sandbox_id`, `command`, and optionally `timeout`. |
| Check | `https://blockrun.ai/api/v1/modal/sandbox/status` | `sandbox_id`. |
| End | `https://blockrun.ai/api/v1/modal/sandbox/terminate` | `sandbox_id`. |

For a create, `image`, when sent, is `python:3.11`, the one managed image. Leave out `gpu` for a CPU-only sandbox, or set it to one of `T4`, `L4`, `A10G`, `A100`, and `H100`. `cpu` is a number of cores and defaults to 1. `memory` is in MB and defaults to 512, so ask for more when the job needs it. `timeout` is the sandbox's lifetime in seconds, from 10 seconds to 24 hours, and defaults to 5 minutes.

For a command, `command` is an array of up to 32 strings of up to 2,000 characters each, such as `["python", "-c", "print(1)"]`. Its `timeout` runs from 1 to 60 seconds and defaults to 60.

A field BlockRun doesn't recognize, or a value outside these ranges, is refused before anything is paid.

Pay these URLs as written. Another BlockRun host can quote a price for the same paths without running a sandbox.

## What it costs

* **A sandbox of up to 5 minutes** pays a flat price for its GPU type.
* **A longer sandbox** pays an hourly price for the whole `timeout` you ask for, charged once at create.
* **Ending a sandbox early refunds nothing.** Ask for the shortest `timeout` that does the job.
* **Each command, check, and end** costs a small fixed price, currently \$0.002.

Prices change, so check the create's exact price before paying, as [Call a paid API](https://docs.anchorage.com/agentic-banking/guides/call-a-paid-api.md#check-the-price-first) describes.

## Limits

* **Spending.** A long GPU sandbox can cost more than the per-payment limit allows, and its create is declined, not sent for approval. Several long sandboxes in a day can reach the daily cap. See [Limits](https://docs.anchorage.com/agentic-banking/reference/limits.md#spending).
* **Size.** Without a GPU, `cpu` goes up to 1 and `memory` up to 1024. With a GPU, `cpu` goes up to 8 and `memory` up to 32768. A sandbox that uses more memory than it asked for can be stopped.
* **Tested hardware.** BlockRun has tested CPU-only and T4 sandboxes at the default size. L4, A10G, A100, and H100 sandboxes are untested.
* **GPU interruptions.** Modal can stop a GPU sandbox before its `timeout` ends. Save the progress of long GPU work somewhere outside the sandbox.

## Slow creates and long-running commands

A paid call waits a limited time for BlockRun's answer. The agent can ask Anchorage Agentic Banking for a longer wait when it pays, as [Crypto payments](https://docs.anchorage.com/agentic-banking/concepts/payments.md) describes. That wait is a setting on the payment, separate from the `timeout` in the request body: raising a create's `timeout` makes the sandbox live longer, which can raise its price, and leaves the wait unchanged.

* **A slow create.** A GPU sandbox can take longer to start than the paid call waits. Ask for the longest wait on a GPU create. If the sandbox still isn't ready when the wait ends, the agent gets no `sandbox_id`, while the sandbox starts and runs for the `timeout` it paid for. Keep a GPU create's `timeout` at 5 minutes or less, so a sandbox the agent can't reach costs only the flat price and ends soon.
* **A long command.** A command runs for at most its `timeout`, up to 60 seconds, and the paid call can wait less than that. Ask for a wait longer than the command's `timeout`. A command that outlasts the wait can still be charged, and its output is lost. Start long work in the background in one command, writing its output to a file, then read the file with later short commands until the work finishes.
* **Processes a command starts.** A command's `timeout` stops the process it ran. Processes that process started keep running until they exit or the sandbox ends. Write the command so stopping it also stops them, or end the sandbox.
* **Large output.** A paid call returns only part of a very long response. Read a large output file in pieces, a range of lines or bytes per command.

## When a payment fails

See [Errors and retries](https://docs.anchorage.com/agentic-banking/reference/errors-and-retries.md) for which failures to retry, and with which idempotency key.


## Related topics

- [Changelog](https://docs.anchorage.com/agentic-banking/changelog.md)
- [Overview](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-overview.md)
- [Sandbox onboarding](https://docs.anchorage.com/knowledge-base/platform/developers/sandbox/sandbox-onboarding.md)
- [AI security and guardrails](https://docs.anchorage.com/knowledge-base/build-with-ai/security.md)
- [Use Claude Code or an Anthropic SDK](https://docs.anchorage.com/agentic-banking/guides/use-claude-code-or-an-anthropic-sdk.md)
