Manager#

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

HTTP API Endpoints#

Status and Health#

GET /status#

Get the current status of the manager and its modules.

Response JSON Object:

llm_module (object) – Status of the LLM module
web_module (object) – Status of the web module

Example response:

{
  "llm_module": "running",
  "web_module": "stopped"
}

Module Management#

POST /module/start#

Start a module with the specified configuration.

Request JSON Object:

module_type (string) – Type of module to start (e.g., “llm”, “web”)
config (object) – Module-specific configuration

Response JSON Object:

result (string) – Result status (“module_started”)

Example request:

{
  "module_type": "llm",
  "config": {
    "host": "localhost",
    "port": 8080
  }
}

POST /module/stop#

Stop a running module.

Request JSON Object:

module_type (string) – Type of module to stop

Response JSON Object:

result (string) – Result status (“module_stopped” or “module_not_running”)

Example request:

{
  "module_type": "llm"
}

GenVM Execution#

POST /genvm/run#

Start a new GenVM instance for contract execution.

Request JSON Object:

major (int) – Major version specification
message (object) – Contract execution message
is_sync (bool) – Whether execution is synchronous
capture_output (bool) – Whether to capture execution output
max_execution_minutes (int) – Maximum execution time in minutes
host_data (string) – Host-specific data as JSON string
timestamp (string) – Execution timestamp in RFC3339 format
host (string) – Host identifier
extra_args (array) – Additional arguments for execution

Response JSON Object:

result (string) – Result status (“started”)
id (int) – Unique identifier for the GenVM instance

Example response:

{
  "result": "started",
  "id": 12345
}

POST /genvm/run/readonly#

Execute a contract in read-only mode (not yet implemented).

Request Headers:

Deployment-Timestamp – Contract deployment timestamp in RFC3339 format

<body:

Contract bytecode

Response JSON Object:

schema (string) – Contract schema information

GET /genvm/(int: genvm_id)#

Get the status of a specific GenVM instance.

Parameters:

genvm_id – Unique identifier of the GenVM instance

Response JSON Object:

genvm_id (int) – The GenVM instance ID
status (object) – Current status of the GenVM instance

DELETE /genvm/(int: genvm_id)#

Gracefully shutdown a GenVM instance.

Parameters:

genvm_id – Unique identifier of the GenVM instance

Query Parameters:

wait_timeout_ms (int) – Timeout in milliseconds to wait for graceful shutdown (default: 30000)

Response JSON Object:

result (string) – Result status (“shutdown_completed”)
genvm_id (int) – The GenVM instance ID

Error response:

{
  "error": "timeout during shutdown",
  "genvm_id": 12345
}

Contract Operations#

POST /contract/detect-version#

Detect the major version specification from contract bytecode.

Request Headers:

Deployment-Timestamp – Contract deployment timestamp in RFC3339 format

<body:

Contract bytecode

Response JSON Object:

specified_major (int) – Detected major version

POST /contract/pre-deploy-writes#

Generate storage writes required for contract deployment.

Request Headers:

Deployment-Timestamp – Contract deployment timestamp in RFC3339 format

<body:

Contract bytecode

Response JSON Object:

writes (array) – Array of storage write operations

Example response:

{
  "writes": [
    ["<base64-encoded-key>", "<base64-encoded-value>"],
    ["<base64-encoded-key>", "<base64-encoded-value>"]
  ]
}

Configuration Management#

POST /log/level#

Set the logging level for the manager.

Request JSON Object:

level (string) – Log level (“trace”, “debug”, “info”, “warn”, “error”)

Response JSON Object:

result (string) – Result status (“log_level_set”)
level (string) – The new log level

Example request:

{
  "level": "debug"
}

POST /manifest/reload#

Reload the executor version manifest.

Response JSON Object:

result (string) – Result status (“manifest_reloaded”)

POST /env#

Set an environment variable in the manager process.

Request JSON Object:

key (string) – Environment variable name
value (string) – Environment variable value

Response JSON Object:

result (string) – Result status (“env_var_set”)
key (string) – The environment variable name

Example request:

{
  "key": "DEBUG_MODE",
  "value": "true"
}

Resource Management#

GET /permits#

Get the current number of execution permits available.

Response JSON Object:

permits (int) – Number of available permits

POST /permits#

Set the number of execution permits.

Request JSON Object:

permits (int) – New number of permits to allocate

Response JSON Object:

result (string) – Result status (“permits_set”)
permits (int) – The new number of permits

Example request:

{
  "permits": 10
}

LLM Testing#

POST /llm/check#

Test availability and functionality of LLM provider configurations.

Request JSON Object:

configs (array) – Array of LLM provider configurations
test_prompts (array) – Array of test prompts to execute

Response JSON Object:

results (array) – Array of availability test results

Example request:

{
  "configs": [
    {
      "host": "https://api.openai.com",
      "provider": "openai-compatible",
      "model": "gpt-4o",
      "key": "${ENV[OPENAIKEY]}",
    }
  ],
  "test_prompts": [
    {
      "system_message": null,
      "user_message": "Respond with exactly two letters 'OK' and nothing else",
      "temperature": 0.2,
      "images": [],
      "max_tokens": 200,
      "use_max_completion_tokens": true
    }
  ]
}

Example response:

[
  {
    "config_index": 0,
    "prompt_index": 0,
    "available": true,
    "error": null,
    "response": "Hello! How can I help you today?"
  }
]

Error Responses#

All endpoints may return error responses in the following format:

{
  "error": "Description of the error"
}

HTTP status codes used:

200 OK: Successful operation
404 Not Found: Endpoint not found
500 Internal Server Error: Server error or request processing failure