Operation
Declare a script that runs on enrolled devices, and run it from a workflow with a device node.
What it is. An operation is a named script, written in PowerShell or sh, that runs on machines enrolled into your project as devices. A workflow runs it with a type: device node.
Use it when a workflow or an agent has to act on a real machine: read its event logs, restart a service, check disk space, or apply a fix.
Works with devices, which are enrolled through the dashboard, CLI or API, the device node, and agents, which reach devices through tool workflows.
Devices are never declared in .swirls source. A machine is enrolled into the project, and a node names it at run time, by id or by tags. What you write and review in source is the operation: the exact script that is allowed to run.
Declare an operation
operation collect_outlook_errors {
label: "Collect Outlook errors"
description: "Counts recent Outlook errors in the Application log."
platform: windows
timeout: 120
inputSchema: @json {
{
"type": "object",
"properties": {
"lookbackHours": { "type": "integer", "minimum": 1, "maximum": 24 }
},
"required": ["lookbackHours"],
"additionalProperties": false
}
}
outputSchema: @json {
{
"type": "object",
"properties": { "errorCount": { "type": "integer", "minimum": 0 } },
"required": ["errorCount"]
}
}
command: @ps {
$request = [Console]::In.ReadToEnd() | ConvertFrom-Json
$since = (Get-Date).AddHours(-$request.lookbackHours)
$errors = Get-WinEvent -FilterHashtable @{
LogName = 'Application'; ProviderName = 'Outlook'; Level = 2; StartTime = $since
} -ErrorAction SilentlyContinue
@{ errorCount = @($errors).Count } | ConvertTo-Json
}
}| Field | Type | Required | Description |
|---|---|---|---|
command | @ps, @sh, or a file reference | Yes | The script. See Write the script. |
label | string | No | Display name. Defaults to the operation name. |
description | string | No | What the operation does. |
platform | windows, linux or macos | No | Only devices running this system can run the operation. |
timeout | number | No | Seconds the script may run before the daemon stops it, from 1 to 3600. Defaults to 300. |
inputSchema | @json { } block | No | JSON Schema for the node's input. Input that does not match fails the node before anything is sent to a device. |
outputSchema | @json { } block | No | JSON Schema for the JSON the script prints. When set, the node returns the parsed value as result. |
runAs | system or signed_in_user | No | Defaults to system: the identity the daemon runs as. Devices refuse signed_in_user for now. |
An operation name may be up to 128 characters.
Write the script
command takes the script in one of two forms.
An inline block holds the script between braces. Use @ps for PowerShell and @sh for sh. The indentation that every line shares is removed, so you can indent the script to sit inside the operation.
operation disk_space {
command: @sh {
df -h /
}
}A file reference points at a script beside your .swirls files. The path is relative to the file that declares the operation, @ps takes a .ps1 file and @sh takes a .sh file. The file is read when you deploy, byte for byte.
operation reset_onedrive {
platform: windows
command: @ps "scripts/reset-onedrive.ps1"
}Use a file for a long script, and for a script that holds a quotation mark inside $( ) within a double-quoted string, which an inline block does not read correctly.
A script gets its input as JSON on standard input and reports by printing to standard output. @sh scripts cannot run on Windows devices.
What gets signed
When you deploy, each operation's script is stored with the SHA-256 hash of its bytes, and the API checks that hash. Each time a node runs the operation, Swirls signs a request for one device that names that hash. The daemon on the device runs the script only when the bytes it received hash to the value in the signed request.
The script that runs on a machine is therefore the script in your deployed source. A workflow chooses which operation runs, on which devices, and with what input. It cannot supply script text of its own.
Run it from a workflow
A device node runs an operation on one device or on a group.
workflow triage_outlook {
label: "Triage Outlook"
description: "Counts recent Outlook errors on one device."
root {
label: "Start"
type: code
inputSchema: @json {
{
"type": "object",
"properties": { "deviceId": { "type": "string" } },
"required": ["deviceId"]
}
}
code: @ts { return context.nodes.root.input }
}
node inspect {
type: device
operation: collect_outlook_errors
device: @ts { return context.nodes.root.output.deviceId }
input: { lookbackHours: 4 }
}
flow { root -> inspect }
}context.nodes.inspect.output.result.errorCount is then available to the nodes downstream.
Let an agent use it
Agents reach devices through workflows. List a workflow that contains a device node in the agent's tools, and the agent can call it with a device id.
secret llm { vars: [OPENROUTER_API_KEY] }
agent helpdesk {
secrets: llm
model: "anthropic/claude-sonnet-4"
tools: [triage_outlook]
}The agent decides when to call the workflow and with which device. The script it causes to run is still the one in the operation. A device node may be the last node of a tool workflow without an output schema, because its output shape is fixed.
Ask a person first
A device node cannot carry a review, because a review replaces a node's own work with the approval form. Put the review on a node upstream of the device node, so the script is only sent once a person has approved.
Current limits
- An operation's script is fixed at deploy. A workflow or agent cannot write a new script at run time.
- Devices refuse
runAs: signed_in_user. Scripts run as the identity the daemon runs as. - A script's child processes are not stopped when it times out. Only the interpreter is.