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

# Commands and files

> Run commands in a sandbox and transfer files in and out.

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.

```python Python theme={null}
result = sandbox.execute("echo hello")
print(result.status, result.exit_code)
print(result.data.get("stdout"), result.data.get("stderr"))
```

```go Go theme={null}
result, err := sandbox.Execute(ctx, "echo hello", agentbox.ExecuteParams{})
fmt.Println(result.Status())
if code := result.ExitCode(); code != nil { // nil until the command finishes
	fmt.Println("exit code:", *code)
}
fmt.Println(result.Data["stdout"], result.Data["stderr"])
```

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

> [!TIP]
>
> For large output, redirect it to a file in the sandbox, then [download the file](#transfer-files).

## Run a long command

For commands that take longer than 25 seconds, start them without waiting, then poll or cancel.

```python Python theme={null}
import time

execution = sandbox.execute("sleep 120", wait=False)

# Poll until the command finishes
while True:
    execution = sandbox.get_execution(execution.id)
    if execution.status not in ("pending", "running", "cancelling"):
        break
    time.sleep(2)
print(execution.status, execution.exit_code)

# Or cancel it
sandbox.cancel_execution(execution.id)
```

```go Go theme={null}
wait := false
execution, err := sandbox.Execute(ctx, "sleep 120", agentbox.ExecuteParams{Wait: &wait})

// Poll until the command finishes
for {
	execution, err = sandbox.GetExecution(ctx, execution.ID())
	if err != nil {
		return err
	}
	if s := execution.Status(); s != "pending" && s != "running" && s != "cancelling" {
		break
	}
	time.Sleep(2 * time.Second)
}
fmt.Println(execution.Status())
if code := execution.ExitCode(); code != nil {
	fmt.Println("exit code:", *code)
}

// Or cancel it
sandbox.CancelExecution(ctx, execution.ID())
```

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

```python Python theme={null}
sandbox.upload_file(path="/root/input.txt", file=b"hello\n")
# file also accepts a local path or an open binary file

download = sandbox.download_file(path="/root/input.txt")
print(download.filename, download.content)
```

```go Go theme={null}
_, err = sandbox.UploadFile(ctx, "/root/input.txt", "input.txt", bytes.NewReader([]byte("hello\n")))

download, err := sandbox.DownloadFile(ctx, "/root/input.txt")
fmt.Println(download.Filename, download.Content)
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.