Agent orchestration

MIOSA lets you build agent systems where different agents use the right runtime for each part of the job.

• A sandbox agent writes code, edits files, runs commands, builds packages, generates artifacts, and exposes preview ports.
• A computer agent uses a real browser or desktop for visual checks, clicks, form fills, screenshots, uploads, and human handoff.
• A deployment agent promotes a verified sandbox workspace into a production deployment or App Engine app.
• Your orchestrator owns the task graph, model calls, permissions, retries, and user-facing progress stream.

The agents communicate through MIOSA-managed state: files, artifacts, events, preview URLs, screenshots, snapshots, and deployment records.

If you are building an agent-company product, treat this as the platform layer: agents are configured workers, devices are the execution substrate, connectors grant tools, and events/artifacts make the work visible to users. See What MIOSA agents can do, Configure an agent, and Agent devices for the product model before scaling the orchestration layer.

For the end-to-end product blueprint, including Polsia-style company operators, Cofounder (cofounder.co)-style department agents, Nebula-style virtual devices, Heuresis-style encoded workspaces, and prompt dispatch into devices, see Build an agent-company platform.

Scale model: from one agent to thousands

The same primitives work for one agent, one hundred agents, or thousands of agents, but the orchestration shape changes.

Do not start 10,000 independent sandboxes just because there are 10,000 logical agents. Most products should distinguish:

• Logical agent: a model/tool loop or task worker in your application.
• Runtime session: a sandbox or computer doing actual work.
• Workspace: the persistent filesystem, secrets, snapshots, usage, and attribution boundary.

Many logical agents can share a queue and borrow runtime sessions from a pool. Only the agents doing active code/browser work need a running sandbox or computer at that moment.

Prompt dispatch

At runtime, orchestration mostly means dispatching prompts into the right device and streaming the result back.

Create reusable runtime profiles for the agents your product supports. A profile can be tenant-wide or workspace-specific, and it can apply to sandbox workers, computer agents, or both.

Prompt-to-device flow should be explicit in your product backend:

user prompt
  -> product run record
  -> runtime profile resolution
  -> sandbox, computer, or BYOC/OpenComputer target
  -> scoped env and secret injection
  -> event stream
  -> files, artifacts, screenshots, previews, deployments

This lets Polsia-style operators, cofounder.co-style company operating systems, Nebula-style virtual devices, and Lovable/Replit/Genspark-style app builders share one UI contract even when they use different runtimes underneath.

Durable run groups

Use an Agent Run Group when one product task fans out into multiple child runs. The group gives your UI one durable record for counts, status, cancellation, child run lookup, and a group event stream.

user task
  -> agent run group
    -> child run: sandbox coder
    -> child run: sandbox tester
    -> child run: computer browser QA
    -> child run: deployment verifier
  -> artifacts, events, previews, screenshots, deployment URL

Current dispatch batches are capped at 100 child runs per API call. For hundreds or thousands of logical agents, queue the work in your backend and dispatch in batches against one or more groups. Keep a separate concurrency policy per tenant/workspace so one customer cannot consume the whole runtime pool.

The user-facing loop should be:

create group
  -> dispatch child runs
  -> stream /agent-run-groups/{id}/events
  -> show child run status and output as it happens
  -> list artifacts from completed child runs
  -> expose download/preview/deploy actions in your UI

This avoids opening one browser stream per child agent. Your product backend can subscribe to one group stream, normalize events into your own task timeline, and keep the UI live while sandbox and computer agents work in parallel.

When a child run uses a sandbox process-backed runtime, cancellation stops the recorded sandbox process instead of only changing run status. Use this for longer build, test, scrape, or artifact-generation tasks where the user may cancel from your UI.

If no explicit profile is passed, MIOSA resolves the workspace default profile first, then the tenant default profile. Request-level env values override non-secret profile defaults. Secret provider keys should come from managed secrets or connectors, not from profile env.

Recommended inheritance order:

Use managed secrets or connectors for anything that can spend money, access customer data, publish externally, or call a provider API. The run should receive a scoped MIOSA runtime token with tenant/workspace/user/run attribution, plus brokered provider access only for the endpoints the profile allows.

