instabox-mcp

Create a machine

instabox_create_machine

Create a Linux Firecracker microVM from a template or snapshot, optionally waiting until it is running. Use it to launch isolated Debian machines with Docker and persistent /data storage.

Instructions

Create a Linux machine (Firecracker microVM, Debian, root, Docker, 20 GiB persistent /data; home is /data/home) from a template or one of your snapshots. Starts as an asynchronous operation; by default this waits until the machine is running. Give templateId OR snapshotId (neither: agent-browser). Leave size fields out for the default 4 vCPU / 8 GiB; other sizes must be ones your plan allows (see instabox_whoami allowedSpecs). Counts against your machine limit even when stopped or paused.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "instabox_create_machine"
  }
}

Input Schema

Name	Required	Description
`name`	No	1-63 lowercase letters, digits or '-', starting with a letter or digit; unique. Omit for box-<random>
`wait`	No	Wait for the operation to finish before returning (default true)
`vault`	No	false disables personal Vault delivery. Use false for machines that run untrusted code
`vcpus`	No	vCPUs of one of your allowed sizes
`memMiB`	No	Memory in MiB of one of your allowed sizes
`secrets`	No	Org proxy Secrets to enrol. SECURITY: code in the machine can send these to their allowed hosts
`metadata`	No	Up to 32 string labels. Stored in plain text: never put secrets here
`guestUser`	No	Linux user inside the machine (default 'user'). Fixed at creation
`envSecrets`	No	Org env Secrets (real values enter the machine and are readable by any process). Use sparingly
`snapshotId`	No	Create from this snapshot instead of a template
`templateId`	No	Template ID, e.g. universal or agent-browser
`desiredState`	No	'stopped' stops it once set up
`deleteAfterSeconds`	No	Delete the machine automatically after this long (60-86400). Good for throwaway sandboxes
`waitTimeoutSeconds`	No	Max seconds to wait (default 300)
`autoSuspendAfterSeconds`	No	Idle seconds before auto-pause (120-86400, 0 = never). Only honoured on accounts with manual lifecycle; otherwise fixed at 1800

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 1, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds real context beyond the annotations: creation is asynchronous and by default blocks until running, and machines count against the machine limit even when stopped or paused — the latter is a non-obvious cost the readOnlyHint/destructiveHint pair cannot convey. It stops short of stating that repeated identical calls each allocate a new machine (the non-idempotent consequence), which the idempotentHint=false annotation leaves implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, front-loaded with the outcome (what the machine is) before the routing rules and defaults. The parenthetical spec list in sentence one is heavy but every element is actionable, so nothing reads as filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter, zero-required mutation tool with no output schema, the description covers defaults, async behavior, sizing constraints, quota impact, and source selection. The main gap is return shape: since no output schema exists, it should say what comes back (machine object vs. an operation id when wait=false) so the agent knows whether to follow up with instabox_get_operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns more by stating the mutual exclusivity of templateId/snapshotId, the fallback when both are omitted, and the consequence of leaving vcpus/memMiB unset (default 4 vCPU / 8 GiB). It also notes home is /data/home, complementing the guestUser schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus concrete image details (Firecracker microVM, Debian, root, Docker, 20 GiB /data), so an agent knows exactly what gets created. It also distinguishes the three creation sources (template, snapshot, default agent-browser), separating it from siblings like instabox_update_machine or instabox_create_snapshot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the selection rule: 'Give templateId OR snapshotId (neither: agent-browser)', which is a when-to-use decision an agent would otherwise have to infer. It also points to instabox_whoami's allowedSpecs as the prerequisite for choosing sizes, naming the sibling that gates valid input.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.