Go SDK

The official Go SDK for MIOSA. Module path github.com/Miosa-osa/miosa-go/v2, version 2.2.0. Requires Go 1.21 or newer.

Install

go get github.com/Miosa-osa/miosa-go/v2

import miosa "github.com/Miosa-osa/miosa-go/v2"

Subpackages: github.com/Miosa-osa/miosa-go/v2/sandboxssh and github.com/Miosa-osa/miosa-go/v2/computeruse.

Authentication

client := miosa.NewClient("msk_u_...")

NewClient(apiKey, opts...) falls back to MIOSA_API_KEY when the key is empty. It also reads MIOSA_BASE_URL, MIOSA_ACCESS_TOKEN and MIOSA_TENANT. Defaults: base URL https://api.miosa.ai/api/v1, timeout 60s, 3 retries.

Options: WithBaseURL, WithHTTPClient, WithTimeout, WithMaxRetries, WithTenant, WithAccessToken, WithBillTo, WithDefaultHeader, WithUserAgent. Derive a scoped client with client.With(opts...), client.AsUser(token) or client.ForTenant(id).

ctx := miosa.WithBillToContext(context.Background(), "acme")

Sandboxes

Sandbox calls live on client.Sandboxes. The *Sandbox value is data, not a handle: it has no methods.

sbx, err := client.Sandboxes.Create(ctx, miosa.CreateSandboxInput{Name: "my-box"})
ok, err := client.Sandboxes.WaitUntilReady(ctx, sbx.ID, miosa.WaitUntilReadyOptions{})

Exec and files

res, err := client.Sandboxes.Exec(ctx, sbx.ID, miosa.ExecSandboxInput{Command: "node -v"})
events, err := client.Sandboxes.ExecStream(ctx, sbx.ID, miosa.ExecSandboxInput{Command: "npm run dev"})

Computer exec uses a WebSocket service:

out, err := computer.Exec.Bash(ctx, "ls -la")
out, err = computer.Exec.Python(ctx, "print(2 + 2)")

Files are computer-scoped. Scope an unscoped client with For:

files := client.Files.For(computer.ID)
_ = files.Upload(ctx, "./notes.txt", "/home/user/notes.txt")
data, _ := files.Download(ctx, "/home/user/notes.txt")
list, _ := files.List(ctx, "/home/user")
_ = files.Mkdir(ctx, "/home/user/data")
_ = files.Rename(ctx, "/home/user/a", "/home/user/b")

client.Files and computer.Files are the same service; computer.Files is pre-scoped. Methods: Upload, UploadReader, Download, DownloadTo, List, Stat, Mkdir, Rename, Copy, Chmod, Readdir, Delete, Export. FS(workingDir) returns a path-scoped ScopedFS.

Snapshots

Five surfaces.

snap, err := client.Sandboxes.CreateSnapshot(ctx, sbx.ID, miosa.CreateSandboxSnapshotInput{})
snaps, err := client.Sandboxes.ListSnapshots(ctx, sbx.ID)
_, err = client.Sandboxes.RestoreSnapshot(ctx, sbx.ID, snap.ID)

Computers

computer, err := client.Computers.Create(ctx, miosa.CreateComputerInput{Name: "dev-box"})
err = computer.Start(ctx)

The Computer handle adds Start, Stop, Restart, Destroy, Wait, Bash, Python, PreviewURL, PublicURL, Clone, Resize, Move, VncCredentials, StreamToken. Desktop: Screenshot (bytes), Click, LeftClick, DoubleClick, RightClick, Drag, Scroll, Type, Key, Hotkey, MoveMouse, Launch, Windows, Cursor, Clipboard, SetWallpaper, AccessibilityTree, ViewerURL.

Agents

client.Agents is settings and catalog only. There is no agent definition CRUD in this SDK.

settings, err := client.Agents.Settings(ctx, workspaceID)
catalog, err := client.Agents.Harnesses(ctx)

Not yet in this SDK: creating, listing, updating and deleting agent definitions.

Errors

Calls return ordinary Go errors. Inspect them with errors.As:

var apiErr *miosa.MiosaError
if errors.As(err, &apiErr) {
    if miosa.IsCode(err, "SANDBOX_STARTING") { /* retry */ }
    fmt.Println(apiErr.StatusCode, apiErr.Code, apiErr.RequestID)
}

MiosaError has StatusCode, Message, RequestID, Body, Code, Details, Retryable and RetryDelay, plus ShouldRetry(). Typed subclasses: AuthenticationError (401), InsufficientCreditsError (402), PermissionError (403), NotFoundError (404), ValidationError (422), RateLimitError (429, adds RetryAfter), ServerError (5xx), ConnectionError. Helpers: AsMiosaError, ErrorCode, IsCode, IsStarting, RetryAfter.