Upload files from a device

After this guide, a device uploads a file with its own credential and returns a public URL the agent can show or store. Use this for screenshots, photos, and logs; for values that fit in a command result, return them directly, since a command response is capped at 1 MB and a file on the CDN is not part of the conversation until you share its URL. Verified against @lua-ai-global/device-client 1.1.0, lua-device-client 1.3.0, and lua-cli 3.45.0. Before you begin

A device credential that grants assets.upload; the CDN refuses uploads from a credential without it. Issue one with lua devices credential --device-name <name> --operations commands,assets.upload.
The Node or Python client. The MicroPython client has no CDN support.

Upload from a command handler

cdn.upload sends the bytes as a multipart upload and resolves with the file’s ID and URL. One file per call, at most 100 MB.

Node
Python

device.ts

import { readFileSync } from 'node:fs';
import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: process.env.LUA_AGENT_ID!,
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  deviceName: 'lobby-kiosk',
  commands: [{ name: 'upload_logs', description: 'Upload the kiosk application log' }],
});

device.onCommand('upload_logs', async () => {
  const log = readFileSync('/var/log/kiosk/app.log');
  const file = await device.cdn.upload(log, 'kiosk-app.log', 'text/plain');
  return { url: file.url, fileId: file.fileId, bytes: log.length };
});

device.connect().catch((err: Error) => console.error(err.message));

device.py

import asyncio
import os

from lua_device import DeviceClient, DeviceCommandDefinition

client = DeviceClient(
    agent_id=os.environ["LUA_AGENT_ID"],
    api_key=os.environ["LUA_DEVICE_CREDENTIAL"],
    device_name="lobby-kiosk",
    commands=[DeviceCommandDefinition(name="upload_logs", description="Upload the kiosk application log")],
)


async def upload_logs(payload):
    with open("/var/log/kiosk/app.log", "rb") as f:
        log = f.read()
    file = await client.cdn.upload(log, "kiosk-app.log", "text/plain")
    return {"url": file.url, "fileId": file.file_id, "bytes": len(log)}


client.on_command("upload_logs", upload_logs)


async def main():
    await client.connect()
    await asyncio.Event().wait()


asyncio.run(main())

The result’s url is https://cdn.heylua.ai/<fileId>, and mediaType and extension report what the CDN detected. cdn.upload is a plain HTTPS request carrying the credential, independent of the device connection, so it works while the socket is down or before connect(). url never expires and is fetched without a credential, so anyone holding it can open the file; the client has no delete call, and files are removed only when the owning account is erased.

Hand the URL to the agent

Returning the URL from a command puts it in the tool result, so the model can share it in the conversation. For a device-initiated event, put the URL in a trigger payload and store or forward it in the handler.

device.ts

async function reportShelfPhoto() {
  const photo = await device.cdn.upload(readFileSync('/tmp/shelf.jpg'), 'shelf.jpg', 'image/jpeg');
  await device.trigger('shelf_photo_taken', { url: photo.url, aisle: 'A3' });
}

src/devices/ShelfPhotoTaken.ts

import { Data, defineDeviceTrigger } from 'lua-cli';
import { z } from 'zod';

export const shelfPhotoTaken = defineDeviceTrigger({
  name: 'shelf_photo_taken',
  description: 'A shelf camera uploaded a new photo',
  payloadSchema: z.object({ url: z.string().url(), aisle: z.string() }),
  async execute(payload, { device }) {
    await Data.create('shelf-photos', { device: device.name, url: payload.url, aisle: payload.aisle, at: Date.now() });
  },
});

Verify

Call the command by hand and open the returned URL.

lua devices test --device-name lobby-kiosk --command upload_logs --ci

The reply contains url; fetching it returns the file with the detected media type.

Options you may need

Download or rebuild a URL

cdn.download(fileId) fetches the bytes back (Buffer in Node, bytes in Python) and cdn.getUrl(fileId) (get_url in Python) rebuilds the URL from an ID you stored.

Files from the agent side

Code running on the platform uploads through the CDN runtime object instead of a device credential.

If it isn’t working

upload rejects with the platform's message

The credential doesn’t grant assets.upload (the CDN answers Device credentials require a designated device endpoint), or it was revoked. Issue a new credential with the operation; operations can’t be added later.

upload rejects for a large file

The cap is 100 MB per file. Compress or split the file.

Next steps

Node device client

The CDN class and CdnUploadResult.

Handle device triggers

Handlers for device-initiated events.

Laptop controller

Screenshots uploaded from a laptop.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Ship logs to your stack

Marketplace

Build with AI

Examples

Upload files from a device

Options you may need

Download or rebuild a URL

Files from the agent side

If it isn’t working

Next steps

Node device client

Handle device triggers

Laptop controller

​Options you may need

​Download or rebuild a URL

​Files from the agent side

​If it isn’t working

​Next steps

Node device client

Handle device triggers

Laptop controller

Options you may need

Download or rebuild a URL

Files from the agent side

If it isn’t working

Next steps