@miosa/adk

Agent Development Kit for MIOSA. Build LLM agents that natively use MIOSA sandboxes, desktops, and deploys — with the tool-call loop already wired.

npm install @miosa/adk

30-second example

import { Agent, groqProvider } from "@miosa/adk";

const agent = new Agent({
  provider: groqProvider({
    apiKey: process.env.GROQ_API_KEY!,
    model: "moonshotai/kimi-k2-instruct-0905",
  }),
  miosaApiKey: process.env.MIOSA_API_KEY!,
});

const result = await agent.run({
  prompt:
    "Create a MIOSA sandbox workspace, write a Python hello-world to /workspace/hello.py, run it, snapshot it, then pause the sandbox.",
  maxIterations: 10,
});

console.log(result.finalText);
console.log(`Took ${result.steps.length} turns. Stopped because: ${result.stopReason}`);

That's it. The agent will create or resume a persistent sandbox workspace, write the file inside /workspace, run it inside the sandbox, checkpoint it, pause it, and return. No tool-loop boilerplate.

The default sandbox tool policy is designed for builder workflows: a 24-hour activity cap, thirty-minute idle snapshot/pause, and snapshot-retention metadata. This is not an always-running VM. CPU stops when the workspace is paused; the filesystem is preserved for resume. Use destroy_sandbox only when the user really wants to delete the workspace.

ADK vs SDK — what's the difference

• @miosa/sdk is a thin wrapper around the MIOSA REST API. You call methods directly (client.computers.create(...)).
• @miosa/adk is the agent layer. It bakes in the MIOSA tool catalogue (sandbox / desktop / files / exec) and the model-loop, so an LLM can drive MIOSA end-to-end with zero glue from you.

Use the SDK when you're writing application code that talks to MIOSA. Use the ADK when you're building an agent that should use MIOSA as its execution substrate.

Built-in MIOSA tools

When you pass miosaApiKey, the agent gets these tools out of the box:

| Tool | Does | |------|------| | create_sandbox | Create/resume a persistent code sandbox workspace (Python + Node + shell). | | create_computer | Boot a general MIOSA computer for GUI, services, previews, files. | | create_desktop | Boot a full Xfce desktop (KasmVNC). | | list_sandboxes | List sandbox workspaces, then desktop computers when relevant. | | get_sandbox / get_computer | Fetch one sandbox or computer by id. | | exec | Run a bash command. | | exec_python | Run a Python snippet inline. | | read_file | Read a file from the sandbox/computer filesystem. | | write_file | Write a file inside the sandbox/computer filesystem. | | list_files | List a directory inside the sandbox/computer filesystem. | | preview_url | Get the public HTTPS URL for a service running on a port. | | pause_sandbox / resume_sandbox | Stop/resume a persistent workspace without deleting files. | | extend_sandbox | Extend the activity timeout before long installs, builds, or agent tasks. | | snapshot_sandbox | Create a checkpoint after dependency install or a good edit. | | deploy_sandbox | Publish to normal MIOSA Deploy. | | deploy_docker | Publish to the workspace App Engine appliance. | | destroy_sandbox / destroy_computer | Delete a computer and release resources. |

Tool defaults are configurable:

import { Miosa } from "@miosa/sdk";
import { miosaTools } from "@miosa/adk";

const tools = miosaTools({
  client: new Miosa({ apiKey: process.env.MIOSA_API_KEY! }),
  sandboxTemplate: "miosa-sandbox",
  computerTemplate: "miosa-desktop",
  defaultSize: "medium",
  workspaceTimeoutSec: 86_400,
  idleTimeoutSec: 1800,
  allowDestroy: false,
});

Get an API key at https://miosa.ai/dashboard/api-keys.

Custom tools

Compose your own tool catalogue alongside (or instead of) the MIOSA tools:

import { Agent, anthropicProvider, miosaTools, type Tool } from "@miosa/adk";
import { Miosa } from "@miosa/sdk";

const miosa = new Miosa({ apiKey: process.env.MIOSA_API_KEY! });

const sendSlack: Tool = {
  name: "send_slack",
  description: "Post a message to the #builds Slack channel.",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"],
  },
  async execute(args) {
    // ... your Slack call ...
    return `Sent: ${args["text"]}`;
  },
};

const agent = new Agent({
  provider: anthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! }),
  tools: [...miosaTools({ client: miosa }), sendSlack],
});

Providers

@miosa/adk ships with native tool-call providers for hosted and local models:

| Provider | Factory | Import | |---|---|---| | Anthropic | anthropicProvider | @miosa/adk or @miosa/adk/providers/anthropic | | OpenAI | openAIProvider | @miosa/adk or @miosa/adk/providers/openai | | Google Gemini | geminiProvider | @miosa/adk or @miosa/adk/providers/gemini | | Groq | groqProvider | @miosa/adk or @miosa/adk/providers/groq | | DeepSeek | deepSeekProvider | @miosa/adk or @miosa/adk/providers/deepseek | | OpenRouter | openRouterProvider | @miosa/adk or @miosa/adk/providers/openrouter | | Together | togetherProvider | @miosa/adk or @miosa/adk/providers/together | | Fireworks | fireworksProvider | @miosa/adk or @miosa/adk/providers/fireworks | | Mistral | mistralProvider | @miosa/adk or @miosa/adk/providers/mistral | | Cerebras | cerebrasProvider | @miosa/adk or @miosa/adk/providers/cerebras | | Perplexity | perplexityProvider | @miosa/adk or @miosa/adk/providers/perplexity | | xAI | xAIProvider | @miosa/adk or @miosa/adk/providers/xai | | Surplus Intelligence | surplusProvider | @miosa/adk or @miosa/adk/providers/surplus | | MIOSA Intelligence / model routes | miosaRouteProvider | @miosa/adk or @miosa/adk/providers/miosa | | Ollama | ollamaProvider | @miosa/adk or @miosa/adk/providers/ollama | | LM Studio | lmStudioProvider | @miosa/adk or @miosa/adk/providers/lmstudio |

Most hosted providers expose an OpenAI-compatible chat completions endpoint, so the ADK uses a lightweight fetch adapter instead of forcing every vendor SDK into your install.

import {
  Agent,
  openAIProvider,
  geminiProvider,
  ollamaProvider,
  surplusProvider,
  miosaRouteProvider,
  openAICompatibleProvider,
} from "@miosa/adk";

const openai = openAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4.1",
});

const gemini = geminiProvider({
  apiKey: process.env.GEMINI_API_KEY!,
  model: "gemini-2.5-pro",
});

const local = ollamaProvider({
  model: "qwen2.5-coder:32b",
});

const surplus = surplusProvider({
  apiKey: process.env.SURPLUS_API_KEY!,
  model: "claude-opus-4.8",
});

const miosaManaged = miosaRouteProvider({
  miosaApiKey: process.env.MIOSA_API_KEY!,
  model: "optimal",
});

const futureRoute = miosaRouteProvider({
  miosaApiKey: process.env.MIOSA_API_KEY!,
  model: "route:cheap-claude-code",
});

const custom = openAICompatibleProvider({
  name: "internal-router",
  baseUrl: "https://llm.example.com/v1/chat/completions",
  apiKey: process.env.INTERNAL_LLM_KEY,
  model: "best-agent-model",
});

const agent = new Agent({ provider: openai, miosaApiKey: process.env.MIOSA_API_KEY! });

Sandbox Builder Examples

The primary ADK use case is letting customers build their own AI builders: website builders, app builders, artifact builders, slide deck builders, and other tools that need a real filesystem, shell, dev server, and preview URL.

See BUILDER_GUIDE.md for the full “build your own Lovable with MIOSA sandboxes” product pattern.

Runnable examples live in examples/:

| Example | What it builds | |---|---| | sandbox-website-builder.ts | A Lovable-style website builder flow. | | sandbox-app-builder.ts | A small app builder with a dev server and preview. | | sandbox-artifact-builder.ts | Markdown/doc artifacts written to /workspace/artifacts. | | sandbox-slide-deck-builder.ts | A deck workspace under /workspace/deck. |

Each example keeps the sandbox alive with miosaTools: { allowDestroy: false } so your product can show the preview, inspect files, pause/resume the workspace, or publish later.

The model should treat a MIOSA sandbox like the actual development machine: write source files under /workspace, run package managers/tests/builds inside the sandbox, start dev servers inside the sandbox, stream logs/tool results back to your UI, and only publish after a sandbox preview passes a smoke check. Local upload is still useful for importing an existing repo, but it is not the primary agent loop.

Streaming step events

const result = await agent.run({
  prompt: "...",
  onStep: (step) => {
    console.log(`[turn ${step.index}] text: ${step.text}`);
    for (const call of step.toolCalls) {
      console.log(`  → ${call.name}(${JSON.stringify(call.input)}) → ${call.output.slice(0, 80)}`);
    }
  },
});

License

MIT.