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

# Quickstart

> Launch your first Agentbox sandbox and run a command.

**1. Create an API key**

Sign in to the [GMI Cloud Console](https://console.gmicloud.ai). In the **Compute** panel (not Inference), open **Access** → [**API Keys**](https://console.gmicloud.ai/user-setting/ce/access/api-keys) and click **Create API key**. Store the key securely; it authenticates requests for your organization.

```bash theme={null}
export GMI_AGENTBOX_API_KEY="your-api-key"
```

**2. Install the SDK**

```bash Python theme={null}
python -m pip install gmi-agentbox-sdk
```

```bash Go theme={null}
go get github.com/GMISWE/agentbox-sdk-go
```

**3. Create an Agent, launch a sandbox and run a command**

The example picks a data center and a size, creates an Agent from a public image, waits for the image build, launches a sandbox, runs `echo hello`, and cleans up.

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

from agentbox_sdk import AgentBoxClient, SandboxFailed, SandboxWaitTimeout

client = AgentBoxClient()  # reads GMI_AGENTBOX_API_KEY

# Available values vary by organization.
idcs = client.idcs.list(runtime="sandbox")
idc_id = "us-central-iowa16"  # choose an idc_id returned above
products = client.products.list(idc_name=idc_id, runtime="sandbox")
instance_type = "gmi.sandbox.small"  # choose an instance_type returned above


def wait_for_template(agent, timeout=600, poll_interval=3):
    deadline = time.monotonic() + timeout
    while True:
        agent.refresh()
        status = agent.template_build_status
        if status == "ready" or status is None:
            return
        if status == "error":
            raise RuntimeError(agent.template_build_error or "Sandbox image build failed")
        if time.monotonic() >= deadline:
            raise TimeoutError(f"Sandbox image is still {status!r} after {timeout}s")
        time.sleep(poll_interval)


agent = None
sandbox = None
try:
    agent = client.agents.create(
        title="agentbox-demo",  # choose a unique name
        image_url="docker.io/library/alpine:3.20",
        idc=idc_id,
        instance_type=instance_type,
        runtime="sandbox",
    )
    wait_for_template(agent)  # a new image can take several minutes

    sandbox = agent.launch(instance_type=instance_type)
    sandbox.wait_until_running()  # default timeout 300s

    execution = sandbox.execute("echo hello")
    print(execution.status, execution.exit_code, execution.data.get("stdout"))
except SandboxFailed as exc:
    print("failed", exc.status, exc.message)
except SandboxWaitTimeout:
    print("still not running", sandbox.status, sandbox.last_error)
finally:
    if sandbox is not None:
        sandbox.delete()
    if agent is not None:
        agent.delete()
```

```go Go theme={null}
package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/GMISWE/agentbox-sdk-go/agentbox"
)

func waitForTemplate(ctx context.Context, agent *agentbox.Agent, timeout, pollInterval time.Duration) error {
	deadline := time.Now().Add(timeout)
	for {
		if err := agent.Refresh(ctx); err != nil {
			return err
		}
		status := agent.TemplateBuildStatus()
		if status == "ready" || status == "" {
			return nil
		}
		if status == "error" {
			msg := agent.TemplateBuildError()
			if msg == "" {
				msg = "Sandbox image build failed"
			}
			return errors.New(msg)
		}
		if time.Now().After(deadline) {
			return fmt.Errorf("Sandbox image is still %q after %s", status, timeout)
		}
		time.Sleep(pollInterval)
	}
}

func main() {
	ctx := context.Background()
	client, err := agentbox.NewClient() // reads GMI_AGENTBOX_API_KEY
	if err != nil {
		panic(err)
	}

	// Available values vary by organization.
	idcs, err := client.Idcs.List(ctx, "sandbox")
	if err != nil {
		panic(err)
	}
	_ = idcs
	idcID := "us-central-iowa16" // choose an idc_id returned above
	products, err := client.Products.List(ctx, agentbox.ProductListParams{IdcName: idcID, Runtime: "sandbox"})
	if err != nil {
		panic(err)
	}
	_ = products
	instanceType := "gmi.sandbox.small" // choose an instance_type returned above

	var agent *agentbox.Agent
	var sandbox *agentbox.Sandbox
	defer func() {
		if sandbox != nil {
			sandbox.Delete(ctx)
		}
		if agent != nil {
			agent.Delete(ctx)
		}
	}()

	agent, err = client.Agents.Create(ctx, agentbox.AgentCreateParams{
		Title:        "agentbox-demo", // choose a unique name
		ImageURL:     "docker.io/library/alpine:3.20",
		Idc:          idcID,
		InstanceType: instanceType,
		Runtime:      "sandbox",
	})
	if err != nil {
		panic(err)
	}
	if err := waitForTemplate(ctx, agent, 600*time.Second, 3*time.Second); err != nil {
		panic(err)
	}

	sandbox, err = agent.Launch(ctx, agentbox.LaunchParams{InstanceType: instanceType})
	if err != nil {
		panic(err)
	}
	if err := sandbox.WaitUntilRunning(ctx, agentbox.WaitUntilRunningParams{}); err != nil {
		panic(err)
	}

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

> [!NOTE]
>
> If your organization has no balance or credit yet, a sandbox can launch and then stop automatically within a few seconds. Top up or redeem your credit, then try again.

## Configuration

| Environment variable | Required | Description |
| - | - | - |
| `GMI_AGENTBOX_API_KEY` | Yes, unless you pass the key in code | API key. Python: `AgentBoxClient(api_key=...)`. Go: `agentbox.WithAPIKey(...)`. |
| `GMI_AGENTBOX_BASE_URL` | No | API root. Defaults to `https://api.gmi-serving.com/v1/agents`. Python: `AgentBoxClient(base_url=...)`. Go: `agentbox.WithBaseURL(...)`. |

## Next steps

* [Sandboxes](https://docs.gmicloud.ai/agentbox-sdk/sandboxes.md): labels, lifetime, pause and resume
* [Commands and files](https://docs.gmicloud.ai/agentbox-sdk/commands-and-files.md): long-running commands and file transfer
* [Errors and limits](https://docs.gmicloud.ai/agentbox-sdk/errors-and-limits.md)


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