VMMs

Every hosted sandbox is a virtual machine. The VMM (virtual machine monitor) is the program on the host that runs it. RemoteHost runs two, QEMU (qemu) and Firecracker (firecracker), and each sandbox, environment and custom template names the one it runs on in its vmm field.

You do not have to choose. A create that names no VMM gets one from what it boots (its custom template, its environment, its environment template), else your org's default. Choose one when a workload needs what only that VMM can do.

On RemoteHost's hosted service, VMM choice is on and new sandboxes run on QEMU by default. To run one on Firecracker, pass --vmm firecracker to remote new or vmm: "firecracker" to the SDK or the API.

On a deployment where VMM choice is off, a create that names a vmm is refused with 400, GET /v1/orgs/{orgId}/vmms answers 404, and every sandbox runs on the default VMM. Responses carry vmm either way.

What each VMM can do

Each VMM declares what it can do, and GET /v1/orgs/{orgId}/vmms reports it as capabilities. A capability is what the VMM is able to do with a virtual machine. What RemoteHost does with it today is under Moves and Resizes.

The table is what each VMM is built to do. What your org can rely on is what the list answers: a capability is reported only when every host your sandboxes may be placed on that runs the VMM offers it.

Lazy restore. A sleeping sandbox wakes before all of its memory is loaded, and the rest loads as the sandbox reads it, so wake returns sooner.

Moves

RemoteHost moves sandboxes off a host before maintenance. Today every move pauses the sandbox, whichever its VMM: its memory is saved and restored on the new host, and it resumes there without rebooting. It keeps its id, so previews, terminals and everything else keyed by it follow. A paused move does not carry the sandbox's connections to the internet; reconnect after one, as you would after a network change.

Live migration is not on yet. Once it is, a running QEMU sandbox moves without pausing, its processes and memory going with it, when a host that can take it runs the same CPU model. It will not cover a sandbox an environment runs as, whose durable disk does not move live yet, or a Firecracker sandbox: those keep moving paused, as does any move that cannot go live.

Resizes

A resize of a running sandbox (POST /v1/sandboxes/{sandboxId}/resize, remote resize) applies live the same way on either VMM: where live resizing is enabled for the deployment, a sandbox created while it was enabled grows or shrinks without a restart, up to the ceiling it was created with. Anything else, a disk change included, is queued for the next wake, and the answer's applied says which happened. No resize uses hotplug yet, so the hotplug capabilities do not change what a resize does today.

Choose a VMM

vmm is a field of four creates:

Its value is qemu or firecracker. A response's vmm is a plain string: more VMMs may be added, so read it as a string and expect values you do not know.

A sandbox's VMM is, in order:

1. the create's vmm;
2. its custom template's, when it boots from one;
3. its environment template's, when it names one;
4. your org's default.

A custom template is built for one VMM, so a sandbox booting from it runs on that VMM: naming another is refused with 409 and the code vmm_mismatch. An environment template's VMM is only a default, which a create's vmm overrides.

An environment's VMM is fixed when the environment is made: its create's vmm, else its environment template's, else the VMM of the custom template that environment template boots from, else your org's default. As for a sandbox, the environment template's VMM is only a default, which the create's vmm overrides, while its custom template binds: a vmm other than the one that custom template is built for is refused with 409 vmm_mismatch. Every sandbox the environment runs as is on that VMM, and a fork runs on the VMM of the checkpoint it forks. An environment template that names a VMM and a custom template built for another is refused with 409 vmm_mismatch.

A custom template's VMM is its create's vmm, else your org's default. A rebuild keeps it; a build for another VMM is another template.

curl -X POST https://api.remotehost.ai/v1/orgs/$ORG/sandboxes \
  -H "Authorization: Bearer $REMOTEHOST_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "projectId": "'$PROJECT'", "agent": "claude", "vmm": "qemu" }'

The CLI takes the same choice as --vmm on remote new, remote claude and remote codex, and the TypeScript SDK as vmm on sandboxes.create.

Refusals

List the VMMs

curl https://api.remotehost.ai/v1/orgs/$ORG/vmms \
  -H "Authorization: Bearer $REMOTEHOST_API_KEY"

{
  "vmms": [
    {
      "id": "qemu",
      "label": "QEMU",
      "default": true,
      "availability": "available",
      "capabilities": {
        "liveMigration": true,
        "lazyRestore": true,
        "hotplug": { "cpu": true, "memory": true, "disk": false }
      }
    },
    {
      "id": "firecracker",
      "label": "Firecracker",
      "default": false,
      "availability": "available",
      "capabilities": {
        "liveMigration": false,
        "lazyRestore": true,
        "hotplug": { "cpu": false, "memory": false, "disk": false }
      }
    }
  ]
}

The list is your org's view, the default first, then the rest by id:

• default marks the one VMM a sandbox, environment or template that names none runs on.
• availability is available when a host your sandboxes may be placed on runs the VMM, installable when none runs it yet but one can install it, and unavailable when none can: naming it is refused with 409 vmm_unavailable.
• capabilities are the ones in the table above, by their field names.

It needs org.read on the org. Of API keys, only an org API key reaches it, and only in its own org; a sandbox's own Claims key and an agent token do not, and a key pinned to a workspace is refused with 403. An org you are not a member of, or another org's from an API key, answers 404, as an org that does not exist does.

An org with a self-hosted fleet sees its own fleet's hosts, so two orgs can get different answers: a VMM is available to it when its fleet's hosts run it.

The provider field

A sandbox's provider says how RemoteHost runs its machine, not which VMM it runs on. It is firecracker for every sandbox on RemoteHost's hosts or your self-hosted fleet, a QEMU sandbox included. Read vmm for the VMM.