what you can do

Devices

Devices — what you can do

/admin/d/devices · pillar devices

Every device you can reach - this browser, this machine, paired computers, and hardware that moves.

Fetch this, never remember it

These change per install and per release. Call for them - a list written here would be a future lie.

What	Call	Why
every device this Studio can currently reach	`list_devices`	devices arrive from several fleets and a fleet can be unreachable on this deployment; the answer is different on every install and on every day
which paired machines are online and what each will run	`list_fabric_capabilities`	`GET /api/fabric/capabilities`	A CAPABILITY IS OFFERED BY A MACHINE, NOT BY THE FABRIC - the index is derived from what nodes advertise right now, so it changes as machines come and go
whether the fabric is even present on this install	`fabric_status`	`GET /api/fabric/status`	on a hosted install the fabric routes are absent rather than empty, and absent is a different answer from "no machines"
the protocols this build can speak to a device	`list_device_drivers`	the driver catalogue is what Leumas has code for, and `can` is DERIVED from what each driver actually implements - a verb missing from it is a real limitation, not an oversight
the machines physically attached to this computer	`GET /api/machines`	this lane exists ONLY on an install with the hardware attached, so its absence is the normal state on a hosted Studio. route-ok: mounted by `mountLocalHardware` in products/leumas-api/src/planes/appliance.js and therefore absent from the recorded route table, which is captured without local hardware

How to actually do things here

Written by hand, because the order and the traps are the part no file can derive.

Answer "what hardware do I have, and can I talk to it?"

list_devices FIRST — every other tool takes an id from it.
Read unreachableFleets on the result BEFORE saying a device does not exist. A hosted Studio has no machine to inspect, and that is not the same as an empty estate.
get_device for one, device_summary for the shape of the whole estate.
select_device and open_device_tab move the operator’s view, so they can see what you mean.

Trap: The page tools are READ-ONLY. They will not stop a process, delete a device or move a machine — the HTTP lane does that, on an install that has the hardware.

Send a print or a cut to a machine

This is the machines lane, and it only exists where the hardware is attached. GET /api/machines lists them; GET /api/machines/printers is the printer-shaped view.
Get a PROGRAM in — there are three doors and they all end in the same place. Already-sliced G-code: POST /api/machines/programs with the text. A 3D model: POST /api/machines/:id/slice (bytes go base64, not multipart; GET /api/machines/slice/status says whether a slicer is even installed). A board you designed: POST /api/machines/cam/pcb, with GET /api/machines/cam/profiles for the profiles.
The create call returns the PREFLIGHT SCAN — time, peak temperature, bounding box. That scan is the product of the call, so read it rather than discarding it.
Take the machine: POST /api/machines/:id/claim, then POST /api/machines/:id/connect. Only one session may hold a machine at a time.
POST /api/machines/:id/preflight before anything moves. Then POST /api/machines/:id/jobs with the program id.
Watch GET /api/machines/:id/stream. Control it with POST /api/machines/:id/jobs/pause, /resume or /cancel. Release it when done: POST /api/machines/:id/release.

Trap: [critical] THIS WORKS FOR A MACHINE ATTACHED TO THIS COMPUTER. A machine reached through a PAIRED NODE cannot be started from here: the node side is complete, but the control plane never calls its start verb, so a remote machine answers "connect the machine first" forever no matter how many times it is retried. Say that plainly rather than looping. CONFIRM WITH THE OPERATOR BEFORE ANYTHING MOVES — a machine cuts, heats and moves next to a person, and a job has no undo. A claim is a 15-minute lease renewed by each command, and it is exclusive: a refusal means somebody else holds it, which is a conversation rather than a retry. POST /api/machines/:id/estop is the stop of last resort and deliberately does NOT require the claim — a safety stop that needs a lock first is not a safety stop. route-ok: this whole lane is mounted by mountLocalHardware in planes/appliance.js, so it exists only on an appliance or dev install and is absent from the recorded route table, which was captured before it landed.

Run work on another computer the operator owns

fabric_status first — the fabric may not be present at all on this install.
list_fabric_capabilities for what the paired machines actually offer. Ask for a capability, never for a named computer: choosing the machine is the scheduler’s job.
POST /api/fabric/run places the job.
Follow it with list_fabric_jobs and fabric_job_events.

