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 environment variables
`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()

Environment Secrets

Store credentials as Environment Secrets at /user/secrets, attach them to your tool from the Code step of the Tool Editor, 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 Environment Variables 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 Test panel inside the Code step of the Tool Editor. 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.