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 Docker Deploy 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.

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.

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:

• 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:

• 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 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 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

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

See also