Trap: [critical] A FRESHLY PAIRED MACHINE RUNS NOTHING. The allowlist ships empty, so the first answer is usually a refusal — and the two refusals mean different things: "no node offers this" and "nodes offer it but all are offline" send an operator to two completely different places. fabric_node says what one machine will and will not accept, and why. Placing work is ADMIN-ONLY, and the reply is a job id with status 202 — never a result, because a capability may run for an hour and an HTTP request held open that long dies to a proxy timeout with the work still running and nobody able to find it. An unsatisfiable job fails immediately and names the requirement it could not meet.

Move a file or an asset between machines

fabric_storage_summary for what the fabric is holding and where.
list_fabric_objects for the objects themselves. An object is content-addressed and replicated, so it outlives the machine it was born on.
Pin it where it is needed: POST /api/fabric/objects/:objectId/pin, and DELETE the pin to let it drift again.
GET /api/fabric/storage is the per-node view of what is stored.

Trap: [critical] NO BYTE OF AN OBJECT PASSES THROUGH THE API. There is no upload route and no download route, by design — an object is content-addressed and enters the index only when a node ANNOUNCES that it holds it, and it is read by talking to a machine that has it. Studio holds the index, not the data, so its disk is never the ceiling on the fabric. Pinning keeps a copy on a node; an unpinned one may move. POST /api/fabric/media/stage is a DIFFERENT job — it writes an installer kit onto a removable drive so a new machine can join, and it is the only route here that writes the filesystem of the computer Studio runs on.

Work out why something will not connect

Serial: list_serial_ports, then serial_port_holder — a port already held by another session is the usual answer.
Network: list_network_adapters, list_connections, and adapter_throughput for live rates.
Ports: list_listening_ports, then port_owner names the process sitting on it.
IoT: list_device_drivers is the protocol CATALOGUE — what Leumas has code for, not what the operator owns.

Trap: unavailableHere is about THIS BROWSER, not the driver. Web Bluetooth and Web Serial do not exist in Firefox or on iOS and need a secure context. Never report that as broken hardware. Pairing is a browser permission gesture that only a real click can start.

Tabs

Every one is a real URL. A tab with its own section below carries a real job.

Tab	Path	Group	What it is for
`all`	-	Everything	Every reachable device across every fleet. The entry point — ids come from here.
`audio`	-	This browser	Every speaker in this home, ticked and played: outputs on this computer, on paired machines, on Chromecasts, on UPnP televisions and on Rokus. The front page finds them, groups them and proves one works.
`audio/share`	-	This browser	Send what one machine is playing to Studio windows on the others, and choose which output each of them uses.
`audio/speakers`	-	This browser	Where every speaker came from — which protocol answered, what identifies it, and which addresses it has been seen at.
`audio/sync`	-	This browser	Measure the real latency — the socket round trip, the output path of this machine, and what a microphone actually hears.
`audio/browser`	-	This browser	Speakers and outputs THIS BROWSER can play through, and the test tone that proves one works.
`cameras`	-	This browser	Cameras this browser can open — and only after the person grants it.
`mics`	-	This browser	Microphones this browser can open, under the same permission gesture.
`bluetooth`	-	This browser	Bluetooth devices already paired with this machine.
`wifi`	-	This machine	Where this machine sits on the network, and which adapters it has.
`ports`	-	This machine	What is listening on this machine, and which process owns it.
`traffic`	-	This machine	Live connections and throughput per adapter.
`fabric`	-	The fabric	Machines paired into the fabric: presence, capabilities, and what each one refuses.
`compute`	-	The fabric	Machines offering compute, and what each is willing to run.
`compute/jobs`	-	The fabric	Work handed to a compute node, and how each run ended.
`capabilities`	-	The fabric	The whole capability index — every verb the paired machines currently offer.
`jobs`	-	The fabric	Every fabric job, its events and how it finished.
`storage`	-	The fabric	What the fabric is holding, where the copies are, and which are pinned.
`installer`	-	The fabric	Make the media a new machine joins from — an installer kit written to a removable drive.
`iot`	-	Machines	The driver catalogue — the protocols Leumas can speak, not the devices the operator owns.
`printers`	-	Machines	The 3D printers this machine can reach, their state, and the jobs running on them.
`cnc`	-	Machines	CNC mills, routers and PCB machines — state, claim and the running job.
`engraving`	-	Machines	Laser engravers and markers — the fleet, the machine console, and the artwork lane that turns a photo, an SVG, a line of text or a raw program into something the beam can run.
`serial`	-	Machines	Serial ports on this machine, and which session is holding each one.
`base8`	-	Machines	The ten-key macro pad: bind any key to anything this Studio can do.
`sensors`	-	Machines	Sensor channels and their live readings.
`sensors/layout`	-	Machines	Where each sensor physically sits, so a reading has a place attached to it.
`sensors/recordings`	-	Machines	Captured sensor history, for what already happened rather than what is happening.
`remotes`	-	Machines	Remote controls and input devices bound to this Studio.
`tv`	-	Machines	Every smart television and streaming player on this network — find them, keep them indexed, and drive each one with a remote. Roku, Vizio SmartCast and Google Cast, behind one vocabulary.
`remote`	`/admin/tv`	-	The TV remote on its own page, at /admin/tv — the fleet picker, the remote, quick actions and a "play <title>" box, plus the television tools the Leviathan assistant uses.

