miosa-sdk (Java)

Official Java SDK for MIOSA - the AI cloud platform for sandboxes, computers, deployments, and managed data.

Java 11+. Dependencies: Jackson Databind 2.17, JDK java.net.http.HttpClient.

Install

Maven

<dependency>
    <groupId>ai.miosa</groupId>
    <artifactId>miosa-sdk</artifactId>
    <version>0.6.0</version>
</dependency>

Gradle (Groovy)

implementation 'ai.miosa:miosa-sdk:0.6.0'

Gradle (Kotlin DSL)

implementation("ai.miosa:miosa-sdk:0.6.0")

Quickstart

import ai.miosa.sdk.MiosaClient;
import ai.miosa.sdk.resources.Computer;
import ai.miosa.sdk.types.ExecResult;

MiosaClient miosa = MiosaClient.builder("msk_live_...").build();

// Create a lightweight code sandbox, then run a command.
Computer sandbox = miosa.sandboxes().create("my-build", "small");
sandbox.start();
sandbox.waitUntilRunning();

ExecResult result = sandbox.exec().bash("echo 'hello from miosa'");
System.out.println(result.getOutput()); // hello from miosa

// Write and read a file
sandbox.files().writeFile("/workspace/hello.txt", "hello world");
String content = sandbox.files().readFile("/workspace/hello.txt");

System.out.println(sandbox.previewUrl(8000, "/"));

sandbox.destroy();

Product templates

Use templates() to discover the canonical product/template/size catalog. This is read-only product metadata. Use sandboxTemplates() only for tenant-owned custom sandbox template CRUD and builds.

List<ProductTemplate> computers = miosa.templates().list("computer");
ProductTemplate desktop = miosa.templates().get("miosa-desktop", "computer");
List<TemplateSizeReadiness> readiness =
    miosa.templates().readiness("miosa-desktop", "computer");

System.out.println(desktop.getDefaultSize());
System.out.println(readiness.get(0).getState());

Computers

// Create - three overloads: name+template+size, +metadata, +attribution
Computer computer = miosa.computers().create("agent", "miosa-desktop", "medium");

Computer withMeta = miosa.computers().create(
    "agent", "miosa-desktop", "medium",
    Map.of("team", "infra")
);

Computer attributed = miosa.computers().create(
    "agent", "miosa-desktop", "medium",
    null,
    Map.of(
        "external_workspace_id", "acme-corp",
        "external_user_id",      "user-42"
    )
);

// List / get / delete
List<ComputerInfo> all = miosa.computers().list();
List<ComputerInfo> page = miosa.computers().list(1, 25, "running");
Computer fetched = miosa.computers().get(computer.getId());
miosa.computers().delete(computer.getId());

// Lifecycle
computer.start();
computer.stop();
computer.restart();
computer.destroy();
computer.refresh();

Desktop viewer password

Authenticated MIOSA platform users should use the platform Desktop button or embedded desktop URL and do not need this password. The viewer password is only for raw external viewer links such as *.computer.miosa.ai/desktop/index.html. The rotate response returns the plaintext password once.

ComputerViewerPasswordStatus status =
    miosa.computers().viewerPassword(computer.getId());

ComputerViewerPasswordRotation rotated =
    computer.rotateViewerPassword();

System.out.println(rotated.getViewerPassword());

Desktop control

byte[] png = computer.desktop().screenshot();

computer.desktop().click(640, 400);
computer.desktop().click(640, 400, "right");
computer.desktop().doubleClick(640, 400);
computer.desktop().drag(100, 200, 400, 300);

computer.desktop().type("hello world");
computer.desktop().key("Return");
computer.desktop().key("ctrl+c");
computer.desktop().scroll("down", 3, 640, 400);

List<WindowInfo> windows = computer.desktop().windows();
computer.desktop().focusWindow(windows.get(0).getId());
computer.desktop().launch("firefox");

CursorInfo cursor = computer.desktop().cursor();

Exec

ExecResult result = computer.exec().bash("ls -la /workspace");
System.out.println(result.getOutput());
System.out.println(result.getExitCode()); // 0

// With timeout (seconds)
ExecResult timed = computer.exec().bash("long-running.sh", 120);

ExecResult py = computer.exec().python("import sys; print(sys.version)");

File operations

// Write / read / download
computer.files().writeFile("/workspace/app.py", "print('hi')");
String text  = computer.files().readFile("/workspace/app.py");
byte[] raw   = computer.files().download("/workspace/app.py");

// List / stat / mkdir / rename
List<FileInfo> entries = computer.files().list("/workspace");
FileStat stat = computer.files().stat("/workspace/app.py");
computer.files().mkdir("/workspace/output");
computer.files().rename("/workspace/old.py", "/workspace/new.py");

// Export (signed download URL)
FileExportResult export = computer.files().export("/workspace/report.pdf");
System.out.println(export.getUrl());

AI agent sessions

AgentSession session = computer.osa().runAgent(
    "Open a browser and navigate to miosa.ai"
);
for (AgentEvent event : computer.osa().streamEvents(session.getId())) {
    System.out.println(event.getType() + ": " + event.getData());
}

Error handling

import ai.miosa.sdk.exceptions.*;

try {
    Computer c = miosa.computers().get("cmp_doesnt_exist");
} catch (NotFoundException e) {
    System.out.println("Not found: " + e.getMessage());
} catch (RateLimitException e) {
    System.out.println("Rate limited; retry after " + e.getRetryAfter() + "s");
} catch (AuthException e) {
    System.out.println("Auth failed: " + e.getMessage());
} catch (InsufficientCreditsException e) {
    System.out.println("Out of credits");
} catch (MiosaException e) {
    System.out.println("API error " + e.getStatusCode() + ": " + e.getMessage());
}

Exception hierarchy: MiosaException > AuthException (401/403), NotFoundException (404), RateLimitException (429), ValidationException (422), InsufficientCreditsException (402), ServerException (5xx), NetworkException, TimeoutException.

The SDK retries 429 and 5xx automatically (3 retries, exponential backoff, respects Retry-After).

Configuration

MiosaClient miosa = MiosaClient.builder(System.getenv("MIOSA_API_KEY"))
    .baseUrl("https://api.miosa.ai/api/v1")
    .timeout(60_000)
    .maxRetries(5)
    .build();

Option	Env var	Default
apiKey	MIOSA_API_KEY	required
baseUrl	MIOSA_BASE_URL	https://api.miosa.ai/api/v1
timeout	none	30 000
maxRetries	none	3

Links

• Full documentation
• Quickstart
• GitHub
• Contact

License

MIT