Lua

Lua tools run in isolated Lua worker processes using the GopherLua runtime. Lua is a good choice for lightweight, fast tools with minimal dependencies.

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. You can 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 for it, 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 variables

Environment variables are injected into the execution context by the platform and accessed via 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

Set environment variables in Step 2 of the tool editor (Code & Test). See the Environment Variables guide for details.

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

Notes

The main file must be named cortexone_function.lua and must contain cortexone_handler as a global function.
Lua worker processes are pooled — avoid mutating globals in your handler as the state may persist within the same worker.
There is no persistent state guaranteed between separate executions — two calls may land on different worker instances.
context is passed but not populated — use event for all input data.