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.3.0</version>
</dependency>

Gradle (Groovy)

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

Gradle (Kotlin DSL)

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

Quickstart

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

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

// Create a computer, run a command
Computer computer = miosa.computers().create("my-build", "miosa-sandbox", "small");
computer.start();
computer.waitUntilRunning();

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

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

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

computer.destroy();

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 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());
}

Async (CompletableFuture)

CompletableFuture<Computer> future = miosa.computers().createAsync(
    "async-build", "miosa-sandbox", "small"
);
future.thenAccept(c -> {
    c.exec().bash("echo async");
    c.destroy();
});

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()
    .apiKey(System.getenv("MIOSA_API_KEY"))
    .baseUrl("https://api.miosa.ai/api/v1")
    .timeoutMs(60_000)
    .maxRetries(5)
    .build();

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

Links

• Full documentation
• Quickstart
• GitHub
• Contact

License

MIT