Manager API

The GenVM Manager is an HTTP server that provides an API for managing GenVM instances, modules, and related operations.

GET /status

Get manager status

Returns the current status of the manager, its modules, permits, and running executions.

Status Codes:

• 200 OK – Manager status

POST /module/start

Start a module

Start a module with the specified configuration.

Status Codes:

• 200 OK – Module started successfully

• 500 Internal Server Error – Error response

POST /module/stop

Stop a module

Stop a running module.

Status Codes:

• 200 OK – Module stop result

• 500 Internal Server Error – Error response

POST /module/restart

Restart a module

Atomically restart a module. Stops the currently running module (if any) and starts a new one with the specified configuration, all under a single lock to prevent concurrent access during the transition.

Status Codes:

• 200 OK – Module restarted successfully

• 500 Internal Server Error – Error response

POST /genvm/run

Start a GenVM execution

Start a new GenVM instance for contract execution.

The request body uses calldata binary encoding (not JSON). The schema below shows the logical structure that must be encoded using the calldata format.

Status Codes:

• 200 OK – GenVM instance started

• 500 Internal Server Error – Error response

GET /genvm/{genvm_id}

Get GenVM status

Get the status of a specific GenVM instance.

Parameters:

• genvm_id (integer) – Unique identifier of the GenVM instance

Status Codes:

• 200 OK – GenVM status

• 500 Internal Server Error – Error response

DELETE /genvm/{genvm_id}

Shutdown GenVM instance

Gracefully shutdown a GenVM instance.

Parameters:

• genvm_id (integer) – Unique identifier of the GenVM instance

Status Codes:

• 200 OK – Shutdown result

POST /contract/detect-version

Detect contract version

Detect the major version specification from contract bytecode.

Status Codes:

• 200 OK – Detected version

• 500 Internal Server Error – Error response

Request Headers:

• Deployment-Timestamp – Contract deployment timestamp in RFC3339 format (Required)

POST /log/level

Set log level

Set the logging level for the manager.

Status Codes:

• 200 OK – Log level set

• 500 Internal Server Error – Error response

POST /manifest/reload

Reload manifest

Reload the executor version manifest.

Status Codes:

• 200 OK – Manifest reloaded

• 500 Internal Server Error – Error response

POST /env

Set environment variable

Set an environment variable in the manager process.

Status Codes:

• 200 OK – Environment variable set

• 500 Internal Server Error – Error response

GET /permits

Get permits

Get the current number of execution permits available.

Status Codes:

• 200 OK – Current permits

POST /permits

Set permits

Set the number of execution permits.

Status Codes:

• 200 OK – Permits set

• 500 Internal Server Error – Error response

POST /llm/check

Check LLM availability

Test availability and functionality of LLM provider configurations.

Status Codes:

• 200 OK – LLM availability results

• 500 Internal Server Error – Error response

GET /vm-error/describe

Describe VM error

Get a human-readable description for a VM error code.

Query Parameters:

• error (string) – The VM error code to describe (Required)

Status Codes:

• 200 OK – Error description

• 500 Internal Server Error – Error response

openapi: 3.0.3
info:
  title: GenVM Manager API
  description: HTTP API for managing GenVM instances, modules, and related operations.
  version: 1.0.0

servers:
  - url: http://localhost:3999
    description: Default local development server