Tabs in focus

`all` - All devices

Every reachable device across every fleet. The entry point — ids come from here.

Read with: list_devices | device_summary | get_device | fabric_status | list_fabric_capabilities

Write with: select_device | open_device_tab | refresh_devices

list_devices, then check unreachableFleets before drawing any conclusion about what is missing.
get_device for detail; select_device and open_device_tab to show the operator.

Trap: The only writes here move the operator’s VIEW. Nothing on this tab commands hardware.

`audio` - Audio

Every speaker in this home, ticked and played: outputs on this computer, on paired machines, on Chromecasts, on UPnP televisions and on Rokus. The front page finds them, groups them and proves one works.

Trap: TWO CONTROLS THAT SOUND ALIKE ARE NOT THE SAME THING. "Play a test sound" makes a short tone come out of everything ticked and works on every kind of speaker listed. "Share this computer's sound" sends a live stream to other Studio WINDOWS only — a Chromecast or a television fetches audio from an address and cannot receive it, and no lane exists that would let it. Never describe one as the other. A group is also as tight as its LOOSEST member, never an average.

`audio/share` - Audio → Share sound

Send what one machine is playing to Studio windows on the others, and choose which output each of them uses.

Trap: A SPEAKER THAT IS PLAYING IS NOT A SPEAKER THAT IS IN SYNC. Latency on this path is a few hundred milliseconds, because it is the browser one — getDisplayMedia in, MediaSource out. Quote the number the Sync Lab measured, never a target. The capturing machine is refused as a speaker of its own session, structurally, because loopback capture would feed its own output straight back in.

`audio/speakers` - Audio → How they were found

Where every speaker came from — which protocol answered, what identifies it, and which addresses it has been seen at.

Trap: An address that answered no discovery protocol is a CANDIDATE, never a speaker: it looks selectable and would never play. A speaker identified by its NAME is re-identified if somebody renames the device, which loses its saved delay. Multicast DNS finds Chromecasts and AirPlay; UPnP finds televisions and Rokus — a network that blocks either simply has fewer speakers on it, which looks identical to a home that has fewer.

`audio/sync` - Audio → Line them up

Measure the real latency — the socket round trip, the output path of this machine, and what a microphone actually hears.

Trap: Every number here was measured on THIS rig. Skew between two speakers is self-calibrating and worth acting on; a single-speaker reading includes the microphone path and is not the latency of that speaker alone. A median without its spread is not a measurement.

`bluetooth` - Bluetooth

Bluetooth devices already paired with this machine.

Read with: list_paired_bluetooth

Write with: refresh_paired_bluetooth

Trap: Pairing a NEW device is a browser permission gesture only a real click can start, and Web Bluetooth does not exist in every browser. An absent device may be an absent API.

`wifi` - WiFi

Where this machine sits on the network, and which adapters it has.

Read with: network_position | list_network_adapters

Write with: refresh_network

`ports` - Ports

What is listening on this machine, and which process owns it.

Read with: list_listening_ports | port_owner

Write with: refresh_ports

Trap: Freeing a port kills somebody’s process. That is an operator decision, and it is not a page tool.

`traffic` - Traffic

Live connections and throughput per adapter.

Read with: list_connections | adapter_throughput

`fabric` - Fabric

Machines paired into the fabric: presence, capabilities, and what each one refuses.

Read with: list_fabric_nodes | fabric_node

Write with: fabric_update_status | refresh_fabric

list_fabric_nodes for who is paired and who is online.
fabric_node for one machine — what it advertises, and what its policy will not allow.

Trap: Pairing, approving and revoking a node are operator decisions taken on this tab, not tool calls. A node that is paired but offline is a different problem from one that refuses the work.

`compute` - Compute

