smol-mcp

by smol-machines

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

create-machine

Create a virtual machine from an OCI image, start it, and wait until it is ready to run commands.

Instructions

Create a machine from an OCI image, start it, and wait until commands run in it.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cmd`	No	Workload command. Default keeps the container alive (sleep loop). Local only; the cloud create request has no such field.
`env`	No	Environment variables
`cpus`	No
`name`	No	Machine name. Omitted: an ephemeral mcp-<id> name, deleted when this server exits. A name without the mcp- prefix persists.
`image`	Yes	OCI image reference, e.g. alpine or python:3.12-alpine
`start`	No	Start and wait for readiness (default true)
`target`	No	Which fleet to talk to. local is smolvm serve on this host; cloud is smol cloud at SMOL_CLOUD_URL.	local
`network`	No	Egress mode. Default open, except run-once on cloud which is blocked. Local: a blocked machine whose image still has to be pulled from a registry is refused by the API; pass open or an allow-list for that create. Cloud: blocked is sent as an allow-list of an unroutable range.
`memoryMb`	No
`allowCidrs`	No	Egress allow-list of CIDR ranges. Overrides network.
`allowHosts`	No	Egress allow-list of hostnames. Overrides network. Local: sent as allowedHosts. Cloud: sent inside the same cidrs list the published schema names, alongside allowCidrs.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`ready`	Yes
`machine`	Yes
`ephemeral`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 9, 2026

TDQS

A3.5/5.0

Behavior3/5

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

With no annotations, the description must carry disclosure, and it does communicate the create/start/blocking-wait behavior. It does not mention ephemeral-vs-persistent naming, cloud/local target behavior, or that start can be disabled with start=false, so the disclosure is incomplete but not misleading at the default behavior level.

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

Conciseness5/5

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

A single sentence with no filler, presenting a clear sequence: create, start, wait. Every segment earns its place and the core operation is front-loaded.

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

Completeness3/5

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

This is an 11-parameter tool with local/cloud targets, network modes, and lifecycle implications, yet the description gives only the core flow. The rich input schema and output schema compensate substantially, but the tool-level context is still thinner than the complexity warrants.

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

Parameters3/5

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

Schema description coverage is high (82%), so the schema already explains most parameters. The tool description adds no extra parameter semantics beyond 'OCI image' and 'commands', which map to image and cmd but are already documented in the schema.

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

Purpose4/5

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

The description names a specific verb+resource ('create a machine from an OCI image') and adds behavioral detail (start it, wait until commands run). It separates the tool from obvious lifecycle siblings like stop-machine and delete-machine, though it does not explicitly distinguish it from run-once.

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

Usage Guidelines3/5

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

The intended use is implied: you want a machine created from an image, started, and ready for commands. It gives no explicit when-not-to-use guidance or alternative routing (e.g., run-once for one-shot tasks), so an agent must infer the boundary between this and run-once.

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

Install Server