Skip to main content
Commands and file transfers work only while the sandbox is running. Call wait_until_running first.

Run a command

execute runs a command and waits for it to finish.
  • The call waits at most 25 seconds. Set wait_timeout_seconds (1 to 25) to wait less.
  • If the command is still running when the wait ends, the call returns with accepted set to true and status running. Poll it with get_execution.
  • stdout and stderr each return at most 1 MiB. Anything beyond that is dropped, and stdout_truncated or stderr_truncated is set to true.
For large output, redirect it to a file in the sandbox, then download the file.

Run a long command

For commands that take longer than 25 seconds, start them without waiting, then poll or cancel.
While a command is pending, running or cancelling, it has not finished. Final statuses include succeeded, failed and cancelled; a cancelled command’s process is stopped.

Transfer files

  • Paths must be absolute and cannot contain . or .. segments.
  • One upload can be up to about 500 MB. Larger uploads return HTTP 413. Split larger files and join them in the sandbox, or have the sandbox download them from object storage.
  • The SDK reads the whole file into memory before sending it. Leave enough memory for the file size.
  • Each request times out after 30 seconds by default. Raise it for large files: AgentBoxClient(timeout=...) in Python, agentbox.WithTimeout(...) in Go. If you pass your own client with agentbox.WithHTTPClient, set Timeout on that client instead.

Sandbox environment

  • Commands run as the image’s USER, or root if the image does not set one. The working directory is the image’s WORKDIR, or / if not set.
  • sudo is available in the sandbox.
  • Outbound internet access is on by default, over IPv4.
  • Docker is not available inside a sandbox.
  • Pass secrets as environment variables with "secret": true when you launch the sandbox (env on launch). They are not returned when you read the sandbox and are not copied into snapshots, so pass them on every launch. Do not put secrets in command strings.