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

# Go SDK reference

> Types and methods in the github.com/GMISWE/agentbox-sdk-go module.

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

```go theme={null}
import "github.com/GMISWE/agentbox-sdk-go/agentbox"
```

Requires Go 1.25.5+. Every method that calls the service takes a `context.Context` first. For workflows and examples, start with the [Quickstart](https://docs.gmicloud.ai/agentbox-sdk/quickstart.md).

## Client

### agentbox.NewClient

```go theme={null}
func NewClient(opts ...Option) (*Client, error)
```

**Options**

| Option | Default | Description |
| - | - | - |
| `WithAPIKey(key)` | `GMI_AGENTBOX_API_KEY` | API key. `NewClient` returns an error if it is unset. |
| `WithBaseURL(url)` | `GMI_AGENTBOX_BASE_URL`, then `https://api.gmi-serving.com/v1/agents` | API root. |
| `WithTimeout(d)` | `30 * time.Second` | Request timeout. Does not apply to streams; use the context. Ignored when `WithHTTPClient` is set; set `Timeout` on your own client. |
| `WithHTTPClient(c)` | internal | Custom `*http.Client` for requests. |

**Collections**: `client.Agents`, `client.Sandboxes`, `client.Snapshots`, `client.Idcs`, `client.Products`.

### client.Eligibility

```go theme={null}
func (c *Client) Eligibility(ctx context.Context) (*Eligibility, error)
```

Returns whether your organization can launch (`Eligible`) and in which data centers (`DataCenters`).

## Catalog

### client.Idcs.List

```go theme={null}
List(ctx, runtime string) ([]*Idc, error)
```

Lists data centers. Pass `"sandbox"`. Each `Idc` has `IdcID()` (use this as `Idc` / `IdcName`) and `Name()`.

### client.Products.List

```go theme={null}
List(ctx, ProductListParams{IdcName, Runtime}) ([]*Product, error)
```

Lists sizes in a data center. Each `Product` has `InstanceType()` (the size ID) and `Price()`.

## Agents

### client.Agents.Create

```go theme={null}
Create(ctx, AgentCreateParams) (*Agent, error)
```

Creates an Agent and starts its image build. Does not start a sandbox.

| Field | Required | Description |
| - | - | - |
| `Title` | Yes | Agent name |
| `Runtime` | Yes, for sandboxes | `"sandbox"` |
| `Idc` | Yes, for sandboxes | Data center ID |
| `InstanceType` | Yes, for sandboxes | Size ID |
| `ImageURL` | No | Container image |
| `StartCmd` | No | Command the sandbox runs on start |
| `Env` | No | Environment variables, each `{"name", "value", "secret"}` |
| `Ports` | No | Port definitions |
| `ImageCredential` | No | Private registry login, `{"username": ..., "secret": ...}` |
| `ShortDesc` | No | Short description |

A sandbox Agent without `Idc` or `InstanceType` returns HTTP 422.

### client.Agents.Get / List / Update / Delete

```go theme={null}
Get(ctx, slug string) (*Agent, error)
List(ctx, page, pageSize int) (*Page[*Agent], error)
Update(ctx, slug string, AgentUpdateFields) (*Agent, error)
Delete(ctx, slug string) error
```

* `List` pages start at 1. Default page size 20, maximum 100.
* `Update` takes a `map[string]any`. Locked fields return 422.
* `Delete` returns 409 (`IsConflictError`) while the Agent still has sandboxes, and can keep returning it for a few seconds after the last one is deleted. Retry on 409.

### Agent

| Method | Type | Description |
| - | - | - |
| `ID()` | `string` | Agent ID |
| `Slug()` | `string` | Stable identifier used by `Get`, `Update` and `Delete` |
| `Title()` | `string` | Name |
| `Idc()` | `string` | Data center ID |
| `ImageURL()` | `string` | Container image |
| `Runtime()` | `string` | Runtime, for example `sandbox` |
| `TemplateBuildStatus()` | `string` | Image build status: `waiting`, `building`, `ready` or `error` |
| `TemplateBuildError()` | `string` | Build error message when the build failed |
| `GeneratedAPIKey()` | `string` | Generated model API key. Returned only by `Create`, and only when `Env` includes `GMI_MODELS` |
| `Launchable()` | `bool` | Whether a sandbox can launch from this Agent |

| Method | Description |
| - | - |
| `Refresh(ctx) error` | Reloads the Agent. |
| `Update(ctx, AgentUpdateFields) error` | Same as `client.Agents.Update`. |
| `Delete(ctx) error` | Same as `client.Agents.Delete`. |
| `Launch(ctx, LaunchParams) (*Sandbox, error)` | See `agent.Launch` below. |
| `ListSandboxes(ctx, AgentSandboxListParams) (*Page[*Sandbox], error)` | This Agent's sandboxes, filterable by `Metadata`. |
| `ListSnapshots(ctx) ([]*Snapshot, error)` | This Agent's snapshots, newest first. |
| `ListBuilds(ctx) ([]TemplateBuild, error)` | Up to the 100 newest image builds. |
| `GetBuild(ctx, buildID) (TemplateBuild, error)` | One image build. |
| `BuildLogs(ctx, buildID, BuildLogParams) (BuildLogPage, error)` | One page of build logs. |

### agent.Launch

```go theme={null}
Launch(ctx, LaunchParams) (*Sandbox, error)
```

Launches a sandbox and returns immediately. The sandbox starts as `pending`.

| Field | Description |
| - | - |
| `InstanceType` | Size ID. Ignored when `SnapshotID` is set. |
| `IdcName` | Defaults to the Agent's data center. Must match it. |
| `Env` | Environment variables for this sandbox. Use `"secret": true` for secrets. |
| `DisplayName` | Display name. |
| `Metadata` | Your labels, `map[string]string`. Up to 32 keys; keys match `^[A-Za-z0-9_.-]{1,63}$`; values up to 256 characters; `source` and `task_name` are reserved. |
| `TimeoutSeconds` | `*int`. Lifetime in seconds from launch, minimum 60. Leave nil for the platform default lifetime, which renews automatically. A value pins the expiry. |
| `SnapshotID` | Launch from a `ready` snapshot of this Agent. |

Errors: 400 for invalid metadata or a timeout under 60; 404 for an unknown snapshot; 409 when the snapshot is not `ready`.

### agent.BuildLogs

```go theme={null}
BuildLogs(ctx, buildID string, BuildLogParams) (BuildLogPage, error)
```

| Field | Default | Description |
| - | - | - |
| `Offset` | `0` | Zero-based. Pass the previous page's `NextOffset`. |
| `Limit` | `100` | 1 to 100. |
| `Level` | all | `debug`, `info`, `warn` or `error`. |

Returns `BuildLogPage` with `Entries` (each `Offset`, `Level`, `Message`, `Timestamp`), `NextOffset` and `HasMore`. Returns 410 (`IsGoneError`) when the logs have expired.

## Sandboxes

Every method below exists on a `*Sandbox`, and on `client.Sandboxes` with the sandbox ID after the context. For example, `sandbox.Pause(ctx)` is the same as `client.Sandboxes.Pause(ctx, sandboxID)`. The exceptions are `WaitUntilRunning` and `Refresh`, which exist only on a `*Sandbox`.

Some collection methods return a different type:

* `client.Sandboxes.SetTimeout`, `Pause` and `Resume` return `*SandboxExpiry`, `*SandboxPause` and `*SandboxResume`, not the sandbox.
* `client.Sandboxes.CreateSnapshot` returns a `*Snapshot` with no Agent slug. Its `WaitUntilReady` and `Refresh` return an error. Use `sandbox.CreateSnapshot` when you need to wait for the snapshot.

### client.Sandboxes.Launch

```go theme={null}
Launch(ctx, slug string, LaunchParams) (*Sandbox, error)
```

Same as `agent.Launch`, by Agent slug. `IdcName` is required unless `SnapshotID` is set.

### client.Sandboxes.List

```go theme={null}
List(ctx, SandboxListParams) (*Page[*Sandbox], error)
```

| Field | Description |
| - | - |
| `AgentID` | Only this Agent's sandboxes |
| `Status` | `[]string`. If omitted, `stopped` and `deleted` are excluded. |
| `Metadata` | Exact match; all keys must match |
| `Page`, `PageSize` | Pagination |

### client.Sandboxes.Get

```go theme={null}
Get(ctx, sandboxID string) (*Sandbox, error)
```

### sandbox.WaitUntilRunning

```go theme={null}
WaitUntilRunning(ctx, WaitUntilRunningParams{Timeout, PollInterval}) error
```

Polls until the status is `running`. Defaults: `Timeout` 300 seconds, `PollInterval` 2 seconds. Returns `*SandboxFailed` if the status becomes `error`, `deleted`, `stopped` or `stopping`, and `*SandboxWaitTimeout` if the timeout passes first.

### sandbox.Refresh

```go theme={null}
Refresh(ctx) error
```

### sandbox.SetTimeout

```go theme={null}
SetTimeout(ctx, timeoutSeconds int) error
```

Sets the lifetime to now plus `timeoutSeconds` (minimum 60) and pins it. Works while the sandbox is running or paused. Errors: 400 if under 60 or above your account maximum; 409 if the sandbox is not running or paused.

### sandbox.Pause

```go theme={null}
Pause(ctx) error
```

Pauses a running sandbox. Returns when accepted; `Status()` is usually `pausing`. Poll with `Refresh` until `paused`. Returns 409 if the sandbox is not running.

### sandbox.Resume

```go theme={null}
Resume(ctx, ResumeParams{TimeoutSeconds}) error
```

Resumes a paused sandbox. Returns when accepted; `Status()` is usually `resuming`. Poll with `WaitUntilRunning`. Leave `TimeoutSeconds` nil to keep the run time left at pause; a value (60 or more) restarts the lifetime and pins it. Errors: 400 if under 60; 409 if the sandbox is not paused.

### sandbox.Execute

```go theme={null}
Execute(ctx, command string, ExecuteParams{Wait, WaitTimeoutSeconds}) (*Execution, error)
```

Runs a command. `Wait` is a `*bool` and defaults to true. `WaitTimeoutSeconds` is a `*int`, 1 to 25, and is ignored when `Wait` is false. `Accepted` is true when the command is still running.

### sandbox.GetExecution / CancelExecution

```go theme={null}
GetExecution(ctx, executionID string) (*Execution, error)
CancelExecution(ctx, executionID string) (*Execution, error)
```

### sandbox.UploadFile

```go theme={null}
UploadFile(ctx, sandboxPath, filename string, content io.Reader) ([]map[string]any, error)
```

`sandboxPath` must be absolute with no `.` or `..` segments. `filename` defaults to the last element of `sandboxPath` when empty.

### sandbox.DownloadFile

```go theme={null}
DownloadFile(ctx, sandboxPath string) (*FileDownload, error)
```

Returns `FileDownload` with `Content` (`[]byte`), `Filename` and `Header`.

### sandbox.Shell

```go theme={null}
Shell(ctx) (ShellConn, error)

func SendShellInput(conn ShellConn, data string) error
func ResizeShell(conn ShellConn, cols, rows int) error
func RecvShellMessage(conn ShellConn) (ShellMessage, error)
```

Opens an interactive shell. `ShellMessage` has `Type` (`status`, `stdout` or `error`), `Data` and `Message`. A connection allows one reader and one writer at a time. See [Interactive shell](https://docs.gmicloud.ai/agentbox-sdk/shell.md).

### sandbox.Stream

```go theme={null}
Stream(ctx) (*Stream, error)
```

Read with `stream.Next() (StreamEvent, bool)`, check `stream.Err()` when it returns false, and always call `stream.Close()`. `StreamEvent` has `Event`, `Data` and `Raw`.

### sandbox.CreateSnapshot

```go theme={null}
CreateSnapshot(ctx, CreateSnapshotParams{Name}) (*Snapshot, error)
```

Saves a running sandbox. See [Snapshots](#snapshots).

### sandbox.Metrics / MetricsTimeseries

Not supported on sandboxes. Return 501 (`IsNotSupportedError`).

### sandbox.Delete

```go theme={null}
Delete(ctx) error
```

Deletes the sandbox. This cannot be undone.

### Sandbox

| Method | Type | Description |
| - | - | - |
| `ID()` | `string` | Sandbox ID |
| `Status()` | `string` | Current status |
| `EndpointURL()` | `string` | Empty until an endpoint is assigned. Can still be empty for a short time after `running` |
| `AgentID()`, `AgentSlug()` | `string` | Owning Agent |
| `DisplayName()` | `string` | Display name |
| `InstanceType()` | `string` | Size ID |
| `IdcName()` | `string` | Data center ID |
| `LastError()` | `string` | Last error message |
| `Capabilities()` | `map[string]any` | Features enabled for this sandbox |
| `Metadata()` | `map[string]string` | Your labels |
| `ExpiresAt()` | `string` | Expiry time |
| `ExpiryPinned()` | `bool` | True when you set the expiry, so it does not renew automatically |
| `PausedAt()` | `string` | When the sandbox was paused |
| `PausedExpireAt()` | `string` | Deadline to resume before the sandbox is deleted |
| `SourceSnapshotID()` | `string` | Snapshot it launched from, if any |

### Execution

| Member | Type | Description |
| - | - | - |
| `ID()` | `string` | Execution ID |
| `Status()` | `string` | For example `running`, `succeeded`, `cancelled` |
| `ExitCode()` | `*int` | Exit code once finished, else nil |
| `Accepted` | `bool` | True when the command is still running |
| `Data` | `map[string]any` | Full result, including `stdout`, `stderr`, `stdout_truncated` and `stderr_truncated` |

## Snapshots

### sandbox.CreateSnapshot

```go theme={null}
CreateSnapshot(ctx, CreateSnapshotParams{Name}) (*Snapshot, error)
```

Saves a running sandbox; the snapshot starts as `creating`. `Name` is up to 255 characters; if empty, one is generated. Errors: 403 if you are not the sandbox's creator or an organization owner; 409 if the sandbox is not running.

### snapshot.WaitUntilReady

```go theme={null}
WaitUntilReady(ctx, WaitUntilReadyParams{Timeout, PollInterval}) error
```

Defaults: `Timeout` 300 seconds, `PollInterval` 2 seconds. Returns `*SnapshotFailed` if the status becomes `error`, `deleting` or `delete_failed`, and `*SnapshotWaitTimeout` if the timeout passes first.

### snapshot.Rename

```go theme={null}
Rename(ctx, name string) error
```

Only a `ready` or `error` snapshot can be renamed. `name` is 1 to 255 characters. Errors: 400 for an invalid name; 409 while still creating or being deleted.

### snapshot.Delete

```go theme={null}
Delete(ctx) error
```

Deletes asynchronously; status becomes `deleting`.

### Snapshot

| Method | Type | Description |
| - | - | - |
| `ID()` | `string` | Snapshot ID |
| `Name()` | `string` | Name |
| `Status()` | `string` | `creating`, `ready`, `error`, `deleting` or `delete_failed` |
| `StatusReason()` | `string` | Why it is `error` or `delete_failed` |
| `AgentID()` | `string` | Owning Agent |
| `SourceSandboxID()` | `string` | Sandbox it was saved from |
| `IdcName()` | `string` | Data center; sandboxes launched from it run here |
| `VCPU()`, `RAMMB()`, `DiskSizeMB()` | `int` | Size inherited at launch |
| `CreatedAt()`, `ReadyAt()` | `string` | Timestamps |

## Errors

Service errors are `*agentbox.APIError` with `StatusCode`, `Message`, `Code` and `Details`. Use `errors.As`, or the `Is*Error` helpers. See [Errors and limits](https://docs.gmicloud.ai/agentbox-sdk/errors-and-limits.md) for the full table.


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