GMI Sandbox SDK Reference

Python SDK for the GMI Sandbox control plane and sandbox data plane.

Installation

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`	organization default IDC	Optional. Set only when targeting a non-default IDC.

export GMI_SANDBOX_API_KEY="your-api-key"

Client

from sandbox_sdk import SandboxClient

client = SandboxClient()

Explicit configuration:

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:

{
    "status": "ok",
    "baseUrl": "https://console.gmicloud.ai/api/v2",
    "authenticated": True,
}

Basic Workflow

from sandbox_sdk import SandboxClient

client = SandboxClient()

sandbox = client.sandboxes.create(
    template_id="template-id",
    idempotency_key="create-request-1",
)

sandbox.connect(timeout=300)
execution = sandbox.commands.run("echo hello", wait=True, wait_timeout_seconds=25)
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()`

sandbox = client.sandboxes.create(
    idc_name="gmi-sandbox-us",
    template_id="template-id",
    timeout=300,
    env_vars={"APP_ENV": "production"},
    metadata={"owner": "platform"},
    idempotency_key="sandbox-create-1",
)

Arguments:

Argument	Description
`idc_name`	Target IDC. Optional; falls back to the organization’s default IDC when omitted.
`template_id`	Template source. Required.
`timeout`	Sandbox lifetime in seconds.
`env_vars`	Runtime environment variables.
`metadata`	String metadata attached to the sandbox.
`idempotency_key`	Optional create idempotency key.

Returns a Sandbox.

