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
  }
}
FieldTypeRequiredDescription
command@ps, @sh, or a file referenceYesThe script. See Write the script.
labelstringNoDisplay name. Defaults to the operation name.
descriptionstringNoWhat the operation does.
platformwindows, linux or macosNoOnly devices running this system can run the operation.
timeoutnumberNoSeconds the script may run before the daemon stops it, from 1 to 3600. Defaults to 300.
inputSchema@json { } blockNoJSON Schema for the node's input. Input that does not match fails the node before anything is sent to a device.
outputSchema@json { } blockNoJSON Schema for the JSON the script prints. When set, the node returns the parsed value as result.
runAssystem or signed_in_userNoDefaults 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.

On this page