> ## 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. # GMI Sandbox SDK Reference > Python SDK reference for GMI Sandbox control-plane and data-plane APIs. # GMI Sandbox SDK Reference Python SDK for the GMI Sandbox control plane and sandbox data plane. ## Installation ```bash theme={null} python -m pip install gmi-sandbox-sdk ``` The SDK requires Python 3.9 or newer. ## Configuration The client reads these environment variables when explicit arguments are not provided: | Variable | Default | Description | | - | - | - | | `GMI_SANDBOX_API_KEY` | none | Bearer API key | | `GMI_SANDBOX_IDC_NAME` | none | Used when `idc_name` is omitted from `sandboxes.create()`, `templates.create()` and `product_specifications.list()`. If neither is set, sandbox and template creation fall back to the organization's default IDC (400 `idc_name is required` when it has none); `product_specifications.list()` has no such fallback and always needs an IDC. | ```bash theme={null} export GMI_SANDBOX_API_KEY="your-api-key" ``` ## Client ```python theme={null} from sandbox_sdk import SandboxClient client = SandboxClient() ``` Explicit configuration: ```python theme={null} client = SandboxClient( api_key="your-api-key", timeout=30.0, ) ``` Constructor arguments: | Argument | Type | Description | | - | - | - | | `api_key` | `str \| None` | API key. Falls back to `GMI_SANDBOX_API_KEY`. | | `base_url` | `str \| None` | Optional control-plane URL for non-default API endpoints. Falls back to `GMI_SANDBOX_BASE_URL`. | | `timeout` | `float` | Transport timeout in seconds. Default: `30.0`. | | `transport` | callable \| None | Optional transport for tests or custom networking. | `client.health()` returns local client information: ```python theme={null} { "status": "ok", "baseUrl": "https://console.gmicloud.ai/api/v2", "authenticated": True, } ``` ### Async client `AsyncSandboxClient` mirrors the synchronous client. All operations that can perform network or file I/O are awaitable: ```python theme={null} from sandbox_sdk import AsyncSandboxClient async with AsyncSandboxClient() as client: sandbox = await client.sandboxes.create(template_id="template-id") await sandbox.wait_until_running() await sandbox.connect() execution = await sandbox.commands.run("echo hello", wait=True) ``` The async client accepts the same configuration arguments. Its optional `transport` must be an async callable returning `RawResponse`. Call `await client.aclose()` when the client is not managed by `async with`. `aclose()` closes only the transport the SDK owns. A `transport` supplied by the caller is never closed by the client; closing it is the caller's responsibility. After `aclose()`, further requests raise `TransportError` rather than silently opening a new connection pool. Both clients accept `http` and `https` URLs only and re-validate that scheme on every redirect hop. The check does not limit which hosts a configured `base_url` may reach. A malformed URL in `base_url` or in a redirect `Location`, such as a non-numeric port or an invalid host name, raises `TransportError` and is not retried. Non-ASCII characters in the path and query are sent percent-encoded as UTF-8. ## Basic Workflow ```python theme={null} from sandbox_sdk import SandboxClient client = SandboxClient() sandbox = client.sandboxes.create( template_id="template-id", idempotency_key="create-request-1", ) sandbox.wait_until_running(timeout=300) sandbox.connect(timeout=300) execution = sandbox.commands.run("echo hello", wait=False).wait(timeout=300) print(execution.stdout) sandbox.delete() ``` `idc_name` is optional for sandbox and template creation: when omitted, the service falls back to the organization's configured default IDC. ## Sandboxes ### `client.sandboxes.create()` ```python theme={null} sandbox = client.sandboxes.create( idc_name="gmi-sandbox-us", template_id="template-id", # or snapshot_id="snapshot-id" timeout=300, env_vars={"APP_ENV": "production"}, metadata={"owner": "platform"}, idempotency_key="sandbox-create-1", ) ``` Arguments: | Argument | Description | | - | - | | `idc_name` | Target IDC. Falls back to `GMI_SANDBOX_IDC_NAME`, then to the organization's default IDC. | | `template_id` | Template source. Exactly one of `template_id` and `snapshot_id` is required. | | `snapshot_id` | Launch from a `ready` snapshot instead of a template. Compute resources are inherited from the snapshot. | | `timeout` | Sandbox lifetime in seconds. | | `env_vars` | Runtime environment variables. | | `metadata` | String metadata attached to the sandbox. | | `default_user` | Optional default user for commands and files in this sandbox. | | `idempotency_key` | Optional create idempotency key. | Returns a `Sandbox`. ### `client.sandboxes.list()` ```python theme={null} page = client.sandboxes.list( page=1, page_size=20, idc_name="gmi-sandbox-us", state=["running"], metadata={"owner": "platform"}, ) ``` `state` accepts a string or a sequence of strings. Metadata is encoded as `metadata[key]` query parameters. ### `client.sandboxes.get()` ```python theme={null} sandbox = client.sandboxes.get("sandbox-id") ``` ### `client.sandboxes.connect()` ```python theme={null} sandbox = client.sandboxes.connect("sandbox-id", timeout=300) ``` The returned sandbox contains fresh data-plane connection fields. ## `Sandbox` Properties: | Property | Description | | - | - | | `sandbox_id` | Sandbox identifier (control-plane UUID) | | `id` | Alias for `sandbox_id` | | `sandbox_key` | Data-plane addressing key, used to build `data_plane_url` | | `domain` | Data-plane domain | | `sandbox_access_token` | Data-plane access token | | `state` | Lifecycle state | | `data_plane_url` | Computed data-plane URL | | `files` | `SandboxFiles` helper | | `commands` | `SandboxCommands` helper | | `executions` | Alias for `commands` | | `data` | Raw response data dictionary | Lifecycle states (`SandboxStatus`): `provisioning`, `running`, `pausing`, `paused`, `resuming`, `checkpointing`, `updating`, `failed`, `deleting`, and `deleted`. Methods: ```python theme={null} sandbox.refresh() sandbox.wait_until_running(timeout=300) sandbox.update_metadata({"team": "platform"}) sandbox.set_timeout(300) sandbox.connect(timeout=300) sandbox.pause() sandbox.resume(timeout=300) # timeout is optional snapshot = sandbox.create_snapshot(name="base", metadata={"team": "platform"}) sandbox.delete() ``` `refresh()`, `wait_until_running()` and `update_metadata()` keep the data-plane connection fields returned by `connect()` (`sandbox_access_token`, `traffic_access_token`, `domain`); the sandbox detail and update responses do not include the access tokens. Data-plane calls (`files`, `commands`) raise `ValueError` if the sandbox has no access token; call `connect()` first. `pause()` keeps disk files except `/tmp`; memory and running processes are not kept. `resume()` is a cold start. Call `connect()` again before data-plane calls. `wait_until_running()` raises `TerminalStateError` (a `RuntimeError`) as soon as the sandbox is `failed`, `deleting` or `deleted`, or is `paused` (a resume that did not complete); it does not wait out the timeout for states that cannot become `running`. `set_timeout()` resets the time-to-live and returns the sandbox with `end_at` set to the new expiry. In some IDCs the access token is bound to the previous `end_at`, so call `connect()` again after extending the lifetime; where the token is not time-bound, `connect()` returns the same token. ## Snapshots A snapshot is a durable copy of a running sandbox. Launch new sandboxes from a `ready` snapshot with `client.sandboxes.create(snapshot_id=...)`. ```python theme={null} snapshot = client.snapshots.create("sandbox-id", name="base", metadata={"team": "platform"}, idempotency_key="snapshot-1") snapshot.wait_until_ready(timeout=300) page = client.snapshots.list(source_sandbox_id="sandbox-id", status="ready", page_size=50) snapshot = client.snapshots.get("snapshot-id") snapshot.update(name="renamed", metadata={"team": "infra"}) snapshot.delete() ``` `Snapshot` properties: `snapshot_id` (alias `id`), `name`, `idc_name`, `source_sandbox_id`, `status`, `data`. Snapshot statuses (`SnapshotStatus`): `creating`, `ready`, `error`, `deleting`, and `delete_failed`. A deleted snapshot is no longer returned: reading it raises `NotFoundError`. `wait_until_ready()` raises `TerminalStateError` (a `RuntimeError`) on `error`, `deleting` or `delete_failed`, including `status_reason` when the service supplies one. `snapshot.delete()` raises `ConflictError` while a sandbox launched from the snapshot is still active; delete those sandboxes first. A paused sandbox cannot be snapshotted (`ConflictError`); resume it first. ## Files All file methods use the sandbox data plane and require `connect()` first. ```python theme={null} sandbox.files.read("/tmp/input.txt") sandbox.files.write("/tmp/output.txt", "hello") sandbox.files.write("/tmp/output.bin", b"\x00\x01") sandbox.files.upload("./local.txt", "/tmp/local.txt") sandbox.files.upload_tree("./local-directory", "/workspace") sandbox.files.download("/tmp/local.txt") sandbox.files.download( "/tmp/local.txt", destination="./downloaded.txt", byte_range="bytes=10-", ) ``` Methods: | Method | Description | | - | - | | `read(path, username=None)` | Read file bytes | | `write(path, content, username=None, filename=None)` | Write text or bytes | | `upload(source, path, username=None)` | Upload a local path or bytes | | `upload_tree(local_dir, remote_dir, timeout=300)` | Tar, upload, and remotely unpack a directory tree | | `download(path, destination=None, username=None, byte_range=None)` | Download bytes, optionally to a local path | `download()` always returns `bytes`. `destination` is an additional local write. Both `read()` and `download()` buffer the complete response in memory; use `byte_range` with `download()` when retrieving large files in chunks. `upload_tree()` reuses the 512 MiB packed-size limit and skips symlinks that resolve outside the local directory. It uploads one archive, unpacks it with the sandbox command API under `/bin/sh` (so images without bash work), and removes the temporary archive. `timeout` bounds both the client wait and how long the sandbox lets the unpack run (at most 3600 seconds). If the unpack fails, it raises `TerminalStateError` (a `SandboxSDKError` and a `RuntimeError`) with the exit code and stderr; `.state` holds the execution status. ## Command Execution ```python theme={null} execution = sandbox.commands.run( "python --version", envs={"PYTHONUNBUFFERED": "1"}, cwd="/tmp", wait=True, wait_timeout_seconds=25, ) ``` Arguments: | Argument | Description | | - | - | | `command` | Shell command | | `envs` | Environment variables for the process | | `cwd` | Working directory | | `wait` | Wait for a result within the wait window | | `wait_timeout_seconds` | Server wait window; the API currently accepts 1-25 seconds | | `execution_timeout_seconds` | How long the sandbox lets the command run, 1-3600 seconds. The data plane uses 300 when omitted; past the limit the command is ended as `timed_out` with no exit code or output | | `request_id` | Sent as the `X-Request-ID` header. The data plane ignores it and generates its own `request_id`, returned in responses and errors | `Execution` properties: ```python theme={null} execution.execution_id execution.status execution.exit_code execution.stdout execution.stderr execution.stdout_truncated execution.stderr_truncated execution.data ``` `stdout` and `stderr` are each capped at 1 MiB. When a stream is cut, `stdout_truncated` / `stderr_truncated` is `True`; redirect large output to a file and read it with `sandbox.files.download(..., byte_range=...)`. Execution statuses (`ExecutionStatus`): `pending`, `running`, `cancelling`, `succeeded`, `failed`, `cancelled`, and `timed_out`. `timed_out` is terminal: the command outlived `execution_timeout_seconds`. Methods: ```python theme={null} execution.refresh() execution.cancel() execution.wait(timeout=300, cancel_on_timeout=True) ``` Cancel only non-terminal executions. The service may reject cancellation after an execution has completed. If `wait()` times out but the execution finishes before its cancel lands, it returns the finished execution instead of raising. Otherwise it raises `WaitTimeoutError`, even when the cancel itself fails; the cancel error is available as `__cause__`. The synchronous `POST /executions` wait window is capped at approximately 25 seconds. Run with `wait=False`, then call `Execution.wait()` for longer work, and set `execution_timeout_seconds` for anything that may run longer than 300 seconds: `Execution.wait()` only bounds how long the client waits, not how long the sandbox lets the command run. ## Templates ### Create ```python theme={null} template = client.templates.create( name="demo-template", idc_name="gmi-sandbox-us", resources={"type": "preset", "product": "gmi.sandbox.small"}, build={ "source": {"type": "image", "image": "ubuntu:22.04"}, "commands": ["apt-get update"], "envs": {"BUILD_ENV": "production"}, "start_cmd": "sleep infinity", }, description="Example template", labels={"team": "platform"}, idempotency_key="template-create-1", ) ``` `resources` selects a catalog preset by product SKU (see `client.product_specifications.list()`): ```python theme={null} {"type": "preset", "product": "gmi.sandbox.small"} ``` Custom resources (`"type": "custom"`) are currently rejected with 400 `Request.InvalidParameter`. Build sources include image and template sources: ```python theme={null} {"type": "image", "image": "ubuntu:22.04"} {"type": "template", "template_id": "parent-template-id"} ``` `idempotency_key` is required for template creation: retrying with the same key and arguments replays the same Template instead of creating a second one. A retry after the Build already started is also safe; the SDK confirms the Build is past `waiting` and does not start it again. Rebuilds (`templates.builds.create()`) are not idempotent. Each call creates a new Build and supersedes the Template's running Builds, so do not blindly retry one. Its `idempotency_key` is optional and only lets a retry reuse an uploaded `build_context_dir`; it is not sent with the rebuild itself. Dockerfile builds accept `dockerfile_content`, `build_context_dir`, and `start_cmd` in place of `build`: ```python theme={null} template = client.templates.create( name="dockerfile-template", resources={"type": "preset", "product": "gmi.sandbox.small"}, dockerfile_content="FROM ubuntu:22.04\nCOPY . /workspace\n", build_context_dir="./context", start_cmd="python /workspace/main.py", idempotency_key="template-dockerfile-1", ) ``` Build contexts are uploaded as gzip-compressed tar archives (`tgz`) and are limited to 512 MiB before compression. Only the paths that `COPY`/`ADD` read are packed, and a `.dockerignore` at the root of `build_context_dir` is honored with Docker's rules (`*`, `**`, `?`, `!` exceptions, last match wins). A `COPY` source excluded by `.dockerignore` raises `ValueError`. Symlinks that resolve outside `build_context_dir` are excluded from the archive. Unlike `.gitignore`, a pattern without `/` matches only at the root of `build_context_dir`: `*.env` excludes `secret.env` but not `app/secret.env`. Prefix `**/` to match at any depth, for example `**/*.env` or `**/node_modules`. A trailing `/` is ignored, so `temp/` also excludes a file named `temp`. This is the same as `docker build`. When the Dockerfile uses the context, the SDK performs the live API's split flow: create the waiting Template/Build, initialize and upload a tgz context, poll until the file is ready, and start the existing Build. The API supports a single context file, so the SDK rewrites each local `COPY`/`ADD` into steps that unpack that file. Each instruction takes one source inside `build_context_dir` (a file or a directory, `.` for all of it) and one destination, in shell form or JSON form (`COPY ["app.py", "/app/"]`), and may span lines with a trailing backslash. `$VAR` and `${VAR}` in the destination expand to `ENV` values. `COPY`/`ADD` flags such as `--chown` are rejected, and so are heredocs (`RUN <