KosmoKrator

data

Linode Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Linode KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.linode.*. Use lua_read_doc("integrations.linode") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Linode workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.linode.list_instances({page = 1, per_page = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("linode"))' --json
kosmo integrations:lua --eval 'print(docs.read("linode.list_instances"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local linode = app.integrations.linode
local result = linode.list_instances({page = 1, per_page = 1})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.linode, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.linode.default.* or app.integrations.linode.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Linode, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Linode — Lua API Reference

list_instances

List all Linode instances (virtual machines) in the account.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (default: 1)
per_pageintegernoItems per page (default: 100, max: 500)

Example

local result = app.integrations.linode.list_instances({
  per_page = 50
})

for _, instance in ipairs(result.data) do
  print(instance.label .. " (" .. instance.status .. ") - " .. instance.type)
end

get_instance

Get details for a specific Linode instance.

Parameters

NameTypeRequiredDescription
idintegeryesThe Linode instance ID

Example

local result = app.integrations.linode.get_instance({ id = 12345678 })
local i = result
print(i.label .. " - " .. i.region .. " - " .. i.specs.vcpus .. " vCPUs, " .. i.specs.memory .. " MB RAM")

list_volumes

List all block storage volumes in the account.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination
per_pageintegernoItems per page

Example

local result = app.integrations.linode.list_volumes({})

for _, volume in ipairs(result.data) do
  print(volume.label .. " (" .. volume.size .. " GB) - " .. volume.status)
end

list_domains

List all DNS domains in the account.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination
per_pageintegernoItems per page

Example

local result = app.integrations.linode.list_domains({})

for _, domain in ipairs(result.data) do
  print(domain.domain .. " (status: " .. domain.status .. ")")
end

get_domain

Get details for a specific DNS domain.

Parameters

NameTypeRequiredDescription
idintegeryesThe domain ID

Example

local result = app.integrations.linode.get_domain({ id = 12345 })
print(result.domain .. " - SOA email: " .. result.soa_email)

list_stackscripts

List all StackScripts (reusable deployment scripts).

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination
per_pageintegernoItems per page

Example

local result = app.integrations.linode.list_stackscripts({})

for _, script in ipairs(result.data) do
  print(script.label .. " (deployments: " .. script.deployments_total .. ")")
end

get_current_user

Get the current authenticated user profile information.

Parameters

None.

Example

local result = app.integrations.linode.get_current_user({})
print("User: " .. result.username .. " (" .. result.email .. ")")

Multi-Account Usage

If you have multiple Linode accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.linode.list_instances({})

-- Explicit default (portable across setups)
app.integrations.linode.default.list_instances({})

-- Named accounts
app.integrations.linode.production.list_instances({})
app.integrations.linode.staging.list_instances({})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Linode — Lua API Reference

## list_instances

List all Linode instances (virtual machines) in the account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `per_page` | integer | no | Items per page (default: 100, max: 500) |

### Example

```lua
local result = app.integrations.linode.list_instances({
  per_page = 50
})

for _, instance in ipairs(result.data) do
  print(instance.label .. " (" .. instance.status .. ") - " .. instance.type)
end
```

---

## get_instance

Get details for a specific Linode instance.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The Linode instance ID |

### Example

```lua
local result = app.integrations.linode.get_instance({ id = 12345678 })
local i = result
print(i.label .. " - " .. i.region .. " - " .. i.specs.vcpus .. " vCPUs, " .. i.specs.memory .. " MB RAM")
```

---

## list_volumes

List all block storage volumes in the account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination |
| `per_page` | integer | no | Items per page |

### Example

```lua
local result = app.integrations.linode.list_volumes({})

for _, volume in ipairs(result.data) do
  print(volume.label .. " (" .. volume.size .. " GB) - " .. volume.status)
end
```

---

## list_domains

List all DNS domains in the account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination |
| `per_page` | integer | no | Items per page |

### Example

```lua
local result = app.integrations.linode.list_domains({})

for _, domain in ipairs(result.data) do
  print(domain.domain .. " (status: " .. domain.status .. ")")
end
```

---

## get_domain

Get details for a specific DNS domain.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The domain ID |

### Example

```lua
local result = app.integrations.linode.get_domain({ id = 12345 })
print(result.domain .. " - SOA email: " .. result.soa_email)
```

---

## list_stackscripts

List all StackScripts (reusable deployment scripts).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination |
| `per_page` | integer | no | Items per page |

### Example

```lua
local result = app.integrations.linode.list_stackscripts({})

for _, script in ipairs(result.data) do
  print(script.label .. " (deployments: " .. script.deployments_total .. ")")
end
```

---

## get_current_user

Get the current authenticated user profile information.

### Parameters

None.

### Example

```lua
local result = app.integrations.linode.get_current_user({})
print("User: " .. result.username .. " (" .. result.email .. ")")
```

---

## Multi-Account Usage

If you have multiple Linode accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.linode.list_instances({})

-- Explicit default (portable across setups)
app.integrations.linode.default.list_instances({})

-- Named accounts
app.integrations.linode.production.list_instances({})
app.integrations.linode.staging.list_instances({})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.linode.list_instances({page = 1, per_page = 1})
print(result)

Functions

list_instances Read

List all Linode instances (virtual machines) in the account. Returns IDs, labels, status, type, region, and IP addresses.

Lua path
app.integrations.linode.list_instances
Full name
linode.linode_list_instances
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of instances per page (default: 100, max: 500).
get_instance Read

Get details for a specific Linode instance by ID. Returns full instance information including specs, networking, and disk config.

Lua path
app.integrations.linode.get_instance
Full name
linode.linode_get_instance
ParameterTypeRequiredDescription
id integer yes The Linode instance ID.
list_volumes Read

List all block storage volumes in the Linode account. Returns IDs, labels, size, status, and attached Linode info.

Lua path
app.integrations.linode.list_volumes
Full name
linode.linode_list_volumes
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of volumes per page (default: 100).
list_domains Read

List all DNS domains managed in the Linode account. Returns domain IDs, names, status, and SOA records.

Lua path
app.integrations.linode.list_domains
Full name
linode.linode_list_domains
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of domains per page (default: 100).
get_domain Read

Get details for a specific DNS domain in Linode, including SOA records, status, and zone information.

Lua path
app.integrations.linode.get_domain
Full name
linode.linode_get_domain
ParameterTypeRequiredDescription
id integer yes The domain ID.
list_stackscripts Read

List all StackScripts (reusable deployment scripts) in the Linode account. Returns IDs, labels, descriptions, and deployment counts.

Lua path
app.integrations.linode.list_stackscripts
Full name
linode.linode_list_stackscripts
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of StackScripts per page (default: 100).
get_current_user Read

Get information about the current authenticated Linode user, including username, email, and account status.

Lua path
app.integrations.linode.get_current_user
Full name
linode.linode_get_current_user
ParameterTypeRequiredDescription
No parameters.