Devices

Enroll customer machines into a project, run signed scripts on them from Swirls Cloud, and read back what happened.

A device is a machine that runs the Swirls daemon, swirlsops, and is enrolled into one project. From that project you can run a script on the machine and read its exit code and output, without opening a remote session and without the machine accepting any inbound connection.

Devices are enrolled and managed through the dashboard, the swirls CLI and the API. They are not declared in .swirls source, because a machine is something a project discovers and enrolls, and it comes and goes on its own schedule. What you declare in source is an operation: a script that workflows and agents are allowed to run on your devices.

Current availability: the daemon's binaries are not code signed yet. Scripts run as the identity the daemon runs as, which is the system account when it is installed as a service.

How it works

  1. An owner or admin creates an enrollment token for a project.
  2. The daemon on a machine trades that token for a device identity. During that exchange it stores the public key Swirls uses to sign scripts for devices.
  3. Someone runs a script on the device. Swirls signs the request for that one device at that moment and holds it until the device checks in.
  4. The daemon checks in every few seconds, collects the signed request, verifies it, and runs the script.
  5. The daemon reports the exit code and output, or the reason it refused to run.

Every connection is opened by the daemon. A device needs outbound HTTPS to Swirls and nothing else, so no firewall rule, port forward or VPN is required.

Enroll a machine

Create an enrollment token

In the Swirls dashboard, open your project and choose Devices in the sidebar, then Enroll devices. You must be an organization owner or admin.

From a terminal, swirls device token create does the same thing and prints the commands for the next step.

Give the token a name, choose how many machines it can enroll, and choose when it expires. Add tags to the token, such as front-office or site:denver, and every machine that enrolls with it starts with those tags. A token for a single laptop can allow one machine and expire in an hour. A token for a rollout can allow as many machines as the rollout covers, up to 10,000, and stay valid for up to 30 days.

Copy the commands

The dialog shows the commands to run, with the token filled in. Copy them before you close the dialog. Swirls stores only a hash of the token, so it cannot show the token again.

Run the commands on the machine

Run from an elevated PowerShell:

$env:SWIRLSOPS_ENROLLMENT_TOKEN = "swe_..."
irm https://swirls.ai/swirlsops/install.ps1 | iex
export SWIRLSOPS_ENROLLMENT_TOKEN="swe_..."
curl -fsSL https://swirls.ai/swirlsops/install | sudo --preserve-env=SWIRLSOPS_ENROLLMENT_TOKEN sh

The installer downloads the daemon for the machine, checks it against the published checksums, enrolls the machine, and starts the daemon as a service so it keeps checking in after a restart. The token is read from the environment so it does not appear in the machine's process list.

Confirm the device is online

The machine appears on the Devices page as soon as it enrolls, named after its hostname. Pass --name to enroll to choose another name. A device shows Online while the daemon is checking in and Offline once it has been quiet for about a minute and a half.

Run a script

On the Devices page, choose Run script beside a device.

FieldWhat it is
Run nameA short name for this run, such as collect_outlook_diagnostics. Letters, numbers, dots, dashes and underscores.
InterpreterPowerShell or sh. Windows devices default to PowerShell. sh is not available on Windows.
TimeoutHow long the script may run before the daemon stops it, from 1 second to 1 hour.
ScriptThe script text, up to 512,000 characters.

Choose Sign and queue. The run appears under Runs and moves through these states:

StatusMeaning
QueuedWaiting for the device to check in. A queued run can be canceled.
RunningThe device has collected the script and has not reported back yet.
SucceededThe script exited with code 0.
FailedThe script exited with any other code.
Timed outThe script ran past its timeout and the daemon stopped it.
RefusedThe daemon would not run the script. The run shows the reason.
CanceledCanceled before the device collected it.
ExpiredThe device did not check in before the signed request expired.
No reportThe device collected the script and never reported a result.

Open a run to read its output, its errors and the exact script that was signed. Output is kept up to 1 MB per stream, and a longer stream is cut off and marked.

A run queued from the dashboard waits one hour for the device to check in. Through the API you can set that window anywhere from 30 seconds to one day, and pass a JSON input that the script receives on standard input.

A run that reaches a device is run once. If the daemon or the machine stops partway through a script, the script is not started again when the daemon comes back, because repeating a script that changes a machine is the more dangerous failure.

Tag devices and run on a group

Tags group devices so one request can reach all of them. A tag is lowercase and may hold letters, numbers, dots, dashes, underscores and colons, so both kiosk and site:denver work. A device can carry up to 32.

Devices get tags in two ways. An enrollment token can carry tags that every machine enrolling with it starts with, and an owner or admin can change a device's tags at any time with Tags beside the device, or with swirls device tag.

To run a script on a group, choose Run on a group on the Devices page and pick the devices by tag, by operating system, or both. A device matches when it has every tag you list and runs the system you chose. The dialog shows which devices match before anything is queued.

swirls device run --tag front-office --os windows --script ./restart-spooler.ps1

A group run works like this:

  • The group is fixed when you queue the run. A device enrolled or tagged a moment later is not part of it.
  • Each device gets its own signed request and its own run, so one device's result never depends on another's. A request signed for one device is refused by every other device.
  • Revoked devices are never included. Offline devices are included and run the script when they next check in, if that is before the request expires.
  • A selector has to name at least one tag or a system. There is no way to select every device by leaving the selector empty.
  • One group run reaches at most 500 devices. Narrow a larger group with another tag.

Run a script from the CLI

swirls device run queues a script, waits for the device to run it, and prints what the script printed. It exits with the script's exit code, so it fits into a shell script or a pipeline the way the script itself would.

swirls device run FRONT-DESK-01 --script ./collect-outlook-logs.ps1

