SynapseOS
Applies to SynapseOS builds from 2026-10-09 (20261009-141152 and later). See What changed.
The operating system your appliance arrived with.
SynapseOS is the Linux that runs on a Gen0Sec appliance, whether that is a Cerebrum Max, a Cerebrum Edge, a server or virtual machine of your own, or an NVIDIA BlueField-3 card. It exists to run Synapse and nothing else. Your unit arrives with it installed and signed; these pages start at the login prompt.
How it differs from a general-purpose Linux
| On SynapseOS | |
|---|---|
The system itself (/usr) | Read-only, and checked block by block on every boot. An edit there does not persist and makes the next boot fail verification |
Your configuration (/etc, /var, /root) | Writable, and kept across updates |
| Updates | One signed update replaces the whole system and its kernel together. The previous system stays on disk, and the appliance returns to it by itself if the new one does not come up |
| Software | There is no package manager. What is on the unit is what the image was built with; new software arrives through an update |
| Network exposure | Inbound traffic is dropped by default, except SSH |
| Access | SSH accepts root with a key only. A password, where one is set, works on the console only |
The read-only system is the reason the rest holds: the kernel, Synapse and every library are verified against a hash that is sealed into the signed kernel image, so a changed file cannot be run, and an update either verifies completely or is not booted.
What you see after logging in
The login banner names the build the unit was delivered with (the running one, after an
update, is in synapseos-ab-update status):
SynapseOS 20261009-141152-1bf85f2 (hardened ab) | kernel 6.18.54-synapseos
A/B slots | /usr sealed with dm-verity
and lists the three commands you will use most:
| Command | What it does |
|---|---|
synapseos-synapse list | The Synapse versions on the unit, and which one runs |
synapseos-ab-update | Check for, install and roll back OS updates |
systemctl status synapse-agent synapseos-firewall | The data plane and the base firewall |
Where to go next
- Logging in: credentials, keys and the console.
- Configuring the appliance: network, firewall, Synapse and logs.
- Network requirements: what the unit accepts inbound and reaches outbound, proxies, a private CA.
- Updating: checking for an update, installing one, and going back.
- Synapse versions: choosing which of the shipped releases runs.
- Running the proxy: enabling Synapse's proxy mode beside the agent.
- High availability: operating two units as a pair with one floating address.
- Platforms: what differs on a Cerebrum Max, a Cerebrum Edge, a server, a VM or a BlueField-3.
- Serial console: connecting a laptop to a Cerebrum Edge's console port.
- Backup, restore and decommission: what to keep, how to put it on a replacement, how to wipe a unit.
- Troubleshooting: the messages you may see, what they mean, and what to collect for support.
- Configuration reference: every file you may change, and three reference configurations.
- Security model: what is verified, what cannot be changed, how to report a vulnerability.
- Known limitations: what the unit does not do yet, and what to do instead.
- What changed: dated changes to these pages and the builds they were checked against.
The banner carries the usual warning about the CLI. Everything on these pages is a supported way to operate the appliance. What is not supported is changing the system itself, and the unit refuses that on its own.