paths:
  /status:
    get:
      summary: Get manager status
      description: Returns the current status of the manager, its modules, permits, and running executions.
      operationId: getStatus
      responses:
        '200':
          description: Manager status
          content:
            application/json:
              schema:
                type: object
                properties:
                  llm_module:
                    type: string
                    description: Status of the LLM module
                    example: running
                  web_module:
                    type: string
                    description: Status of the web module
                    example: stopped
                  permits:
                    type: object
                    properties:
                      current:
                        type: integer
                        description: Current number of available permits
                      max:
                        type: integer
                        description: Maximum number of permits
                  executions:
                    type: object
                    description: Status of running executions

  /module/start:
    post:
      summary: Start a module
      description: Start a module with the specified configuration.
      operationId: startModule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - module_type
              properties:
                module_type:
                  type: string
                  enum: [llm, web]
                  description: Type of module to start
                config:
                  type: object
                  description: Module-specific configuration
              example:
                module_type: llm
                config:
                  host: localhost
                  port: 8080
      responses:
        '200':
          description: Module started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: module_started
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /module/stop:
    post:
      summary: Stop a module
      description: Stop a running module.
      operationId: stopModule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - module_type
              properties:
                module_type:
                  type: string
                  enum: [llm, web]
                  description: Type of module to stop
              example:
                module_type: llm
      responses:
        '200':
          description: Module stop result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    enum: [module_stopped, module_not_running]
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /module/restart:
    post:
      summary: Restart a module
      description: |
        Atomically restart a module. Stops the currently running module (if any) and starts
        a new one with the specified configuration, all under a single lock to prevent
        concurrent access during the transition.
      operationId: restartModule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - module_type
              properties:
                module_type:
                  type: string
                  enum: [llm, web]
                  description: Type of module to restart
                config:
                  type: object
                  description: Module-specific configuration (null to use default config file)
              example:
                module_type: llm
                config:
                  host: localhost
                  port: 8080
      responses:
        '200':
          description: Module restarted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: module_restarted
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /genvm/run:
    post:
      summary: Start a GenVM execution
      description: |
        Start a new GenVM instance for contract execution.

        The request body uses calldata binary encoding (not JSON). The schema below
        shows the logical structure that must be encoded using the calldata format.
      operationId: runGenvm
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              $ref: '#/components/schemas/GenvmRunRequest'
      responses:
        '200':
          description: GenVM instance started
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: started
                  id:
                    type: integer
                    description: Unique identifier for the GenVM instance
                    example: 12345
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /genvm/{genvm_id}:
    get:
      summary: Get GenVM status
      description: Get the status of a specific GenVM instance.
      operationId: getGenvmStatus
      parameters:
        - name: genvm_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier of the GenVM instance
      responses:
        '200':
          description: GenVM status
          content:
            application/json:
              schema:
                type: object
                properties:
                  genvm_id:
                    type: integer
                  status:
                    type: object
                    description: Current status of the GenVM instance
        '500':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Shutdown GenVM instance
      description: Gracefully shutdown a GenVM instance.
      operationId: shutdownGenvm
      parameters:
        - name: genvm_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique identifier of the GenVM instance
      responses:
        '200':
          description: Shutdown result
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      result:
                        type: string
                        example: shutdown_completed
                      genvm_id:
                        type: integer
                  - type: object
                    properties:
                      error:
                        type: string
                        example: timeout during shutdown
                      genvm_id:
                        type: integer

  /contract/detect-version:
    post:
      summary: Detect contract version
      description: Detect the major version specification from contract bytecode.
      operationId: detectContractVersion
      parameters:
        - name: Deployment-Timestamp
          in: header
          required: true
          schema:
            type: string
            format: date-time
          description: Contract deployment timestamp in RFC3339 format
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: Contract bytecode
      responses:
        '200':
          description: Detected version
          content:
            application/json:
              schema:
                type: object
                properties:
                  specified_major:
                    type: integer
                    description: Detected major version
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /log/level:
    post:
      summary: Set log level
      description: Set the logging level for the manager.
      operationId: setLogLevel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - level
              properties:
                level:
                  type: string
                  enum: [trace, debug, info, warn, error]
                  description: Log level to set
              example:
                level: debug
      responses:
        '200':
          description: Log level set
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: log_level_set
                  level:
                    type: string
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /manifest/reload:
    post:
      summary: Reload manifest
      description: Reload the executor version manifest.
      operationId: reloadManifest
      responses:
        '200':
          description: Manifest reloaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: manifest_reloaded
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /env:
    post:
      summary: Set environment variable
      description: Set an environment variable in the manager process.
      operationId: setEnv
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - key
                - value
              properties:
                key:
                  type: string
                  description: Environment variable name
                value:
                  type: string
                  description: Environment variable value
              example:
                key: DEBUG_MODE
                value: "true"
      responses:
        '200':
          description: Environment variable set
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: env_var_set
                  key:
                    type: string
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /permits:
    get:
      summary: Get permits
      description: Get the current number of execution permits available.
      operationId: getPermits
      responses:
        '200':
          description: Current permits
          content:
            application/json:
              schema:
                type: object
                properties:
                  permits:
                    type: integer
                    description: Number of available permits
    post:
      summary: Set permits
      description: Set the number of execution permits.
      operationId: setPermits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - permits
              properties:
                permits:
                  type: integer
                  description: New number of permits to allocate
              example:
                permits: 10
      responses:
        '200':
          description: Permits set
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: permits_set
                  permits:
                    type: integer
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /llm/check:
    post:
      summary: Check LLM availability
      description: Test availability and functionality of LLM provider configurations.
      operationId: checkLlm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - configs
                - test_prompts
              properties:
                configs:
                  type: array
                  items:
                    type: object
                    required:
                      - host
                      - provider
                      - model
                      - key
                    properties:
                      host:
                        type: string
                        description: LLM provider host URL
                        example: https://api.openai.com
                      provider:
                        type: string
                        description: Provider type
                        example: openai-compatible
                      model:
                        type: string
                        description: Model name
                        example: gpt-4o
                      key:
                        type: string
                        description: API key (supports ${ENV[VAR]} syntax)
                        example: ${ENV[OPENAIKEY]}
                test_prompts:
                  type: array
                  items:
                    type: object
                    properties:
                      system_message:
                        type: string
                        nullable: true
                      user_message:
                        type: string
                      temperature:
                        type: number
                      images:
                        type: array
                        items:
                          type: string
                      max_tokens:
                        type: integer
                      use_max_completion_tokens:
                        type: boolean
            example:
              configs:
                - host: https://api.openai.com
                  provider: openai-compatible
                  model: gpt-4o
                  key: ${ENV[OPENAIKEY]}
              test_prompts:
                - system_message: null
                  user_message: |
                    I am testing that your API works and you are capable for understanding the simplest request.
                    For it I need you to respond with two letters "ok" (without quotes) and nothing else.
                    Lowercase, no repetition or punctuation
                  temperature: 0.2
                  images: []
                  max_tokens: 200
                  use_max_completion_tokens: true
      responses:
        '200':
          description: LLM availability results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    config_index:
                      type: integer
                    prompt_index:
                      type: integer
                    available:
                      type: boolean
                    error:
                      type: string
                      nullable: true
                    response:
                      type: string
                      nullable: true
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /vm-error/describe:
    get:
      summary: Describe VM error
      description: Get a human-readable description for a VM error code.
      operationId: describeVmError
      parameters:
        - name: error
          in: query
          required: true
          schema:
            type: string
          description: The VM error code to describe
      responses:
        '200':
          description: Error description
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                    nullable: true
                    description: Human-readable error description, or null if unknown
        '500':
          $ref: '#/components/responses/ErrorResponse'

