{
  "openapi": "3.1.0",
  "info": {
    "title": "SmolVM",
    "summary": "Disposable computers for AI agents, over HTTP.",
    "version": "0.1.0"
  },
  "paths": {
    "/sandboxes": {
      "get": {
        "summary": "List Sandboxes",
        "description": "List the sandboxes discoverable on the host.\n\nReturns only sandboxes owned by this API process.",
        "operationId": "listSandboxes",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/SandboxResponse"
                  },
                  "type": "array",
                  "title": "Response Listsandboxes"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Sandbox",
        "description": "Create, boot, and register a new sandbox.\n\nBuilds a :class:`~smolvm.SmolVM` from the request's auto-config\nfields, starts it, stores it in the registry under its id, and\nreturns the client-safe view.",
        "operationId": "createSandbox",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSandboxRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request was invalid or the sandbox failed to boot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/sandboxes/{sandbox_id}": {
      "get": {
        "summary": "Get Sandbox",
        "description": "Return the current state of a sandbox.\n\nA sandbox not owned by this API process yields a 404.",
        "operationId": "getSandbox",
        "parameters": [
          {
            "name": "sandbox_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sandbox Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxResponse"
                }
              }
            }
          },
          "404": {
            "description": "No sandbox with that id exists on the host.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "The sandbox exists but could not be reconnected.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete Sandbox",
        "description": "Stop the sandbox, release its resources, and forget it.\n\nEvicts the facade from the registry so its id stops resolving \u2014\nthe write-through delete the registry-as-cache model needs.",
        "operationId": "deleteSandbox",
        "parameters": [
          {
            "name": "sandbox_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sandbox Id"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "404": {
            "description": "No sandbox with that id exists on the host.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "The sandbox could not be reconnected or deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/sandboxes/{sandbox_id}/desktop": {
      "get": {
        "summary": "Get Sandbox Desktop",
        "description": "Return a sanitized loopback desktop endpoint without opening it.",
        "operationId": "getSandboxDesktop",
        "parameters": [
          {
            "name": "sandbox_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sandbox Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesktopResponse"
                }
              }
            }
          },
          "404": {
            "description": "The sandbox was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "No running desktop is available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/sandboxes/{sandbox_id}/exec": {
      "post": {
        "summary": "Exec Command",
        "description": "Run a command inside a sandbox and return its result.\n\nResolves the sandbox (reconnecting on a registry miss), then runs\nthe command over the facade's cached SSH channel.",
        "operationId": "execCommand",
        "parameters": [
          {
            "name": "sandbox_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Sandbox Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExecRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExecResponse"
                }
              }
            }
          },
          "404": {
            "description": "No sandbox with that id exists on the host.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "The sandbox could not be reconnected, or the command could not run.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateSandboxRequest": {
        "properties": {
          "image": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Image",
            "description": "Image reference to boot (S3 ref, file:// URI, or path). Omit to use the default built-in image."
          },
          "os": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "alpine",
                  "ubuntu",
                  "windows",
                  "macos"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Os",
            "description": "Guest OS for auto-configured images: 'alpine', 'ubuntu', 'windows', or 'macos'."
          },
          "memory": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 16384.0,
                "minimum": 128.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Memory",
            "description": "Guest memory in MiB."
          },
          "disk_size": {
            "anyOf": [
              {
                "type": "integer",
                "maximum": 262144.0,
                "minimum": 1.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Disk Size",
            "description": "Guest disk size in MiB."
          },
          "backend": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "firecracker",
                  "qemu",
                  "libkrun",
                  "vz"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Backend",
            "description": "Runtime backend override: 'firecracker', 'qemu', 'libkrun', or 'vz'."
          }
        },
        "type": "object",
        "title": "CreateSandboxRequest",
        "description": "Request body for creating (and booting) a sandbox.\n\nMirrors the auto-config arguments of the :class:`smolvm.SmolVM`\nconstructor. All fields are optional; omitting them boots the\ndefault Alpine micro-VM."
      },
      "DesktopResponse": {
        "properties": {
          "protocol": {
            "type": "string",
            "const": "vnc",
            "title": "Protocol",
            "default": "vnc"
          },
          "host": {
            "type": "string",
            "enum": [
              "127.0.0.1",
              "localhost",
              "::1"
            ],
            "title": "Host"
          },
          "port": {
            "type": "integer",
            "maximum": 65535.0,
            "minimum": 1.0,
            "title": "Port"
          },
          "viewer_url": {
            "type": "string",
            "title": "Viewer Url"
          }
        },
        "type": "object",
        "required": [
          "host",
          "port",
          "viewer_url"
        ],
        "title": "DesktopResponse",
        "description": "A sanitized loopback display endpoint for a running sandbox."
      },
      "ErrorResponse": {
        "properties": {
          "detail": {
            "type": "string",
            "title": "Detail",
            "description": "Human-readable explanation of the error."
          }
        },
        "type": "object",
        "required": [
          "detail"
        ],
        "title": "ErrorResponse",
        "description": "The body returned for a handled 4xx error.\n\nMirrors FastAPI's :class:`~fastapi.HTTPException` shape (``{detail}``)\nso the generated SDKs get a typed error surface distinct from the\n422 request-validation body, whose ``detail`` is a list of field\nerrors rather than a single string."
      },
      "ExecRequest": {
        "properties": {
          "command": {
            "type": "string",
            "title": "Command",
            "description": "Shell command to execute in the sandbox."
          },
          "timeout": {
            "type": "integer",
            "maximum": 3600.0,
            "minimum": 1.0,
            "title": "Timeout",
            "description": "Maximum seconds to wait for the command to finish.",
            "default": 30
          },
          "shell": {
            "type": "string",
            "enum": [
              "login",
              "raw"
            ],
            "title": "Shell",
            "description": "'login' runs via the guest login shell; 'raw' executes the command directly with no shell wrapping.",
            "default": "login"
          }
        },
        "type": "object",
        "required": [
          "command"
        ],
        "title": "ExecRequest",
        "description": "Request body for running a command inside a sandbox.\n\nMirrors the arguments of :meth:`smolvm.SmolVM.run`."
      },
      "ExecResponse": {
        "properties": {
          "exit_code": {
            "type": "integer",
            "title": "Exit Code"
          },
          "stdout": {
            "type": "string",
            "title": "Stdout"
          },
          "stderr": {
            "type": "string",
            "title": "Stderr"
          }
        },
        "type": "object",
        "required": [
          "exit_code",
          "stdout",
          "stderr"
        ],
        "title": "ExecResponse",
        "description": "The result of a command run inside a sandbox.\n\nReuses the engine's :class:`~smolvm.types.CommandResult` (exit code,\nstdout, stderr) under an API-owned name so the generated SDKs expose\na stable ``ExecResponse`` type rather than an engine-internal one."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "SandboxResponse": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Stable sandbox identifier."
          },
          "status": {
            "$ref": "#/components/schemas/VMState",
            "description": "Current lifecycle state."
          }
        },
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "title": "SandboxResponse",
        "description": "A sandbox's public, client-safe state.\n\nHost-internal details (disk paths, PID, network device) are\nintentionally omitted \u2014 clients address a sandbox only by ``id``."
      },
      "VMState": {
        "type": "string",
        "enum": [
          "created",
          "running",
          "paused",
          "stopped",
          "error"
        ],
        "title": "VMState",
        "description": "VM lifecycle states."
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  }
}