Machines offering compute, and what each is willing to run.

Read with: list_fabric_capabilities

Trap: A capability is offered by a MACHINE. If nothing advertises it, the honest answer is that this fabric cannot do it — not that the job is queued.

`compute/jobs` - Compute → Jobs

Work handed to a compute node, and how each run ended.

Read with: list_fabric_jobs | fabric_job_events

`capabilities` - Capabilities

The whole capability index — every verb the paired machines currently offer.

Read with: list_fabric_capabilities

Trap: Derived, never stored: it changes the moment a machine goes offline.

`jobs` - Jobs

Every fabric job, its events and how it finished.

Read with: list_fabric_jobs | fabric_job_events

Write with: refresh_jobs

`storage` - Storage

What the fabric is holding, where the copies are, and which are pinned.

Read with: fabric_storage_summary | list_fabric_objects

Write with: refresh_storage

fabric_storage_summary for the shape.
list_fabric_objects for the objects, then pin one where it is needed.

Trap: An object is content-addressed and replicated — it outlives the machine it was born on. An unpinned copy may move.

`installer` - Installer

Make the media a new machine joins from — an installer kit written to a removable drive.

Trap: This is a FILESYSTEM WRITE to a real drive, not a transfer to a device. It is how a machine is enrolled, not how work reaches one.

`iot` - IoT

The driver catalogue — the protocols Leumas can speak, not the devices the operator owns.

Read with: list_device_drivers | device_driver

Trap: can is DERIVED from what each driver implements, so a missing verb is a real limitation. unavailableHere is about this browser, not the driver.

`printers` - 3D printers

The 3D printers this machine can reach, their state, and the jobs running on them.

The page tools here are named at RUNTIME (one hook serves printers and CNC), so call listTools on the live page rather than assuming a name.
To actually print: add a program, slice it for the machine, claim it, preflight, then start the job — the "Send a print or a cut" recipe above is the whole sequence.

Trap: Two firmware FAMILIES are supported — GRBL and Marlin — with a variant of each. Klipper, OctoPrint, Moonraker, Repetier and Smoothie are NOT, and a Klipper port does not even speak G-code. What a machine can do is DERIVED from its dialect: a verb the firmware lacks is refused as "cannot", not as an error. A motion verb is accepted only while the machine is idle or paused, and a temperature above the machine ceiling is refused with the ceiling. Serial needs an optional native module; without it every serial call refuses honestly rather than throwing.

`cnc` - CNC / PCB

CNC mills, routers and PCB machines — state, claim and the running job.

Trap: Same lane and same rules as printers, with less margin for error: these cut. The CAM door takes a designed board and its drill file, nothing else. Engravers are NOT here any more — they have their own tab, which is also where the image lane lives. Preflight before anything moves.

`engraving` - Engraving

Laser engravers and markers — the fleet, the machine console, and the artwork lane that turns a photo, an SVG, a line of text or a raw program into something the beam can run.

Page tools here are READ-ONLY. Nothing on this page fires a beam, jogs a head or starts a job from a tool call, and that is deliberate: the line here is not irreversible, it is PHYSICAL, and the operator may have their hands in the machine.
To engrave headlessly: POST /api/machines/:id/art to make the program, POST /api/machines/:id/art/frame to trace where it will land, then POST /api/machines/:id/jobs to run it. Full paths, because an abbreviated one is a 404 an agent cannot explain.

Trap: THE BEAM WILL NOT FIRE AT ALL unless the machine row records an interlock (flags.laserInterlockFitted) — that is a refusal, not a fault, and it now applies to a running JOB and not only to the manual beam control. FRAME BEFORE YOU RUN: the frame traces the artwork outline at about 1% so the operator can see where it lands, and it is the cheapest thing on this page. Peak power in the program is checked against ceilings.laserPercent, and an S word above the controller's $30 is refused because GRBL CLIPS rather than scaling. Progress is ACKNOWLEDGED lines, which can be half a minute behind the head.

`serial` - Serial

Serial ports on this machine, and which session is holding each one.

Read with: list_serial_ports | serial_port_holder

Write with: rescan_serial_ports

Trap: A port already held is the usual reason a machine will not connect — check the holder before blaming the hardware.

`sensors` - Sensors

Sensor channels and their live readings.

Read with: list_sensor_channels | read_sensor_channel

Write with: refresh_sensors

`tv` - TVs

Every smart television and streaming player on this network — find them, keep them indexed, and drive each one with a remote. Roku, Vizio SmartCast and Google Cast, behind one vocabulary.

