microagent dispatch

Last updated: 2026-06-24

microagent dispatch <image> [command arg...] [flags]
microagent dispatch --image <ref> --exec "<command>" [flags]
microagent dispatch --file <agent.yaml> [flags]

dispatch boots a throwaway microVM under the egress guardrails you choose, runs one command, and returns its result and a summary of what it reached on the network — the mediator-written audit — then tears the workspace down. It is the one-call “delegate this to an isolated machine and tell me what it did” primitive: ideal for handing untrusted, dangerous, or parallel work to its own machine.

It is one-shot: nothing persists. Use run when you want the same disposable boot but not the audit receipt, or create when you want a named workspace that survives.

Why dispatch

The second half of the return value is the point. The egress audit is written by the mediator, outside the guest’s control, so the summary is a trustworthy record of where the task actually connected — a prompt-injected or otherwise-rogue task can neither forge nor suppress it. Under the default guarded mode the mediator records allowed public destinations too (not just denials), so the summary reflects real behavior without needing strict.

Pair it with credential swap: the guest can use a provider API key it can never read, because the real secret is injected host-side at the mediator.

Examples

Run a command and throw the VM away, keeping the audit receipt:

microagent dispatch docker.io/library/python:3.12 python -c 'print(2+2)'

Delegate work that uses a provider key the guest never holds:

microagent dispatch --egress strict --cred-swap anthropic \
  docker.io/library/python:3.12 python agent.py

Run an Agentfile — a build-free agent recipe — in one call:

microagent dispatch --file examples/agents/openai-agent/agent.yaml

With --json the result and audit are machine-readable:

{
  "workspace": "dispatch-1730000000000000000",
  "final_state": "stopped",
  "result": { "exit_code": 0, "stdout": "4\n" },
  "audit": { "decision_count": 3, "allow_by_host": { "example.com": 1 } }
}

Flags

dispatch shares the workspace flagset with run; the most relevant:

Flag	Description
--image <ref>	OCI image to boot (or the first positional argument)
--exec <command>	Command to run (alternative to the positional command)
--file <path>	Workspace spec / Agentfile; flags override matching spec fields
--network <mode>	Network mode: user (default) or isolated
--timeout <seconds>	Maximum wall-clock time before the task is killed
--egress <mode>	Egress mediation mode: guarded (default; deny the inside, allow public), strict (deny non-allowlisted), or off
--egress-allow <host>	Allowlisted egress destination (TLS-intercepted). Repeatable; an exact host or a .suffix matching the apex and subdomains
--egress-passthrough <host>	Allowed egress destination that is not TLS-intercepted. Repeatable. For cert-pinned / mTLS endpoints
--egress-policy <path>	Egress policy file (.yaml/.yml/.json) declaring allow[] / passthrough[]; unioned with the flags. Requires --egress guarded or strict
--egress-swap-config <path>	Credential-swap config (YAML): for an allowlisted, intercepted host the mediator injects the real credential host-side so the guest never holds it. Requires --egress guarded or strict. See credential swap
--cred-swap PROVIDER[=ref]	Shorthand for a credential swap against a built-in provider (anthropic, openai, gemini, groq, openrouter, deepseek): allowlists the provider host and injects its API key host-side so the guest never holds it. The optional =ref is a reference (env:NAME / file:PATH / vault:PATH), never a literal secret. Repeatable; requires --egress guarded or strict. See credential swap
--secret NAME=<scheme>:<ref>	Deliver a secret to the guest tmpfs /run/secrets. Repeatable. See secret
--secret-on-demand NAME=<scheme>:<ref>	Declare an on-demand secret fetched at runtime, never written to tmpfs. Repeatable
--secrets-env-file <path>	Deliver every key in a dotenv file as a secret
--secrets-audit	Append every secret access to the workspace audit log
--state-dir <dir>	State directory (default ~/.microagent/)

See global flags for --json/--text/--output/--supervisor. The full shared flag reference (resources, model pairing, storage, networking) is documented under run.

Related

• run - the disposable one-shot boot without the audit receipt
• spec - the workspace spec / Agentfile format --file accepts
• egress - read a workspace’s recorded egress audit decisions
• credential swap - inject a key the guest never holds