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": "123e4567-e89b-12d3-a456-426614174000",
  "account_id": "123e4567-e89b-12d3-a456-4266141740ac",
  "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.

Field	Always present	Notes
`id` · `account_id`	yes	UUIDs
`name`	yes	`""` if you did not set one
`state`	yes	See above
`vcpus` · `memory_mb` · `rootfs_size_gb`	yes	The machine shape
`stack`	yes	The image it booted from
`created_at` · `updated_at`	yes	RFC 3339 UTC
`started_at` · `stopped_at`	no	Omitted until it has started / stopped
`last_seen_at`	no	Last time the host confirmed it
`private_ip`	no	Appears once the machine has an address
`metadata`	no	Whatever you sent at create
`git_repo`	no	Omitted unless set
`error_message`	no	Why a machine is in `error`. Read this before deleting it

Fields marked "no" are omitted entirely rather than sent as null, so test for presence, not for an empty value.

Placement is never in the response

Which host your machine runs on, and its address on our internal network, are not fields on this object and never will be. If you are looking for them to pin a machine somewhere, that is not something the API exposes.

List machines¶

GET /v1/machines

Scope: read or full.

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

{
  "machines": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "my-sandbox",
      "state": "running",
      "vcpus": 1,
      "memory_mb": 1024,
      "rootfs_size_gb": 10,
      "stack": "base",
      "created_at": "2026-06-23T17:30:39Z"
    }
  ]
}

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. A kept disk keeps billing storage until you delete the volume.

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.

Only these two parameters, and only real booleans

Both flags default to destroying, so this endpoint refuses what it does not understand instead of ignoring it. Any other query parameter — say retain_root=true — is a 400 and nothing is deleted, because a caller reaching for the wrong name is asking to keep the disk. A non-boolean value such as ?preserve_storage=yes is a 400 for the same reason: it must never quietly mean false.

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

Run a command¶

See Exec — POST /v1/machines/{id}/execs.