@miosa/sdk 1.2.4 → 1.2.6

package/README.md

@@ -29,8 +29,11 @@ import { Miosa } from "@miosa/sdk";
 
 const miosa = new Miosa({ apiKey: "msk_live_..." });
 
-// Boot a sandbox, write a file, run a command
-const sbx = await miosa.sandboxes.create({ name: "my-build" });
+// Create or resume a persistent sandbox workspace, then work inside it.
+const sbx = await miosa.sandboxes.createAgentWorkspace({
+  name: "my-build",
+  externalWorkspaceId: "customer-workspace-123",
+});
 
 await sbx.files.write("/workspace/hello.ts", `console.log("hello from miosa")`);
 const result = await sbx.exec("npx tsx /workspace/hello.ts");
@@ -40,7 +43,9 @@ console.log(result.stdout); // hello from miosa
 const url = await sbx.expose(3000);
 console.log(url); // https://3000-<slug>.sandbox.miosa.ai
 
-await sbx.destroy();
+// Keep progress. Pause preserves the workspace so the next session can resume.
+await sbx.snapshots.create("after-hello-world");
+await sbx.pause();
 ```
 
 ## What's included
@@ -61,6 +66,53 @@ await sbx.destroy();
 | `miosa.completions` | OpenAI-compatible chat completions with SSE streaming |
 | `miosa.embeddings` | OpenAI-compatible embedding vectors |
 
+## Agent workspaces
+
+For AI builders, code assistants, and white-label agent products, the sandbox
+is the development machine. Do not run builds on the user's laptop and upload
+the result as the primary flow. Create or resume a stable sandbox workspace,
+write files under `/workspace`, run package installs/tests/builds inside the
+sandbox, expose previews from the sandbox, and publish from that sandbox.
+
+```ts
+const sbx = await miosa.sandboxes.getOrCreate({
+  name: "acme-marketing-page",
+  templateId: "miosa-sandbox",
+  persistent: true,
+  timeoutSec: 86_400,
+  idleTimeoutSec: 1800,
+  snapshotExpirationDays: 30,
+  keepLastSnapshots: 1,
+  externalWorkspaceId: "acme",
+  externalUserId: "jane",
+  waitUntilReady: true,
+});
+
+await sbx.files.writeMany([
+  { path: "/workspace/package.json", content: `{"scripts":{"dev":"vite --host 0.0.0.0"}}` },
+  { path: "/workspace/index.html", content: `<main id="app"></main>` },
+]);
+
+for await (const event of sbx.exec.stream("cd /workspace && npm install && npm run dev -- --port 3000")) {
+  console.log(event);
+}
+
+const preview = await sbx.previews.create(3000);
+console.log(preview.url);
+```
+
+`createAgentWorkspace()` is a convenience wrapper around `getOrCreate()` with
+builder defaults: a 24-hour activity cap, thirty-minute idle snapshot/pause,
+readiness waiting, 30-day snapshot-retention metadata, keep-last-snapshot
+metadata, and metadata that marks the sandbox as an agent workspace.
+
+That mirrors the Vercel-style persistent-sandbox model without keeping CPU
+running forever: activity extends the running session, idle workspaces are
+checkpointed and paused, and later sessions resume from the checkpoint. Use
+`extend(86_400)` before long builds, `pause()` when the user is done for now,
+`resume()` for the next session, `snapshots.create()` for manual checkpoints,
+and `destroy()` only when the workspace should be permanently deleted.
+
 ## Sandbox sub-resources
 
 Every `Sandbox` instance exposes composable sub-resources:
@@ -126,6 +178,26 @@ const deployment = await sbx.deploy({
 });
 ```
 
+For workspace Docker Deploy, publish from the same sandbox but choose the
+Docker Deploy target:
+
+```ts
+const deployment = await sbx.deployDocker({
+  name: "lead-magnet",
+  path: "/workspace",
+  buildCommand: "npm run build",
+  runCommand: "npm start",
+  port: 3000,
+});
+
+console.log(deployment.url ?? deployment.public_url);
+```
+
+Docker Deploy runs app containers inside the workspace's dedicated MIOSA
+Docker Deploy appliance VM. It is separate from normal MIOSA dynamic runtime
+VMs and is useful when a workspace needs many small apps, funnels, lead
+magnets, APIs, or client sites.
+
 Always display the server-returned `url` / `public_url`. Do not hardcode
 `preview.miosa.app`, `api.miosa.app`, or `<tenant>.miosa.app`.