components:
  schemas:
    Address:
      type: string
      format: hex
      description: 20-byte Ethereum-style address as hex string
      example: "0x1234567890abcdef1234567890abcdef12345678"

    MessageData:
      type: object
      description: Contract execution message data
      required:
        - contract_address
        - sender_address
        - origin_address
        - chain_id
        - is_init
      properties:
        contract_address:
          $ref: '#/components/schemas/Address'
        sender_address:
          $ref: '#/components/schemas/Address'
        origin_address:
          $ref: '#/components/schemas/Address'
        stack:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          default: []
          description: View methods call chain (empty for entrypoint)
        chain_id:
          type: string
          description: Chain ID as big integer string
          example: "1"
        value:
          type: string
          description: Transaction value as big integer string
          default: "0"
        is_init:
          type: boolean
          description: Whether this is a contract initialization call
        datetime:
          type: string
          format: date-time
          description: Transaction timestamp

    GenvmRunRequest:
      type: object
      description: |
        GenVM execution request. This structure must be encoded using the calldata
        binary format before sending.
      required:
        - major
        - message
        - is_sync
        - capture_output
        - storage_pages
        - host_data
        - timestamp
        - host
        - calldata
      properties:
        major:
          type: integer
          format: uint32
          description: Major version specification
        message:
          $ref: '#/components/schemas/MessageData'
        is_sync:
          type: boolean
          description: Whether execution is synchronous
        capture_output:
          type: boolean
          description: Whether to capture execution output
        max_execution_minutes:
          type: integer
          format: uint64
          default: 20
          description: Maximum execution time in minutes
        storage_pages:
          type: integer
          format: uint64
          description: Number of storage pages allocated
        host_data:
          type: string
          description: Host-specific data as JSON string
        timestamp:
          type: string
          format: date-time
          description: Execution timestamp in RFC3339 format
        host:
          type: string
          description: Host identifier
        extra_args:
          type: array
          items:
            type: string
          default: []
          description: Additional arguments for execution
        calldata:
          type: string
          format: binary
          description: Contract calldata (method name and arguments)
        code:
          type: string
          format: binary
          nullable: true
          description: Optional contract bytecode (for deployment)

  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message