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
- An owner or admin creates an enrollment token for a project.
- 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.
- 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.
- The daemon checks in every few seconds, collects the signed request, verifies it, and runs the script.
- 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 | iexexport SWIRLSOPS_ENROLLMENT_TOKEN="swe_..."
curl -fsSL https://swirls.ai/swirlsops/install | sudo --preserve-env=SWIRLSOPS_ENROLLMENT_TOKEN shThe 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.
| Field | What it is |
|---|---|
| Run name | A short name for this run, such as collect_outlook_diagnostics. Letters, numbers, dots, dashes and underscores. |
| Interpreter | PowerShell or sh. Windows devices default to PowerShell. sh is not available on Windows. |
| Timeout | How long the script may run before the daemon stops it, from 1 second to 1 hour. |
| Script | The script text, up to 512,000 characters. |
Choose Sign and queue. The run appears under Runs and moves through these states:
| Status | Meaning |
|---|---|
| Queued | Waiting for the device to check in. A queued run can be canceled. |
| Running | The device has collected the script and has not reported back yet. |
| Succeeded | The script exited with code 0. |
| Failed | The script exited with any other code. |
| Timed out | The script ran past its timeout and the daemon stopped it. |
| Refused | The daemon would not run the script. The run shows the reason. |
| Canceled | Canceled before the device collected it. |
| Expired | The device did not check in before the signed request expired. |
| No report | The 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.ps1A 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.ps1swirls 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.
| System | What service install registers |
|---|---|
| Windows | A Windows service named swirlsops, running as the system account. |
| Linux | A systemd unit at /etc/systemd/system/swirlsops.service. |
| macOS | A 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:
| Variable | What it sets |
|---|---|
SWIRLSOPS_ENROLLMENT_TOKEN | The enrollment token. Required when the machine is not enrolled yet. |
SWIRLSOPS_DEVICE_NAME | The name shown for the device. Defaults to the machine's hostname. |
SWIRLSOPS_DOWNLOAD_URL | Where 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_URL | The Swirls API the machine enrolls with. Defaults to Swirls Cloud. |
SWIRLSOPS_DATA_DIR | The 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
| Action | Who |
|---|---|
| See devices, runs and enrollment tokens | Any member who can open the project |
| Create and revoke enrollment tokens | Organization owners and admins |
| Change a device's tags | Organization owners and admins |
| Run a script on a device or a group, cancel a run | Organization owners and admins |
Deploy an operation, and the workflows and agents that run it | Anyone who can deploy to the project |
| Revoke a device | Organization owners and admins |
Agent credentials cannot read or manage devices. Enrollment, tag changes, runs and revocations are written to the audit log.
Daemon reference
| Command | What it does |
|---|---|
swirlsops enroll | Enrolls this machine. Refuses to replace an existing enrollment unless you pass --force, which enrolls the machine again as a new device. |
swirlsops run | Runs 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 --once | Checks in once, runs whatever is waiting, and exits. |
swirlsops service install | Registers the daemon as a service that starts at boot. Running it again updates the registration. |
swirlsops service start / stop | Starts or stops the service. stop waits for a running script to finish. |
swirlsops service status | Prints whether the service is installed and running. |
swirlsops service uninstall | Removes the service. The enrollment and the data directory are kept. |
| Setting | Flag | Environment variable |
|---|---|---|
| Swirls API URL | --url | SWIRLSOPS_API_URL |
| Enrollment token | --token | SWIRLSOPS_ENROLLMENT_TOKEN |
| Data directory | --data-dir | SWIRLSOPS_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.