Skip to main content
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. 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 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. To retry a failed call, follow Errors and retries. 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 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.
  • 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 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 for which failures to retry, and with which idempotency key.