KosmoKrator

data

Fly.io Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local fly_io = app.integrations.fly_io
local result = fly_io.list_apps({})

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

MCP-only Lua

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

Fly.io — Lua API Reference

list_apps

List all Fly.io apps in the organization.

Parameters

None.

Example

local result = app.integrations["fly-io"].list_apps({})

for _, app in ipairs(result) do
  print(app.name .. " - " .. app.status .. " (" .. app.organization .. ")")
end

get_app

Get details for a specific Fly.io app.

Parameters

NameTypeRequiredDescription
app_namestringyesThe name of the Fly.io app

Example

local result = app.integrations["fly-io"].get_app({ app_name = "my-app" })
print(result.name .. " - " .. result.status)

create_app

Create a new Fly.io app.

Parameters

NameTypeRequiredDescription
app_namestringyesThe desired name for the new app
org_slugstringnoThe organization slug (uses default org if omitted)

Example

local result = app.integrations["fly-io"].create_app({
  app_name = "my-new-app",
  org_slug = "personal"
})
print("Created app: " .. result.name)

list_machines

List all machines for a Fly.io app.

Parameters

NameTypeRequiredDescription
app_namestringyesThe name of the Fly.io app

Example

local result = app.integrations["fly-io"].list_machines({ app_name = "my-app" })

for _, machine in ipairs(result) do
  print(machine.id .. " - " .. machine.state .. " - " .. machine.region)
end

get_machine

Get details for a specific Fly.io machine.

Parameters

NameTypeRequiredDescription
app_namestringyesThe name of the Fly.io app
machine_idstringyesThe machine ID

Example

local result = app.integrations["fly-io"].get_machine({
  app_name = "my-app",
  machine_id = "73d8d46dbee589"
})
print(result.id .. " - state: " .. result.state .. " - region: " .. result.region)

list_volumes

List all persistent volumes for a Fly.io app.

Parameters

NameTypeRequiredDescription
app_namestringyesThe name of the Fly.io app

Example

local result = app.integrations["fly-io"].list_volumes({ app_name = "my-app" })

for _, vol in ipairs(result) do
  print(vol.id .. " - " .. vol.name .. " - " .. vol.size_gb .. "GB - " .. vol.region)
end

Multi-Account Usage

If you have multiple Fly.io accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations["fly-io"].list_apps({})

-- Explicit default (portable across setups)
app.integrations["fly-io"].default.list_apps({})

-- Named accounts
app.integrations["fly-io"].production.list_apps({})
app.integrations["fly-io"].staging.list_apps({})

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

Raw agent markdown 
# Fly.io — Lua API Reference

## list_apps

List all Fly.io apps in the organization.

### Parameters

None.

### Example

```lua
local result = app.integrations["fly-io"].list_apps({})

for _, app in ipairs(result) do
  print(app.name .. " - " .. app.status .. " (" .. app.organization .. ")")
end
```

---

## get_app

Get details for a specific Fly.io app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_name` | string | yes | The name of the Fly.io app |

### Example

```lua
local result = app.integrations["fly-io"].get_app({ app_name = "my-app" })
print(result.name .. " - " .. result.status)
```

---

## create_app

Create a new Fly.io app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_name` | string | yes | The desired name for the new app |
| `org_slug` | string | no | The organization slug (uses default org if omitted) |

### Example

```lua
local result = app.integrations["fly-io"].create_app({
  app_name = "my-new-app",
  org_slug = "personal"
})
print("Created app: " .. result.name)
```

---

## list_machines

List all machines for a Fly.io app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_name` | string | yes | The name of the Fly.io app |

### Example

```lua
local result = app.integrations["fly-io"].list_machines({ app_name = "my-app" })

for _, machine in ipairs(result) do
  print(machine.id .. " - " .. machine.state .. " - " .. machine.region)
end
```

---

## get_machine

Get details for a specific Fly.io machine.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_name` | string | yes | The name of the Fly.io app |
| `machine_id` | string | yes | The machine ID |

### Example

```lua
local result = app.integrations["fly-io"].get_machine({
  app_name = "my-app",
  machine_id = "73d8d46dbee589"
})
print(result.id .. " - state: " .. result.state .. " - region: " .. result.region)
```

---

## list_volumes

List all persistent volumes for a Fly.io app.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `app_name` | string | yes | The name of the Fly.io app |

### Example

```lua
local result = app.integrations["fly-io"].list_volumes({ app_name = "my-app" })

for _, vol in ipairs(result) do
  print(vol.id .. " - " .. vol.name .. " - " .. vol.size_gb .. "GB - " .. vol.region)
end
```

---

## Multi-Account Usage

If you have multiple Fly.io accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations["fly-io"].list_apps({})

-- Explicit default (portable across setups)
app.integrations["fly-io"].default.list_apps({})

-- Named accounts
app.integrations["fly-io"].production.list_apps({})
app.integrations["fly-io"].staging.list_apps({})
```

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

Functions

list_apps Read

List all Fly.io apps in the organization. Returns app names, IDs, status, and network details.

Lua path
app.integrations.fly_io.list_apps
Full name
fly-io.fly_io_list_apps
ParameterTypeRequiredDescription
No parameters.
get_app Read

Get details for a specific Fly.io app, including status, network, and machine count.

Lua path
app.integrations.fly_io.get_app
Full name
fly-io.fly_io_get_app
ParameterTypeRequiredDescription
app_name string no The name of the Fly.io app.
create_app Write

Create a new Fly.io app. Requires an app name and optionally an organization ID.

Lua path
app.integrations.fly_io.create_app
Full name
fly-io.fly_io_create_app
ParameterTypeRequiredDescription
app_name string no The desired name for the new app.
org_slug string no The organization slug to create the app in (optional, uses default org if omitted).
list_machines Read

List all machines for a Fly.io app. Returns machine IDs, state, region, and configuration.

Lua path
app.integrations.fly_io.list_machines
Full name
fly-io.fly_io_list_machines
ParameterTypeRequiredDescription
app_name string no The name of the Fly.io app.
get_machine Read

Get details for a specific Fly.io machine, including its state, config, and region.

Lua path
app.integrations.fly_io.get_machine
Full name
fly-io.fly_io_get_machine
ParameterTypeRequiredDescription
app_name string no The name of the Fly.io app.
machine_id string no The machine ID.
list_volumes Read

List all persistent volumes for a Fly.io app. Returns volume IDs, name, size, and region.

Lua path
app.integrations.fly_io.list_volumes
Full name
fly-io.fly_io_list_volumes
ParameterTypeRequiredDescription
app_name string no The name of the Fly.io app.