Lua

Lua is Rival’s fastest-starting language for Function tools - ideal for lightweight logic with minimal dependencies. The Lua runtime is sandboxed: file I/O, module imports, dynamic code execution, and most OS access are disabled. A json module is pre-loaded so you can encode and decode JSON without any setup.

Handler signature

Your main file must be named cortexone_function.lua and must define a global function called cortexone_handler:

function cortexone_handler(event, context)
    local result = {message = "Hello, World!"}
    return {statusCode = 200, body = result}
end

Parameter	Type	Description
`event`	`table`	The input payload decoded from JSON
`context`	`table`	Execution metadata (not populated for Lua)

The return value should be a Lua table with statusCode and body. Return body as a plain table - the platform serializes it automatically. Use json.encode() only when you need to explicitly control the JSON output.

The `json` module

A json module is pre-loaded and always available - no require needed, but you can require it explicitly:

local json = require("json")

function cortexone_handler(event, context)
    -- decode an incoming JSON string
    local parsed = json.decode(event.payload)
    return {statusCode = 200, body = {value = parsed.key}}
end

The `event` object

event arrives as a Lua table decoded from the caller’s JSON input:

function cortexone_handler(event, context)
    local numbers = event.num
    local sum = 0
    local count = #numbers

    for i = 1, count do
        sum = sum + numbers[i]
    end

    local mean = sum / count

    return {statusCode = 200, body = {sum = sum, mean = mean, count = count}}
end

What is available

Feature	Available
`json` module	Yes - encode/decode JSON
`os.time()`	Yes - current Unix timestamp
`string`, `table`, `math`	Yes - standard Lua libraries
Standard built-ins (`tostring`, `tonumber`, etc.)	Yes
`process.env`	Yes - read your Secrets
`fetch()`	Conditional - depends on version setting
`require()`	No - disabled (except `json`)
`io` module	No - no file I/O
`package` module	No
`dofile` / `loadfile`	No
`load` / `loadstring`	No - no dynamic code execution
`os` (other than `os.time`)	No

What is restricted

No file I/O - io module is removed
No module imports - require, package, dofile, loadfile are removed (only json is pre-loaded)
No dynamic code execution - load and loadstring are removed
No OS access - os module only exposes os.time()

Secrets

Store credentials as Secrets at /user/secrets, attach them to your tool from the Code tab in Studio, and read them through process.env:

function cortexone_handler(event, context)
    local apiKey = process.env.MY_API_KEY
    local region = process.env.REGION or "us-east-1"
    return {statusCode = 200, body = {region = region}}
end

See Secrets for the full workflow.

HTTP requests

When HTTP access is enabled for your version, a fetch() function is available. It returns a Lua table - not a string.

function cortexone_handler(event, context)
    local response = fetch(event.url)
    -- response.body is the raw HTTP response body as a string
    local data = json.decode(response.body)
    return {statusCode = response.status, body = data}
end

The response table contains:

Field	Type	Description
`response.status`	`number`	HTTP status code
`response.statusText`	`string`	HTTP status text
`response.body`	`string`	Response body as a raw string
`response.headers`	`table`	Response headers

You can also pass options for method, headers, and body:

function cortexone_handler(event, context)
    local response = fetch("https://api.example.com/submit", {
        method = "POST",
        headers = {["Content-Type"] = "application/json"},
        body = json.encode({key = "value"})
    })
    return {statusCode = response.status, body = json.decode(response.body)}
end

Resource limits

Limit	Default
Max memory	512 MB
Max runtime	300 seconds
CPU limit	2.0 cores

Example: String processing

function cortexone_handler(event, context)
    local text = event.text or ""
    local words = {}
    for word in text:gmatch("%S+") do
        table.insert(words, word)
    end
    return {
        statusCode = 200,
        body = {
            word_count = #words,
            char_count = #text
        }
    }
end

Example: Using os.time

function cortexone_handler(event, context)
    return {
        statusCode = 200,
        body = {
            processed_at = os.time(),
            input = event
        }
    }
end

Error responses

If your handler raises an error, the platform catches it and returns:

{
  "statusCode": 500,
  "body": "{\"error\": \"Script execution failed\", \"type\": \"RuntimeError\", \"details\": \"...\"}"
}

Timeouts return statusCode: 408. You can return non-200 status codes intentionally:

function cortexone_handler(event, context)
    if not event.id then
        return {statusCode = 400, body = {error = "id is required"}}
    end
    return {statusCode = 200, body = {ok = true}}
end

Testing your code

Save and run sample payloads from the Preview tab in Studio. The panel shows the returned statusCode, body, and any logs from your handler. See Testing & Executing for the full workflow.

Notes

The main file must be named cortexone_function.lua and must contain cortexone_handler as a global function.
Avoid mutating global variables in your handler - keep state local to each call.
Each run starts fresh - no state carries over between calls.
context is passed but not populated - use event for all input data.