swirls device list shows what is enrolled, swirls device runs shows recent runs, and swirls device result <run-id> prints one run's output again. The CLI reference covers every command and flag.

Run operations from workflows and agents

A script queued from the Devices page or the CLI is written by the person who queues it. For anything a workflow or an agent should be able to run, declare an operation in your .swirls source and run it with a device node.

operation restart_print_spooler {
  platform: windows
  command: @ps {
    Restart-Service -Name Spooler -Force
    Get-Service -Name Spooler | Select-Object -ExpandProperty Status
  }
}

A device node names the operation and the devices: one device by id, or a group by tags and operating system. The script that runs is always the one in your deployed source, so a workflow or an agent chooses which approved script runs and where, and never supplies script text of its own. Runs started by a workflow appear under Runs like any other.

Install the daemon as a service

swirlsops service install registers the daemon with the operating system so it starts at boot and is restarted if it stops with an error. swirlsops service start, stop, status and uninstall manage it from there.

SystemWhat service install registers
WindowsA Windows service named swirlsops, running as the system account.
LinuxA systemd unit at /etc/systemd/system/swirlsops.service.
macOSA LaunchDaemon at /Library/LaunchDaemons/ai.swirls.swirlsops.plist.

Stopping the service lets a script that is already running finish and report first. Under a service the daemon writes its log to logs/swirlsops.log in the data directory.

The installer from Enroll a machine does the whole job on a new machine: it downloads the binary for the machine, checks it against the published checksums, enrolls, installs the service and starts it. Running it again upgrades the binary in place and skips enrollment, so the same two lines work for a new machine and for an upgrade, and an upgrade needs no token.

The binary is installed to C:\Program Files\Swirls\swirlsops\swirlsops.exe on Windows and /usr/local/bin/swirlsops on Linux and macOS. The binaries, their SHA256SUMS file and a VERSION file are published at https://releases.swirls.ai/swirlsops/latest/, and every release is kept at https://releases.swirls.ai/swirlsops/v<version>/.

The installer reads its settings from the environment:

VariableWhat it sets
SWIRLSOPS_ENROLLMENT_TOKENThe enrollment token. Required when the machine is not enrolled yet.
SWIRLSOPS_DEVICE_NAMEThe name shown for the device. Defaults to the machine's hostname.
SWIRLSOPS_DOWNLOAD_URLWhere the binaries and SHA256SUMS are downloaded from, which must be an https:// address. Set it to a versioned folder to pin a release, or to a mirror you host.
SWIRLSOPS_API_URLThe Swirls API the machine enrolls with. Defaults to Swirls Cloud.
SWIRLSOPS_DATA_DIRThe data directory, when it is not the default.

On macOS and Linux, name every variable you set in --preserve-env, because sudo drops the rest of the environment.

On Windows, enrolling and installing the service limit the data directory to the system account and administrators, because it holds the device's identity.

What the daemon checks before it runs a script

The daemon treats everything it receives as untrusted until it has verified it. A script runs only when all of these hold:

  • The request carries a valid signature from the key the device stored at enrollment.
  • The request names this device.
  • The request is inside its validity window.
  • The script hashes to the exact value the signed request names.
  • The device has not already accepted a request with the same run id.

When a check fails, nothing runs and the run is marked Refused with the reason, such as script_mismatch or expired.

Revoke a device or a token

Choose Revoke beside a device to cut it off. Its identity stops working on its next check-in and the runs it has not collected are canceled. To bring the machine back, enroll it again with a new token. It returns as a new device.

Revoking an enrollment token stops more machines from enrolling with it. Devices that already enrolled with that token stay enrolled.

Who can do what

ActionWho
See devices, runs and enrollment tokensAny member who can open the project
Create and revoke enrollment tokensOrganization owners and admins
Change a device's tagsOrganization owners and admins
Run a script on a device or a group, cancel a runOrganization owners and admins
Deploy an operation, and the workflows and agents that run itAnyone who can deploy to the project
Revoke a deviceOrganization owners and admins

Agent credentials cannot read or manage devices. Enrollment, tag changes, runs and revocations are written to the audit log.

Daemon reference

CommandWhat it does
swirlsops enrollEnrolls this machine. Refuses to replace an existing enrollment unless you pass --force, which enrolls the machine again as a new device.
swirlsops runRuns the daemon until it is stopped. A script that has already started is allowed to finish and report first. Exits with an error when the device has been revoked.
swirlsops run --onceChecks in once, runs whatever is waiting, and exits.
swirlsops service installRegisters the daemon as a service that starts at boot. Running it again updates the registration.
swirlsops service start / stopStarts or stops the service. stop waits for a running script to finish.
swirlsops service statusPrints whether the service is installed and running.
swirlsops service uninstallRemoves the service. The enrollment and the data directory are kept.
SettingFlagEnvironment variable
Swirls API URL--urlSWIRLSOPS_API_URL
Enrollment token--tokenSWIRLSOPS_ENROLLMENT_TOKEN
Data directory--data-dirSWIRLSOPS_DATA_DIR

The data directory holds the device's identity and its record of the runs it has accepted. It defaults to C:\ProgramData\Swirls\swirlsops on Windows, /Library/Application Support/Swirls/swirlsops on macOS and /var/lib/swirlsops on Linux. Anyone who can write to it can change which signing key the device trusts, so keep it writable only by the account the daemon runs as.

The daemon uses the operating system's TLS stack, certificate store and proxy settings. A root certificate your organization has installed on the machine is honored without any daemon configuration.

Use the API

Everything on the Devices page is available through the SDK devices client and the swirls device commands: create enrollment tokens, list devices, queue runs and read their results.

On this page