`client.sandboxes.list()`

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()`

sandbox = client.sandboxes.get("sandbox-id")

`client.sandboxes.connect()`

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 include provisioning, running, checkpointing, updating, and failed. Methods:

sandbox.refresh()
sandbox.update_metadata({"team": "platform"})
sandbox.set_timeout(300)
sandbox.connect(timeout=300)
sandbox.delete()

Files

All file methods use the sandbox data plane and require connect() first.

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

Command Execution

execution = sandbox.commands.run(
    "python --version",
    envs={"PYTHONUNBUFFERED": "1"},
    cwd="/tmp",
    wait=True,
    wait_timeout_seconds=25,
    request_id="execution-request-1",
)

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
`request_id`	Optional request correlation ID

Execution properties:

execution.execution_id
execution.status
execution.exit_code
execution.stdout
execution.stderr
execution.data

Execution statuses include pending, running, canceling, succeeded, failed, and canceled. Methods:

execution.refresh(request_id="refresh-1")
execution.cancel(request_id="cancel-1")

Cancel only non-terminal executions. The service may reject cancellation after an execution has completed.

Templates

Create

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 supports preset or custom values. Preset:

{"type": "preset", "product": "gmi.sandbox.small"}

Custom:

{
    "type": "custom",
    "cpu_count": 2,
    "memory_mb": 4096,
    "disk_size_mb": 20480,
    "architecture": "x86_64",
}

Build sources include image and template sources:

{"type": "image", "image": "ubuntu:22.04"}
{"type": "template", "template_id": "parent-template-id"}

idempotency_key is required for template creation. Returns a Template. The returned object can be used with template instance methods such as update(), delete(), builds(), build(), and build_logs().

List and Get

page = client.templates.list(idc_name="gmi-sandbox-us")
template = client.templates.get("template-id", idc_name="gmi-sandbox-us")

Update and Delete

template.update(name="renamed-template", description="Updated description")
template.delete()

The template’s idc_name is reused automatically when present in the template response.

Builds and Logs

builds = template.builds(page=1, page_size=20)
build = template.build("build-id")
logs = template.build_logs("build-id", offset=0, limit=100)

Product Specifications

specifications = client.product_specifications.list()
specifications = client.product_specifications.list(idc_name="gmi-sandbox-us")

Pagination

List methods return a Page object:

page = client.sandboxes.list(page=1, page_size=20)

print(page.items)
print(page.total)
print(page.page)
print(page.page_size)
print(page.request_id)

Page fields:

Field	Type	Description
`items`	`list`	Returned resources
`total`	`int`	Total matching resources
`page`	`int`	Current page
`page_size`	`int`	Requested page size
`request_id`	`str \| None`	Server request ID

Errors

All SDK exceptions derive from SandboxSDKError.

Exception	HTTP status
`BadRequestError`	400
`AuthenticationError`	401
`PermissionDeniedError`	403
`NotFoundError`	404
`ConflictError`	409
`RateLimitError`	429
`ServerError`	500+
`TransportError`	Request could not reach the endpoint

APIError fields:

try:
    client.sandboxes.get("missing")
except NotFoundError as exc:
    print(exc.status_code)
    print(exc.message)
    print(exc.code)
    print(exc.request_id)
    print(exc.details)

Error handling example:

from sandbox_sdk import ConflictError, NotFoundError, SandboxSDKError

try:
    sandbox = client.sandboxes.get("sandbox-id")
    sandbox.connect()
except NotFoundError:
    print("sandbox no longer exists")
except ConflictError:
    print("sandbox is in a transitional state; retry later")
except SandboxSDKError as exc:
    print(f"sandbox request failed: {exc}")

OpenAPI Coverage

The SDK maps the Sandbox-related OpenAPI operations as follows:

OpenAPI operation	SDK
`createSandbox`	`client.sandboxes.create()`
`listSandboxes`	`client.sandboxes.list()`
`getSandbox`	`client.sandboxes.get()`
`updateSandbox`	`sandbox.update_metadata()`
`deleteSandbox`	`sandbox.delete()`
`connectSandbox`	`sandbox.connect()`
`setSandboxTimeout`	`sandbox.set_timeout()`
`createSandboxExecution`	`sandbox.commands.run()`
`getSandboxExecution`	`execution.refresh()`
`cancelSandboxExecution`	`execution.cancel()`
`downloadSandboxFile`	`sandbox.files.read()` / `download()`
`uploadSandboxFile`	`sandbox.files.write()` / `upload()`
`listProductCatalog`	`client.product_specifications.list()`
`createTemplate`	`client.templates.create()`
`listTemplates`	`client.templates.list()`
`getTemplate`	`client.templates.get()`
`updateTemplate`	`template.update()`
`deleteTemplate`	`template.delete()`
`listTemplateBuilds`	`template.builds()`
`getTemplateBuild`	`template.build()`
`getTemplateBuildLogs`	`template.build_logs()`

API Introduction

Sandbox SDK

IAM Service APIs

Compute Service APIs

IDC Service APIs

GMI Sandbox SDK Reference

GMI Sandbox SDK Reference

Installation

Configuration

Client

Basic Workflow

Sandboxes

`client.sandboxes.create()`

`client.sandboxes.list()`

`client.sandboxes.get()`

`client.sandboxes.connect()`

`Sandbox`

Files

Command Execution

Templates

Create

List and Get

Update and Delete

Builds and Logs

Product Specifications

Errors

OpenAPI Coverage

​GMI Sandbox SDK Reference

​Installation

​Configuration

​Client

​Basic Workflow

​Sandboxes

​client.sandboxes.create()

​client.sandboxes.list()

​client.sandboxes.get()

​client.sandboxes.connect()

​Sandbox

​Files

​Command Execution

​Templates

​Create

​List and Get

​Update and Delete

​Builds and Logs

​Product Specifications

​Pagination

​Errors

​OpenAPI Coverage

GMI Sandbox SDK Reference

Installation

Configuration

Client

Basic Workflow

Sandboxes

`client.sandboxes.create()`

`client.sandboxes.list()`

`client.sandboxes.get()`

`client.sandboxes.connect()`

`Sandbox`

Files

Command Execution

Templates

Create

List and Get

Update and Delete

Builds and Logs

Product Specifications

Pagination

Errors

OpenAPI Coverage