Ask what this build can talk to FIRST: GET /api/tv/drivers. Each vendor carries can flags derived from what it implements and a notes object stating its limits in words. route-ok: mounted by mountTv inside caps.localHardware.
Find what is there: POST /api/tv/discover (admin). Every driver is asked at once; byDriver says how many each found. route-ok: same mount.
List what is known: GET /api/tv/devices. Offline devices are INCLUDED with a lastSeenAt, and each row carries driverLabel and needsPairing. route-ok: same mount.
Read one, live: GET /api/tv/devices/:id — gives actions (the buttons THAT device really has), what is playing, the current input, and can. route-ok: same mount.
Press a button: POST /api/tv/devices/:id/command with { action } — an action NAME (home, select, volumeUp), never a vendor protocol key. route-ok: same mount.
Pair a Vizio before using it: POST /api/tv/devices/:id/pair with {step:"start"} puts a PIN on the screen, then {step:"finish", pin, token, challenge}. Admin-gated, because it mints a credential. route-ok: same mount.
Apps, text and inputs: GET /api/tv/devices/:id/apps then POST .../apps/:appId/launch; POST .../text; GET .../inputs then POST .../input. route-ok: same mount.
The same verbs are on the adapter surface as tv.* (POST /api/adapters/tv/<verb>), which is what an MCP client, a chatbot and a workflow node reach. Identical behaviour, but METERED — use /api/tv for anything interactive.

Trap: ASK THE DEVICE WHAT IT CAN DO, AND ASK THE VENDOR FIRST. The three drivers are not equivalent and the differences are not cosmetic. [critical] A GOOGLE CAST DEVICE HAS NO REMOTE AT ALL — the buttons live behind the binary CASTV2 protocol on port 8009, which Leumas does not speak, so can.command is false and there is nothing to press. [critical] A VIZIO CANNOT BE TYPED INTO and has no play/pause: SmartCast has no text endpoint, and no publicly confirmed transport key codes, so those are absent rather than guessed. [critical] A VIZIO MUST BE PAIRED before anything but its power state can be read, and pairing needs a human to read a PIN off the screen — an agent cannot complete it alone. A ROKU PLAYER has no volume and cannot be turned on over the network once fully off; a Roku TV has both. apps reports inventory: "device" when the list was read off the television and "catalog" when it is what that model usually carries — only Roku can be asked, so a Vizio or Cast entry may simply not be installed and launching it will quietly do nothing. wake reports that an ATTEMPT was made, never that the screen came on. Discovery is per-vendor and mostly SSDP, which does not cross subnets; a device on another network is added by address instead.

`remote` - TV remote

The TV remote on its own page, at /admin/tv — the fleet picker, the remote, quick actions and a "play <title>" box, plus the television tools the Leviathan assistant uses.

Address: /admin/tv

This page registers LIVE TOOLS while it is open: list_tvs, describe_tv, select_tv, press_button, open_app, play_title, type_text, set_power. They are what let somebody say "put Netflix on the living room TV" rather than clicking.
ALWAYS call describe_tv before pressing anything. It returns the buttons THIS device actually has, whether it can search, what is playing, and what that brand cannot do, in words.
To play a specific film or show, prefer play_title — it asks the television to search every service it has. Use open_app only when somebody names an app rather than a title.

Trap: THE PAGE AND THE TVs TAB ARE THE SAME COMPONENTS IN DIFFERENT FRAMES, not two implementations — the tab is for managing televisions (find, pair, rename), this page is for using one. [critical] NEVER SAY SOMETHING IS PLAYING. No television here reports that: play_title returns "asked the TV to find and open X", and a model that upgrades that to "it is on now" is telling somebody a fact while they look at a search screen. play_title only exists on Roku — check canSearch before offering it, or a Vizio owner is promised something that cannot happen. A device that needs pairing cannot be driven at all, and pairing needs a person to read a code off the screen, so an agent must stop and say so rather than retrying.

Ways in

Declared cross-links. Every address is matched against the real route table by check:huds.

From	Does	Go to
`devices/hub:fabric`	Make a stick	`/admin/d/devices/installer`
`devices/hub:compute`	What it will run	`/admin/d/devices/capabilities`

Tools an agent can call here

These are live page capabilities: they exist only while that surface is open, and they call the page's own mutators, so a change made through one is a change the operator can see. A tool missing from this list is not callable — reach for the API or an adapter instead.