balena
balenaCloud: manage fleets of Linux devices — inspect, configure, pin releases, and reboot or restart remotely.
About
balena ships in the w6w first-party pack. It declares 16 actions, 3 health checks, and the host runs its code in a sandbox that never sees the credential.
- App id
io.w6w.balena- Version
- 0.1.1
- Author
- w6w
- Licence
- MIT
- Categories
- IoT & Hardware · DevOps & Infrastructure
Overview
balenaCloud manages fleets of Linux devices remotely, and this app covers the everyday operations of running one: listing and inspecting fleets and devices, renaming or moving a device between fleets, pinning it to a specific release for a canary rollout, and reading or setting its environment variables and tags. It is built for workflows that manage IoT or edge hardware at scale rather than one machine at a time — grouping devices by tag, auditing which release each one is actually running, and rolling configuration changes out safely.
It also reaches into the device itself where balena’s supervisor allows it: rebooting a device, restarting its application containers, blinking an identifying LED, and purging its local data — all of which check that the device is online first, since balena has no way to queue these for later. Environment and tag changes are handled as the deployments they really are, since setting a variable triggers a container recreation, and every destructive action requires an explicit confirmation before it runs.
Build with balena
Three routes to the same 16 actions. The Workflow tab is generated from balena's own manifest and carries its real ids, so it is copy-pasteable; the Code and CLI examples are the same call for any action on any app, so every app-specific value in them is a blank you fill in.
List a device's environment
device-env-list What a device's services actually see — fleet-level, device-level and per-service variables read together, with the EFFECTIVE value and where it came from. No single balena endpoint shows the layering, and reading only one of them gives wrong answers.
Set a device environment variable
device-env-set Create, change or remove a device-level variable. balena applies it by RECREATING THE CONTAINER, so every call restarts the service. Removing restores the fleet's value; setting an empty string shadows it with an empty string, which is not the same thing.
Get a device
device-get One device, comparing what it IS running against what it SHOULD be — the comparison that says whether it is mid-update, offline or stuck. Reports how stale the supervisor metrics are, since an offline device keeps returning its last reading.
Identify a device
device-identify Blink the device's LED for fifteen seconds — the dashboard's identify button, and the way to tell which of forty identical boxes is which. Note the supervisor answers 200 whether or not the hardware HAS an LED, so a silent success is possible.
List devices
device-list Devices, with the two health fields balena reports separately: `is_online` from the VPN and `api_heartbeat_state`, whose `timeout` value is a device that has gone quiet rather than one that is gone. Requests `overall_status`, which balena omits unless asked.
Move a device to another fleet
device-move Move a device between fleets, which is a DEPLOYMENT: it picks up the new fleet's target release and starts different containers within seconds. Device-level variables and tags survive; the old fleet's FLEET-LEVEL variables do not.
Pin or unpin a device's release
device-pin-release Pin a device to a specific release — the canary pattern — or unpin it to follow its fleet's target again. Note UNPINNING is not a rollback: it means whatever the fleet currently targets, which may be newer than what the device runs.
Purge a device's data
device-purge-data DESTRUCTIVE. Clears `/data` and every named volume — years of readings, gone, with no snapshot and no undo. It also removes and recreates the containers, because a volume cannot be deleted while one holds it, so the services go down with it.
Reboot a device
device-reboot Reboot through balena's VPN. Respects the supervisor's UPDATE LOCK by default — a service holding one is saying it is mid-transaction — and reports a refusal as the healthy outcome it is. The device must be ONLINE; there is no queued reboot.
Rename a device
device-rename Give a device a meaningful name. balena does NOT enforce uniqueness, so this refuses a name already used in the same fleet unless told otherwise — a duplicate makes every lookup by name ambiguous.
Restart a device's services
device-restart-services Restart the application without rebooting the host. balena REMOVES AND RECREATES the service containers — anything in a container's writable layer is gone, while named volumes and `/data` survive. Looks up the fleet id the supervisor requires.
List device tags
device-tag-list Tags for one device, or every device carrying a given tag — the closest thing balena has to a sub-fleet. Values are always STRINGS matched exactly, so `version=2` does not find a device tagged `version=2.0`.
Set a device tag
device-tag-set Set or remove a tag — balena's only grouping between a fleet and a device, and the way a thousand devices become 'the ones in Berlin'. Unlike an environment variable a tag RESTARTS NOTHING and does not need the device online.
Get a fleet
fleet-get One fleet with the counts that make it legible: how many devices are online, how many are running something other than the TARGET RELEASE, and how many are individually PINNED — the three reasons a device is not running the new build.
List fleets
fleet-list Fleets in the organizations this credential belongs to. The unfiltered balena listing returns the platform's PUBLIC fleets too — and does so with no credential at all — so this scopes by organization membership and reports what it excluded.
List releases
release-list Builds for a fleet. A release row exists as soon as a build STARTS, so the newest one may be running or failed — this returns successful releases by default and counts the rest. Also separates INVALIDATED releases, which are withdrawn rather than deleted.
A workflow step names the app and the action, and the editor fills in the
connection when you pick one. This is the Step shape from the
workflow spec, carrying balena's real ids.
{
"manifestVersion": "2",
"name": "balena-example",
"steps": [
{
"id": "device-env-list",
"uses": {
"app": "io.w6w.balena",
"action": "device-env-list",
"connection": "conn_YOUR_CONNECTION_ID"
},
"with": {
"uuid": "<uuid>"
}
}
]
}Here are some of the things you can do
-
List a device's environment
readdevice-env-list -
Set a device environment variable
performdevice-env-set -
Get a device
readdevice-get -
Identify a device
performdevice-identify -
List devices
searchdevice-list
+11 more actions available
Every app-specific value here is a blank you have to fill in. An
app action is reached through the connection that authenticates it, so the
address is a connection id, not the app id — and connections belong to your account,
so a public page cannot know yours. Create one for balena, then fill in
the three blanks: conn_YOUR_CONNECTION_ID, the action key, and the
parameters that action declares. The call itself is real — the shape is transcribed
from the studio's own snippet builder, which prints the same kind of blanks — but
nothing in it is specific to balena. The Workflow tab is where this app's
real ids are.
npm install @w6w/sdkyarn add @w6w/sdkpnpm add @w6w/sdkdeno add npm:@w6w/sdkimport { W6wClient, isActionRun } from "@w6w/sdk";
// Reads W6W_BASE_URL and W6W_TOKEN from the environment when omitted.
const client = new W6wClient();
const envelope = await client.run({
urn: "conn_YOUR_CONNECTION_ID",
action: "device-env-list",
payload: {
uuid: "<value>",
// nameContains: "<value>",
},
});
if (isActionRun(envelope)) console.log(envelope.value);npm install -g @w6w/cliw6w run conn_YOUR_CONNECTION_ID --action device-env-list --payload '{"uuid":"<value>"}'Give an AI agent balena — without giving it balena's credentials. One MCP endpoint exposes every app, function and workflow the caller is entitled to, as tools it can discover and run. Access is granted per team while we onboard.
One tool call{
"name": "w6w_invoke",
"arguments": {
"ref": "app:io.w6w.balena#device-env-list",
"input": {
"uuid": "<uuid>"
}
}
}
Every tool names its target with a single ref. The
app: form above doesn't name a connection at all — the
host resolves which of the caller's balena connections to sign
with, and refuses rather than guesses when the answer is ambiguous.
What the agent gets
Credentials it can't read
The token is attached host-side, at the moment of the call. It is never a tool argument, never in the model's context, and never in a transcript — so a prompt injection has nothing to exfiltrate.
A tool surface scoped to the caller
Tools are derived per end user from what that person has actually connected and is entitled to — not one shared bot identity carrying the union of everyone's access.
A durable workflow in one call
Multi-step work runs on the workflow engine and returns a run handle the agent can poll — retries, branching and state survive the conversation that started them.
Health-aware discovery
balena's declared health checks are on the surface too, so an agent can tell "the vendor is down" from "your credential expired" before it burns a retry on either.
The MCP surface is part of the hosted platform. balena itself is MIT, and the runtime that executes it is source-available (FSL).
Health checks
balena declares its own checks, so its health is a property of the app rather than something the host guesses at.
balenaCloud status
Reads balena's Statuspage, weighting the API and reporting CLOUDLINK (the VPN) separately — the four supervisor actions travel over the VPN and fail independently of everything else. Names its components rather than taking the feed's worst, which includes AWS.
balena API reachable
Probes balena's UNAUTHENTICATED `/ping`, which answers the plain text `OK` — so this reads the API itself and still cannot be confused by a credential problem. It does not speak for Cloudlink, which the supervisor actions need.
Rate-limit headroom
Declared unavailable — measured live, balena publishes no rate-limit header on success or failure. What binds an account is the plan's DEVICE COUNT, and what binds a workflow is whether the device is online at all.