Every dispatch should record:

• prompt
• runtime or harness
• device id
• scoped credentials and connectors
• approval policy
• streamed events
• files, artifacts, screenshots, previews, or deployment outputs

The user experience should be the same whether the prompt is handled by OSA, Codex, Claude Code, Hermes, OpenCode, OpenClaw, or a custom runtime.

Exporting generated work

Agents should leave concrete outputs behind. For app builders and agent-company products, those outputs become the user’s deliverable: HTML, PDFs, DOCX files, CSV exports, screenshots, ZIPs, source patches, build logs, or deployment URLs.

Use declared artifact paths on Agent Runs when you expect a generated file:

{
  "sandbox_id": "sbx_code",
  "provider": "claude-code",
  "prompt": "Build the landing page and export /workspace/artifacts/site.html",
  "metadata": {
    "artifact_paths": ["/workspace/artifacts/site.html"]
  }
}

When the run completes, list and download artifacts:

miosa runs files <run-id> --json
miosa runs download-file <run-id> <file-id> --output ./site.html

MIOSA captures artifact bytes into managed storage when possible. If an artifact has persisted: true, your UI can keep showing a download button after the runtime stops. If it is not persisted, keep the sandbox or computer running until the file has been downloaded, published, or copied somewhere durable.

Use this split in your product UI:

Subagents inside sandboxes

You can also run subagents inside a sandbox. This is useful when the product wants a primary orchestrator to delegate work into an isolated workspace.

Account / tenant
  -> workspace
    -> orchestrator service
      -> sandbox
        -> subagent A: code editor
        -> subagent B: test runner
        -> subagent C: artifact generator
        -> subagent D: deploy verifier

The sandbox receives the environment and scoped credentials it needs. The subagents run inside /workspace, communicate through files, local processes, stdout, and MIOSA events, and report results back to the orchestrator.

Good uses for sandbox-hosted subagents:

• parallel code review agents inside one repo
• test generation plus test execution
• report generation workers
• artifact conversion workers
• dependency install/build/lint/test pipelines

Avoid using one sandbox as an uncontrolled multi-tenant process host. A sandbox should belong to one tenant/workspace/security boundary.

Sandbox-hosted orchestrators

The orchestrator does not always have to live in your backend. A MIOSA sandbox can be the root orchestrator workspace.

Tenant account
  -> workspace
    -> root orchestrator sandbox
      -> orchestration config
      -> local subagents
      -> child MIOSA sandboxes
      -> child MIOSA computers
      -> artifacts
      -> previews
      -> deployments

This pattern is useful for autonomous coding systems, research systems, artifact factories, and customer-owned agent runtimes. The root sandbox keeps the project files, agent configuration, run history, and local tooling. The orchestrator process inside that sandbox can call MIOSA to launch additional sandboxes or computers when it needs isolated workers.

Good examples of this pattern:

• root sandbox runs an agent manager
• child sandbox builds a web app
• child sandbox runs tests in parallel
• child computer opens the preview in a browser
• root sandbox collects screenshots, logs, and artifacts
• deploy agent publishes the verified result

The backend still owns tenant enforcement, billing, quotas, audit logging, and token minting. The sandbox-hosted orchestrator owns the local plan and execution strategy for that workspace.

Self-configuring agents

A sandbox-hosted orchestrator can customize its own setup. It can write config files, install packages, create worker scripts, generate task definitions, and adjust its local workflow as the project evolves.

Typical files inside /workspace:

/workspace
  agent.config.json
  miosa.runbook.md
  tasks/
    build.json
    test.json
    browser-qa.json
  agents/
    coder.ts
    tester.ts
    artifact-generator.py
  artifacts/
  logs/

Example agent.config.json:

{
  "workspace": "clinic-iq-demo",
  "defaultTemplate": "nextjs",
  "workers": {
    "coder": { "runtime": "local", "tools": ["files", "exec"] },
    "tester": { "runtime": "child-sandbox", "template": "miosa-sandbox" },
    "browserQa": { "runtime": "computer", "template": "ubuntu-browser" }
  },
  "limits": {
    "maxConcurrentWorkers": 8,
    "maxChildSandboxes": 4,
    "maxChildComputers": 1
  }
}

