Build your first device

​

1. Get set up

/plugin marketplace add lua-ai-global/claude-code-lua-plugin
/plugin install lua-agent-builder@claude-code-lua-plugin
/reload-plugins
/lua-doctor

npm install -g lua-cli
lua auth configure
lua init

​

2. Issue the device credential

mkdir -p ../bench-device
lua devices credential --device-name bench-sensor --out ../bench-device/.env.device

​

3. The primitives that matter

​

4. Your first command

cd ../bench-device
npm init -y
npm install @lua-ai-global/device-client
npm install -D tsx

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: process.env.LUA_DEVICE_NAME!,
  commands: [{ name: 'read_temperature', description: 'Read the bench temperature in degrees celsius' }],
});

device.onCommand('read_temperature', async () => {
  return { temperature: 22.5, unit: 'celsius' }; // replace with a real sensor read
});

device.on('connected', () => console.log('bench-sensor connected'));
device.on('error', (err: { code?: string; message?: string }) => console.error(err.code, err.message));
device.connect().catch((err: Error) => {
  console.error(err.message);
  process.exit(1);
});

set -a; . ./.env.device; set +a
npx tsx device.ts

lua chat -m "What temperature does the bench sensor read?"

​

5. Go live and test

lua push all --force
lua version create
lua version promote <n>

lua push device --name <device> --ci --force
lua push device-trigger --name <trigger> --auto-deploy

lua devices status --device-name bench-sensor
lua devices test --device-name bench-sensor --command read_temperature --ci
lua devices test-trigger --device-name bench-sensor --trigger temperature_alert --payload '{"temperature":41.2}' --ci
lua logs --type device-trigger

​

Things that save you time

• Write the credential to a file. --out plus set -a; . ./.env.device; set +a saves copying secrets around. Use one credential per device; the agent ID and device name must match it exactly.
• Don’t use a dashboard API key on a device. It fails with AUTH_FAILED over Socket.IO and Not authorized over MQTT. Issue a device credential.
• Sign in by email. lua devices credential refuses an API-key sign-in, and a LUA_API_KEY in your shell or the project’s .env overrides the email session.
• has never connected to this agent from lua devices status means the device connected with a different name or agent, or not at all.
• lua devices list shows every device, including self-describing ones, with online, offline, or disabled.
• Use underscores in command and trigger names. Hyphens in a device name become underscores in tool names: bench-sensor → device__bench_sensor__read_temperature.
• Write descriptions for the model. A command’s description and the persona decide when the agent calls it.
• Test without chatting. lua devices test --command … --ci checks a command and lua devices test-trigger --trigger … runs a handler; both run in scripts.
• Make trigger handlers idempotent. They are delivered at least once and run up to three times.
• Reconnect daily. A self-describing device loses its command tools 24 hours after it connected, until it reconnects.
• Scaffold with Claude Code. /lua-new device and /lua-new device-trigger create, register, and compile the declarations.

​

Go deeper