Machines¶

A machine is a real Firecracker microVM. (In the SDK, a sandbox is a machine used create-run-destroy.)

Base URL: https://api.sistemo.io · all requests require authentication.

The machine object¶

{
  "id": "ee17cec6-b07d-4c03-b278-3fe161f04586",
  "account_id": "cf4629fa-3aac-4f2c-8c34-0b826fbc3edc",
  "name": "my-sandbox",
  "state": "running",
  "vcpus": 1,
  "memory_mb": 1024,
  "rootfs_size_gb": 10,
  "stack": "base",
  "private_ip": "10.200.0.2",
  "created_at": "2026-06-23T17:30:39Z",
  "started_at": "2026-06-23T17:30:43Z"
}

state is one of pending, provisioning, running, stopped, error, destroyed.

List machines¶

GET /v1/machines

Scope: read or full.

curl https://api.sistemo.io/v1/machines \
  -H "Authorization: Bearer $SISTEMO_API_KEY"

{ "machines": [ { "id": "…", "state": "running", … } ] }

Create a machine¶

POST /v1/machines

Scope: full. Blocks until the VM boots, then returns 201.

Field	Type	Default	Notes
`name`	string	`""`	Optional label
`vcpus`	int	`1`
`memory_mb`	int	`1024`
`rootfs_size_gb`	int	`10`
`stack`	string	`base`	See Images
`metadata`	object	`{}`	Arbitrary key/values
`snapshot_id`	string	—	Boot from a snapshot (placement pinned to that host)
`root_volume_id`	string	—	Boot an existing detached root volume

Optional header: Idempotency-Key: <unique> — retrying with the same key returns the existing machine instead of creating a duplicate.

curl -X POST https://api.sistemo.io/v1/machines \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-sandbox","stack":"base","vcpus":1,"memory_mb":1024}'

Returns the machine object with state: "running".

Quota

Each plan limits machines, vCPU, memory and storage independently. Exceeding any one returns 403 quota_exceeded, and the message names which limit bound — free up that resource (stop or delete a machine, delete a volume) and retry. GET /v1/quotas shows your limits and current usage. See Errors.

Get a machine¶

GET /v1/machines/{id}

Scope: read or full. Returns the machine object, or 404 if it doesn't exist / isn't yours.

Stop a machine¶

POST /v1/machines/{id}/stop

Scope: full. Soft stop — preserves the disk; billing drops to storage only.

Start a machine¶

POST /v1/machines/{id}/start

Scope: full. Boots a stopped machine from its saved spec (IP + volumes restored).

Delete a machine¶

DELETE /v1/machines/{id}
DELETE /v1/machines/{id}?preserve_storage=true
DELETE /v1/machines/{id}?delete_snapshots=true

Scope: full. Destroys the machine. By default its disk is reclaimed; pass preserve_storage=true to keep the root volume as a detached disk.

If the machine has snapshots and delete_snapshots is not true, the API returns 409 and deletes nothing. Pass delete_snapshots=true to remove snapshots first, then the machine.

curl -X DELETE "https://api.sistemo.io/v1/machines/$ID" \
  -H "Authorization: Bearer $SISTEMO_API_KEY"

Run a command¶

See Exec for POST /v1/machines/{id}/exec.