Key concepts
Suta has three parts: the Suta app at app.suta.dev, the Suta agent that runs on each device, and the Suta CLI on your computer. People, CI jobs and AI agents all work through the app, which checks what each of them is allowed to do.
Workspaces
Section titled “Workspaces”A workspace holds your projects and the people who manage them. Everyone in a workspace has a role that controls what they can do. You can belong to more than one workspace and switch between them, for example to keep separate customers or teams apart.
Projects
Section titled “Projects”A project is one fleet: its devices, the suta.yaml that describes what they
run, and every plan and rollout that changed them. Use a project for each kind
of device you run, for example one for your delivery drones and one for your
warehouse robots. Each device belongs to exactly one project, and each project
deploys on its own. See Projects.
Devices
Section titled “Devices”When the Suta agent first starts, it creates a private key on the device. The key never leaves the device and is the device’s identity. The first workspace to claim a device owns it.
The agent checks in with Suta every few seconds. A device shows as Online only while those check-ins arrive. If they stop for 30 seconds, it shows as Offline, and anything you see about it is labelled as the last value it reported.
Devices connect out to Suta over HTTPS. You never need to open a port or set up a VPN to reach them.
Generations
Section titled “Generations”A generation is everything a device runs, fixed in one version: the Suta OS version, each app’s container image and settings, the secrets it uses and its persistent volumes. Every change to a device, however small, gives it a new generation.
Because a generation pins exact image digests and secret versions, you always know what a device runs, and two devices on the same generation run the same thing.
Names you choose and names Suta makes
Section titled “Names you choose and names Suta makes”Every deploy-related name is either yours or Suta’s, never a mix:
| Name | Who makes it | Example | What it names |
|---|---|---|---|
| Deploy message | You, with suta plan -m or suta deploy -m |
“Fix sensor calibration” | A plan and its rollout. Shown in quotes. |
| App, device, site and project names | You, in suta.yaml or the dashboard |
web, kitchen-pi |
What they say |
| Generation ID | Suta: the hash of the generation’s contents | 3f9a2c71b0de |
One generation, the same on every device that runs it |
| Deploy number | Suta: counts the deploys to one device | deploy #7 | The 7th time this device was given a generation, by a rollout, rollback, retry or move to Suta OS |
| Plan and rollout IDs | Suta | 8c41… |
A plan or rollout, for the CLI |
The same settings always make the same generation ID, so many devices can share one generation. Deploy numbers belong to one device: the same generation can be deploy #3 on one device and deploy #9 on another. Select a generation’s ID anywhere in the dashboard to open its page.
Without a message, the dashboard names a rollout after what it changes, such
as web · Suta OS 2026.09.1.
Plans and rollouts
Section titled “Plans and rollouts”You describe what a project’s devices should run in a file called
suta.yaml. Changing devices then takes two steps:
- A plan shows exactly which generation each device would get and what changes. Making a plan changes nothing on devices.
- A rollout applies exactly that plan, to a few devices first and then in batches. It pauses if devices fail.
This is the same idea as terraform plan and apply: you review a change,
then apply the change you reviewed.
Devices check every change
Section titled “Devices check every change”A device doesn’t simply do what it’s told. When it gets a new generation, it:
- Downloads and checks everything it needs, while the current generation keeps running.
- Switches over, restarting only the apps that changed.
- Watches the new generation for a probation period. Every app must stay healthy and the device must still reach Suta.
- Accepts the new generation, or, if anything failed, returns to the previous one on its own.
The device makes this decision itself, so a change that cuts it off from the network still gets rolled back. A power cut during an update leaves the device on the old generation or the new one, never in between. See Plan and roll out.
Raspberry Pi OS and Suta OS
Section titled “Raspberry Pi OS and Suta OS”Suta OS is a minimal operating system built for Suta. It keeps two copies of the OS on the card, so Suta can update the OS the same safe way it updates apps, and roll it back if the new version doesn’t start.
A new Pi you flash with suta flash runs Suta OS from its first boot. A Pi
that already runs Raspberry Pi OS can
install Suta alongside it: there, Suta deploys
your apps but leaves the OS alone. When you’re ready,
move that device to Suta OS without reflashing it.
Off until you turn it on
Section titled “Off until you turn it on”Features that reach into a device start switched off:
- Monitoring collects metrics and logs only after someone turns it on for that device. See Monitor devices.
- Remote access opens only for a time window you choose, such as one hour. Terminals and commands work only while it’s open. See Remote access.
Access is checked and recorded
Section titled “Access is checked and recorded”Every request is checked against a set of permissions:
- People get permissions from their role.
- AI agents get only the access you approve, and never more than the person who approved it. See Connect an AI agent.
- CI jobs use an API token that takes its permissions from a role.
Deploys, commands, service restarts and changes to the workspace are recorded in Activity, and terminal sessions are recorded in full.