Go SDK reference - GMI Cloud Documentation

go get github.com/GMISWE/agentbox-sdk-go

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.

Client

agentbox.NewClient

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

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

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

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

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

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

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

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

Launch(ctx, slug string, LaunchParams) (*Sandbox, error)

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

client.Sandboxes.List

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

Get(ctx, sandboxID string) (*Sandbox, error)

sandbox.WaitUntilRunning

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

Refresh(ctx) error

sandbox.SetTimeout

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

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

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

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

GetExecution(ctx, executionID string) (*Execution, error)
CancelExecution(ctx, executionID string) (*Execution, error)

sandbox.UploadFile

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

DownloadFile(ctx, sandboxPath string) (*FileDownload, error)

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

sandbox.Shell

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.

sandbox.Stream

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

CreateSnapshot(ctx, CreateSnapshotParams{Name}) (*Snapshot, error)

Saves a running sandbox. See Snapshots.

sandbox.Metrics / MetricsTimeseries

Not supported on sandboxes. Return 501 (IsNotSupportedError).

sandbox.Delete

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

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

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

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

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 for the full table.

​Client

​agentbox.NewClient

​client.Eligibility

​Catalog

​client.Idcs.List

​client.Products.List

​Agents

​client.Agents.Create

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

​Agent

​agent.Launch

​agent.BuildLogs

​Sandboxes

​client.Sandboxes.Launch

​client.Sandboxes.List

​client.Sandboxes.Get

​sandbox.WaitUntilRunning

​sandbox.Refresh

​sandbox.SetTimeout

​sandbox.Pause

​sandbox.Resume

​sandbox.Execute

​sandbox.GetExecution / CancelExecution

​sandbox.UploadFile

​sandbox.DownloadFile

​sandbox.Shell

​sandbox.Stream

​sandbox.CreateSnapshot

​sandbox.Metrics / MetricsTimeseries

​sandbox.Delete

​Sandbox

​Execution

​Snapshots

​sandbox.CreateSnapshot

​snapshot.WaitUntilReady

​snapshot.Rename

​snapshot.Delete

​Snapshot

​Errors

Client

agentbox.NewClient

client.Eligibility

Catalog

client.Idcs.List

client.Products.List

Agents

client.Agents.Create

client.Agents.Get / List / Update / Delete

Agent

agent.Launch

agent.BuildLogs

Sandboxes

client.Sandboxes.Launch

client.Sandboxes.List

client.Sandboxes.Get

sandbox.WaitUntilRunning

sandbox.Refresh

sandbox.SetTimeout

sandbox.Pause

sandbox.Resume

sandbox.Execute

sandbox.GetExecution / CancelExecution

sandbox.UploadFile

sandbox.DownloadFile

sandbox.Shell

sandbox.Stream

sandbox.CreateSnapshot

sandbox.Metrics / MetricsTimeseries

sandbox.Delete

Sandbox

Execution

Snapshots

sandbox.CreateSnapshot

snapshot.WaitUntilReady

snapshot.Rename

snapshot.Delete

Snapshot

Errors