Runloop Launch Parameters

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/runloop-ai/main/json-schema/runloop-launch-parameters-schema.json",
  "title": "Runloop Launch Parameters",
  "description": "LaunchParameters enable you to customize the resources available to your Devbox as well as the environment set up that should be completed before the Devbox is marked as 'running'.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "launch_commands": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "description": "Set of commands to be run at launch time, before the entrypoint process is run."
    },
    "resource_size_request": {
      "$ref": "#/$defs/ResourceSize",
      "nullable": true,
      "description": "Preset Devbox resources (vCPU, RAM in GiB, ephemeral disk in GiB). If not set, SMALL is used. X_SMALL: 0.5 vCPU, 1 GiB RAM, 4 GiB disk. SMALL: 1 vCPU, 2 GiB RAM, 4 GiB disk. MEDIUM: 2 vCPU, 4 GiB RAM, 8 GiB disk. LARGE: 2 vCPU, 8 GiB RAM, 16 GiB disk. X_LARGE: 4 vCPU, 16 GiB RAM, 16 GiB disk. XX_LARGE: 8 vCPU, 32 GiB RAM, 16 GiB disk. CUSTOM_SIZE: set custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size."
    },
    "available_ports": {
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int32"
      },
      "nullable": true,
      "description": "[Deprecated] A list of ports to make available on the Devbox. This field is ignored."
    },
    "keep_alive_time_seconds": {
      "type": "integer",
      "format": "int64",
      "nullable": true,
      "description": "Time in seconds after which Devbox will automatically shutdown. Default is 1 hour. Maximum is 48 hours (172800 seconds)."
    },
    "after_idle": {
      "$ref": "#/$defs/IdleConfigurationParameters",
      "nullable": true,
      "description": "Configure Devbox lifecycle based on idle activity. If after_idle is set, Devbox will ignore keep_alive_time_seconds. If both after_idle and lifecycle.after_idle are set, they must have the same value. Use lifecycle.after_idle instead."
    },
    "custom_cpu_cores": {
      "type": "integer",
      "format": "int32",
      "nullable": true,
      "description": "Custom CPU cores. Must be 0.5, 1, or a multiple of 2. Max is 16."
    },
    "custom_gb_memory": {
      "type": "integer",
      "format": "int32",
      "nullable": true,
      "description": "Custom memory size in GiB. Must be 1 or a multiple of 2. Max is 64GiB."
    },
    "custom_disk_size": {
      "type": "integer",
      "format": "int32",
      "nullable": true,
      "description": "Custom disk size in GiB. Must be a multiple of 2. Min is 2GiB, max is 64GiB."
    },
    "architecture": {
      "$ref": "#/$defs/Architecture",
      "nullable": true,
      "description": "The target architecture for the Devbox. If unset, defaults to x86_64."
    },
    "user_parameters": {
      "$ref": "#/$defs/UserParameters",
      "nullable": true,
      "description": "Specify the user for execution on Devbox. If not set, default `user` will be used."
    },
    "required_services": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "nullable": true,
      "description": "A list of ContainerizedService names to be started when a Devbox is created. A valid ContainerizedService must be specified in Blueprint to be started."
    },
    "network_policy_id": {
      "type": "string",
      "nullable": true,
      "description": "(Optional) ID of the network policy to apply to Devboxes launched with these parameters. When set on a Blueprint launch parameters, Devboxes created from it will inherit this policy unless explicitly overridden."
    },
    "lifecycle": {
      "$ref": "#/$defs/LifecycleConfigurationParameters",
      "nullable": true,
      "description": "Lifecycle configuration for idle and resume behavior. Configure idle policy via lifecycle.after_idle (if both this and the top-level after_idle are set, they must match) and resume triggers via lifecycle.resume_triggers."
    }
  },
  "$defs": {
    "ResourceSize": {
      "type": "string",
      "enum": [
        "X_SMALL",
        "SMALL",
        "MEDIUM",
        "LARGE",
        "X_LARGE",
        "XX_LARGE",
        "CUSTOM_SIZE"
      ],
      "description": "The size of the Devbox resources for Runloop to allocate.\n\nX_SMALL: 0.5 cpu x 1GiB memory x 4GiB disk\nSMALL: 1 cpu x 2GiB memory x 4GiB disk\nMEDIUM: 2 cpu x 4GiB memory x 8GiB disk\nLARGE: 2 cpu x 8GiB memory x 16GiB disk\nX_LARGE: 4 cpu x 16GiB memory x 16GiB disk\nXX_LARGE: 8 cpu x 32GiB memory x 16GiB disk\nCUSTOM_SIZE: To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive.\n",
      "x-enum-descriptions": {
        "X_SMALL": "0.5 cpu x 1GiB memory x 4GiB disk",
        "SMALL": "1 cpu x 2GiB memory x 4GiB disk",
        "MEDIUM": "2 cpu x 4GiB memory x 8GiB disk",
        "LARGE": "2 cpu x 8GiB memory x 16GiB disk",
        "X_LARGE": "4 cpu x 16GiB memory x 16GiB disk",
        "XX_LARGE": "8 cpu x 32GiB memory x 16GiB disk",
        "CUSTOM_SIZE": "To choose a custom size, set this enum and also the custom_cpu_cores, custom_gb_memory, and optionally custom_disk_size in launch parameters. CPU must be 0.5, 1, or a multiple of 2 (max 16). Memory must be 1 or a multiple of 2 (max 64GiB). Disk must be a multiple of 2 (min 2GiB, max 64GiB). The cpu:memory ratio must be between 1:2 and 1:8 inclusive."
      }
    },
    "IdleAction": {
      "type": "string",
      "enum": [
        "shutdown",
        "suspend"
      ],
      "description": "Action to take after Devbox idle timer is triggered.\n\nshutdown: Shutdown the Devbox.\nsuspend: Suspend the Devbox.\n",
      "x-enum-descriptions": {
        "shutdown": "Shutdown the Devbox.",
        "suspend": "Suspend the Devbox."
      }
    },
    "IdleConfigurationParameters": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "idle_time_seconds": {
          "type": "integer",
          "format": "int32",
          "description": "After idle_time_seconds, on_idle action will be taken."
        },
        "on_idle": {
          "$ref": "#/$defs/IdleAction",
          "description": "Action to take after Devbox becomes idle."
        }
      },
      "required": [
        "idle_time_seconds",
        "on_idle"
      ]
    },
    "Architecture": {
      "type": "string",
      "enum": [
        "x86_64",
        "arm64"
      ]
    },
    "UserParameters": {
      "type": "object",
      "additionalProperties": false,
      "description": "Configuration for the Linux user in the Devbox environment.",
      "properties": {
        "username": {
          "type": "string",
          "description": "Username for the Linux user."
        },
        "uid": {
          "type": "integer",
          "format": "int32",
          "description": "User ID (UID) for the Linux user. Must be a non-negative integer."
        }
      },
      "required": [
        "username",
        "uid"
      ]
    },
    "ResumeTriggers": {
      "type": "object",
      "additionalProperties": false,
      "description": "Triggers that can resume a suspended Devbox.",
      "properties": {
        "http": {
          "type": "boolean",
          "nullable": true,
          "description": "When true, HTTP traffic to a suspended Devbox via tunnel will trigger a resume."
        },
        "axon_event": {
          "type": "boolean",
          "nullable": true,
          "description": "When true, axon events targeting a suspended Devbox will trigger a resume."
        }
      }
    },
    "LifecycleConfigurationParameters": {
      "type": "object",
      "additionalProperties": false,
      "description": "Lifecycle configuration for Devbox idle and resume behavior. Configure idle policy via after_idle and resume triggers via resume_triggers.",
      "properties": {
        "after_idle": {
          "$ref": "#/$defs/IdleConfigurationParameters",
          "nullable": true,
          "description": "Configure Devbox lifecycle based on idle activity. If both this and the top-level after_idle are set, they must have the same value. Prefer this field for new integrations."
        },
        "resume_triggers": {
          "$ref": "#/$defs/ResumeTriggers",
          "nullable": true,
          "description": "Triggers that can resume a suspended Devbox."
        }
      }
    }
  }
}