KosmoKrator

productivity

UpCloud Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.upcloud.*. Use lua_read_doc("integrations.upcloud") 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 UpCloud workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.upcloud.list_servers({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("upcloud"))' --json
kosmo integrations:lua --eval 'print(docs.read("upcloud.list_servers"))' --json

Workflow file

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

workflow.lua 
local upcloud = app.integrations.upcloud
local result = upcloud.list_servers({})

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.upcloud, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.upcloud.default.* or app.integrations.upcloud.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need UpCloud, 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.

UpCloud — Lua API Reference

list_servers

List all cloud servers on the UpCloud account.

Parameters

None.

Examples

-- List all servers
local result = app.integrations.upcloud.list_servers({})

for _, server in ipairs(result.servers) do
  print(server.uuid .. ": " .. server.title .. " (" .. server.state .. ")")
end

get_server

Get details for a specific UpCloud server.

Parameters

NameTypeRequiredDescription
uuidstringyesThe server UUID

Examples

local result = app.integrations.upcloud.get_server({ uuid = "abc123-def456" })
print(result.server.title)
print(result.server.state)
print(result.server.vcpu)
print(result.server.memory_amount)

list_storages

List storage devices on the UpCloud account.

Parameters

NameTypeRequiredDescription
typestringnoStorage type filter: “disk”, “backup”, or “cdrom”

Examples

-- List all storages
local result = app.integrations.upcloud.list_storages({})

-- List only disk storages
local result = app.integrations.upcloud.list_storages({ type = "disk" })

for _, storage in ipairs(result.storages) do
  print(storage.uuid .. ": " .. storage.title .. " (" .. storage.size .. " GB)")
end

list_networks

List private networks on the UpCloud account.

Parameters

None.

Examples

local result = app.integrations.upcloud.list_networks({})

for _, network in ipairs(result.networks) do
  print(network.uuid .. ": " .. network.name .. " (" .. network.zone .. ")")
end

list_ips

List IP addresses on the UpCloud account.

Parameters

None.

Examples

local result = app.integrations.upcloud.list_ips({})

for _, ip in ipairs(result.ip_addresses) do
  print(ip.address .. " (" .. ip.family .. ") -> " .. (ip.server or "unassigned"))
end

list_zones

List available UpCloud zones (data centers).

Parameters

None.

Examples

local result = app.integrations.upcloud.list_zones({})

for _, zone in ipairs(result.zones) do
  print(zone.id .. ": " .. zone.description)
end

get_current_user

Get the profile of the currently authenticated user.

Parameters

None.

Examples

local result = app.integrations.upcloud.get_current_user({})
print("Logged in as: " .. result.account.username)

Multi-Account Usage

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

-- Default account (always works)
app.integrations.upcloud.function_name({...})

-- Explicit default (portable across setups)
app.integrations.upcloud.default.function_name({...})

-- Named accounts
app.integrations.upcloud.production.function_name({...})
app.integrations.upcloud.staging.function_name({...})

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

Raw agent markdown 
# UpCloud — Lua API Reference

## list_servers

List all cloud servers on the UpCloud account.

### Parameters

None.

### Examples

```lua
-- List all servers
local result = app.integrations.upcloud.list_servers({})

for _, server in ipairs(result.servers) do
  print(server.uuid .. ": " .. server.title .. " (" .. server.state .. ")")
end
```

---

## get_server

Get details for a specific UpCloud server.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | yes | The server UUID |

### Examples

```lua
local result = app.integrations.upcloud.get_server({ uuid = "abc123-def456" })
print(result.server.title)
print(result.server.state)
print(result.server.vcpu)
print(result.server.memory_amount)
```

---

## list_storages

List storage devices on the UpCloud account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | no | Storage type filter: "disk", "backup", or "cdrom" |

### Examples

```lua
-- List all storages
local result = app.integrations.upcloud.list_storages({})

-- List only disk storages
local result = app.integrations.upcloud.list_storages({ type = "disk" })

for _, storage in ipairs(result.storages) do
  print(storage.uuid .. ": " .. storage.title .. " (" .. storage.size .. " GB)")
end
```

---

## list_networks

List private networks on the UpCloud account.

### Parameters

None.

### Examples

```lua
local result = app.integrations.upcloud.list_networks({})

for _, network in ipairs(result.networks) do
  print(network.uuid .. ": " .. network.name .. " (" .. network.zone .. ")")
end
```

---

## list_ips

List IP addresses on the UpCloud account.

### Parameters

None.

### Examples

```lua
local result = app.integrations.upcloud.list_ips({})

for _, ip in ipairs(result.ip_addresses) do
  print(ip.address .. " (" .. ip.family .. ") -> " .. (ip.server or "unassigned"))
end
```

---

## list_zones

List available UpCloud zones (data centers).

### Parameters

None.

### Examples

```lua
local result = app.integrations.upcloud.list_zones({})

for _, zone in ipairs(result.zones) do
  print(zone.id .. ": " .. zone.description)
end
```

---

## get_current_user

Get the profile of the currently authenticated user.

### Parameters

None.

### Examples

```lua
local result = app.integrations.upcloud.get_current_user({})
print("Logged in as: " .. result.account.username)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.upcloud.function_name({...})

-- Explicit default (portable across setups)
app.integrations.upcloud.default.function_name({...})

-- Named accounts
app.integrations.upcloud.production.function_name({...})
app.integrations.upcloud.staging.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.upcloud.list_servers({})
print(result)

Functions

list_servers Read

List all cloud servers on the UpCloud account.

Lua path
app.integrations.upcloud.list_servers
Full name
upcloud.upcloud_list_servers
ParameterTypeRequiredDescription
No parameters.
get_server Read

Get details for a specific UpCloud server by UUID.

Lua path
app.integrations.upcloud.get_server
Full name
upcloud.upcloud_get_server
ParameterTypeRequiredDescription
uuid string yes The server UUID.
list_storages Read

List storage devices on the UpCloud account. Optionally filter by type (disk, backup, cdrom).

Lua path
app.integrations.upcloud.list_storages
Full name
upcloud.upcloud_list_storages
ParameterTypeRequiredDescription
type string no Storage type filter: "disk", "backup", or "cdrom".
list_networks Read

List private networks on the UpCloud account.

Lua path
app.integrations.upcloud.list_networks
Full name
upcloud.upcloud_list_networks
ParameterTypeRequiredDescription
No parameters.
list_ips Read

List IP addresses on the UpCloud account.

Lua path
app.integrations.upcloud.list_ips
Full name
upcloud.upcloud_list_ips
ParameterTypeRequiredDescription
No parameters.
list_zones Read

List available UpCloud zones (data centers).

Lua path
app.integrations.upcloud.list_zones
Full name
upcloud.upcloud_list_zones
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the profile of the currently authenticated UpCloud user. Useful for verifying credentials and displaying account information.

Lua path
app.integrations.upcloud.get_current_user
Full name
upcloud.upcloud_get_current_user
ParameterTypeRequiredDescription
No parameters.