Quickstart
Two tracks. Pick one, finish it, then read the other.
- Track 1: Static deploy - write a small site inside a sandbox, preview it live, publish to a permanent URL. Good first pass through the whole platform.
- Track 2: Agent-driven build - drive a sandbox entirely through the API as your own AI agent (BYO LLM), then optionally screenshot a Computer.
Both tracks take five minutes.
Building a white-label product? If your goal is to ship a SaaS where your customers never see the MIOSA brand, start with the White-Label Integrator Guide instead. It covers per-user provisioning, custom domains, iframe embeds, webhooks, and usage billing from scratch.
Prerequisites
- A MIOSA account at miosa.ai with a workspace created.
2. A workspace API key: Dashboard → Settings → API Keys → New key. It starts with msk_. Export it:
export MIOSA_API_KEY="msk_live_..."3. SDK or tooling installed for your language
Track 1: Static deploy
Step 1 - Create a sandbox.
Step 2 - Write a small static site into /workspace.
Step 3 - Start a dev server so you can preview it.
Step 4 - Create a preview and open it.
Open the URL in your browser. You see your index.html served live from inside the sandbox.
Step 5 - Publish to production.
MIOSA freezes a source snapshot, runs a Builder to package the files, stores an immutable Release, and routes the Deployment URL to it. The sandbox remains alive and editable.
Step 6 - Make a change and republish.
Edit /workspace/index.html again and call deployments.publish once more. A new Version is created, the Release is new, and the Deployment’s active_version_id flips. The previous version is archived - roll back instantly by calling deployments.rollback.
Step 7 - (Optional) Attach a custom domain.
See Domains for the DNS setup. Short version: add a CNAME from your domain to the generated host, hit the verify endpoint, MIOSA issues a TLS certificate.
Step 8 - Clean up.
The sandbox is gone. The published deployment and its domain are unaffected - the Release is immutable and lives in object storage independently of the sandbox.
What you just did
| Step | What happened |
|---|---|
sandboxes.create | Created an isolated sandbox from the miosa-node template |
files.write | Wrote a file into /workspace inside the running VM |
exec | Ran a command inside the VM over the exec API |
previews.create | Opened a tunnel from a public hostname to port 3000 inside the VM |
deployments.publish | Froze source, ran Builder, stored Release, created Version, made it live |
sandbox.destroy | Terminated the VM; deployment is unaffected |
Track 2: Agent-driven build
This track treats the sandbox as an agent’s tool environment. You supply the intelligence (any LLM); the sandbox supplies isolated compute, file system, and execution.
Step 1 - Create a sandbox with external attribution.
If you’re embedding MIOSA in your own product, pass your user/project IDs so you can filter resources later.
Step 2 - Give your agent an exec tool.
The pattern below shows the structure. Substitute callYourLLM with your actual model call.
Step 3 - Let the agent write files directly.
Step 4 - Start the dev server, create a preview, stream it to your user.
The share_url is safe to put in an <iframe> in your end user’s browser. It expires after the configured TTL. Your msk_* key never leaves your server.
Step 5 - Take a screenshot of a Computer (optional).
If your agent needs to verify GUI output or run browser-based tasks, use a Computer instead of (or alongside) a Sandbox.
Step 6 - Publish what the agent built.
Step 7 - Filter all sandboxes for this customer.
Step 8 - Clean up.
What you just did
| Step | What happened |
|---|---|
| External attribution | Tagged every resource with your customer’s IDs - no MIOSA accounts needed for your end users |
| Exec as agent tool | Ran arbitrary shell commands inside an isolated VM from your agent loop |
files.write | Agent wrote generated code directly to the sandbox file system |
| Share token | Minted a browser-safe URL for preview embedding - workspace key stays server-side |
| Computer screenshot | Optionally gave the agent a real desktop with a vision-accessible screen |
deployments.publish | Shipped the agent’s output to a permanent immutable URL |
sandboxes.list with attribution | Queried only resources belonging to one customer - cross-tenant leakage impossible |
What’s next
- Add a real backend. Move from static to dynamic deploys with Publishing and a managed Postgres database.
- Authenticate end users. Auth-as-a-service adds a full JWT signup/login flow with one environment variable.
- Roll back a bad deploy. Rollback repoints the domain at an older version in seconds.
- Understand every primitive. Concepts is the canonical architecture reference.
- Build your own product on MIOSA. The Platform / White-label overview covers preview tokens, share URLs, tenant branding, per-user quotas, webhook subscriptions, and the audit log - everything introduced in 1.1.0.
- Drop in UI components.
@miosa/react,@miosa/vue, and@miosa/svelte(v0.2.0) provideMiosaPreview,MiosaTerminal,MiosaFileTree, andMiosaUsage- all handle token minting and SSE reconnect automatically. See UI Components. - See a full white-label example. The reference integration shows a complete platform embedding.
- Extend Claude Code with MIOSA skills. 5 pre-built skills at github.com/Miosa-osa/miosa-skills give Claude Code sandbox, computer, and deploy primitives. See Skills.
- API wire format. API Reference documents every endpoint.