This lets an agent improve its own operating procedure without requiring every change to be hard-coded in the parent application.

Use these guardrails:

• keep config files visible in /workspace
• require explicit approval for quota or permission increases
• validate generated config before applying it
• cap child sandbox/computer creation
• write run events back to the product UI
• snapshot before major self-modification
• keep tenant admin credentials outside the sandbox

The goal is controlled autonomy: the agent can code and configure its own workspace, but MIOSA still enforces account boundaries and resource limits.

Credentials and account connection

Large agent systems should use scoped credentials instead of sharing one tenant admin key everywhere.

Tenant key
  -> server-side orchestrator only
  -> mints scoped workspace/user tokens
  -> tokens injected into sandbox/computer runtime
  -> subagents call MIOSA within their allowed scope

Typical environment injected into a runtime:

MIOSA_API_KEY=msk_scoped_...
MIOSA_TENANT_ID=...
MIOSA_WORKSPACE_ID=...
MIOSA_PROJECT_ID=...
MIOSA_USER_ID=...
MIOSA_RUN_ID=...

This lets every subagent be connected to the correct account while still giving the platform auditability, quotas, and revocation.

Important credential rules:

• Browser code never receives tenant admin keys.
• Sandboxes receive scoped runtime keys, not root account keys.
• Every token has workspace/project/user/run attribution.
• Every command, file write, preview, snapshot, and deploy is auditable.
• Quotas apply at tenant, workspace, user, and runtime-pool levels.

Queue and pool architecture

For high-scale orchestration, put a queue in front of MIOSA runtimes.

The queue owns backpressure. The runtime pool owns capacity. The orchestrator owns task assignment. MIOSA owns isolated execution.

Use this pattern when:

• thousands of user tasks may arrive at once
• agents do bursty work
• you need to cap spend
• you need per-customer fairness
• you need reliable retries and dead-letter queues
• users need live progress without polling every runtime directly

Mental model

The orchestrator should not make every agent share one messy machine. Instead, each runtime does the work it is good at and emits durable outputs that the next agent can consume.

Runtime selection

Example: app builder with browser QA

This is the pattern behind AI app-builder products. The user sees one task, but the orchestrator splits it across code, browser, and deployment agents.

Communication primitives

Use explicit handoffs instead of hidden shared memory.

The orchestrator should store these as run state so the frontend can replay what happened and the next agent has a clean input.

Product UI pattern

An orchestrated MIOSA product usually has three panels:

Good progress events include:

• plan created
• sandbox created or resumed
• file written
• command started
• stdout/stderr chunk
• command completed
• preview ready
• screenshot captured
• artifact created
• deployment started
• deployment ready

Minimal orchestrator shape

Sandbox-first code agent

The code agent should build inside the sandbox rather than building locally and uploading only at the end.

get_or_create persistent sandbox
write files under /workspace
run install/build/test inside sandbox
start preview server
stream stdout/stderr to product UI
snapshot after meaningful progress
publish when verified

This is the loop that makes MIOSA useful for coding agents.

Computer QA agent

Use a computer agent when the output needs visual/browser inspection.

open preview URL
capture screenshot
click through navigation
fill a form
test login or signup
capture errors
return screenshot and findings to orchestrator

The browser agent should not edit code directly. It reports findings. The sandbox agent patches the code.

Permissions and safety

Each agent should receive only the permissions it needs.

Use scoped workspace keys or server-side tokens. Do not put tenant admin keys in browser code.

When to use ADK vs your own orchestrator

Use the ADK when you want MIOSA’s built-in tool catalog and a simple agent loop.

Build your own orchestrator when you need:

• multiple agents with different responsibilities
• product-specific UI events
• custom approval steps
• background jobs and retries
• per-user quotas and billing
• white-label attribution
• durable run history in your product layer

The orchestrator is your product layer. MIOSA is the runtime layer.

See also