Execute Command

POST /execute

Executes a command in an available microVM.

NOTE: The 'timeout' parameter is HTTP REQUEST TIMEOUT (how long to wait for response). VM lifetime is controlled by session's vm_lifetime_seconds (set during session creation).

Flow:

1. First /execute call → spawns VM, schedules kill after vm_lifetime_seconds
2. Subsequent /execute calls → reuse same VM (until lifetime expires)
3. After lifetime expires → VM is killed, next /execute spawns new VM

Rate limiting is applied based on user's subscription plan.

Multi-node routing:

• If session exists on another node, request is proxied to that node
• New sessions are created locally

Authentication

Requires authentication via: OAuth2PasswordBearer.

Parameters

Name	In	Type	Required	Description	Constraints
X-API-Key	header	string | null	No		nullable

Request Body

Required: Yes

application/json

Resolved schema:

{
  "properties": {
    "command": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Command"
    },
    "code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Code"
    },
    "api_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Api Key"
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Session Id"
    },
    "language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Language",
      "default": "python"
    },
    "timeout": {
      "type": "integer",
      "maximum": 600,
      "minimum": 1,
      "title": "Timeout",
      "default": 60
    },
    "vault_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Vault Ids"
    }
  },
  "type": "object",
  "title": "CommandRequest"
}

Field details:

Field	Type	Required	Description	Constraints
command	string | null	No		nullable
code	string | null	No		nullable
api_key	string | null	No		nullable
session_id	string | null	No		nullable
language	string | null	No		nullable
timeout	integer	No		default=60, min=1, max=600
vault_ids	array<string> | null	No		nullable
vault_ids[]	string	No

Responses

200

Successful Response

application/json

Resolved schema:

{}

422

Validation Error

application/json

Resolved schema:

{
  "properties": {
    "detail": {
      "items": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "type": "array",
      "title": "Detail"
    }
  },
  "type": "object",
  "title": "HTTPValidationError"
}

Field details:

Field	Type	Required	Description	Constraints
detail	array<object>	No
detail[]	object	No
detail[].loc	array<string | integer>	No
detail[].loc[]	string | integer	No
detail[].msg	string	No
detail[].type	string	No