Pantavisor State Format (state.json)¶
A Pantavisor revision is defined by a single JSON object called state.json. It acts as a virtual filesystem manifest where every key represents a relative file path within the revision, and every value is either a nested configuration object or a SHA256 identifier for a binary artifact.
1. Root Level (state.json)¶
These keys represent the files at the root of a revision.
| Key | Value Type | Mandatory | Description |
|---|---|---|---|
#spec |
string | Yes | Parser version. Must be "pantavisor-service-system@1". |
README.md |
string | No | Documentation for the revision in Markdown format. |
bsp/run.json |
BSP Manifest | Yes | Board Support Package configuration. |
bsp/drivers.json |
Drivers Manifest | No | Abstract driver mapping for the kernel. |
device.json |
Infrastructure Manifest | No | Unified physical storage and logical group definition. |
groups.json |
Groups Manifest | No | (Legacy) Logical container orchestration groups. |
disks.json |
Disks Manifest | No | (Legacy) Physical storage medium definitions. |
<container>/run.json |
Container Manifest | Yes | Individual container configuration. |
<container>/services.json |
Service Exports | No | Services exported to the xconnect mesh. |
_sigs/<container>.json |
Signature Manifest | No | Security signature for container artifacts. |
_config/<container>/<path> |
string | No | Injects data into <path> inside the container's rootfs. |
<any/other/path> |
string | No | SHA256 identifier for a binary artifact at that path. |
2. BSP (bsp/run.json)¶
Defines the core system boot assets.
| Key | Value Type | Description |
|---|---|---|
linux |
path string | Path to the Linux kernel image. |
initrd |
path string | Path to the Pantavisor initrd binary. |
modules |
path string | Path to the modules squashfs image. |
firmware |
path string | Path to the firmware squashfs image. |
fdt |
path string | Path to the Flattened Device Tree binary. |
fit |
path string | Path to a FIT image (replaces linux/initrd/fdt). |
rpiab |
path string | Path to a Raspberry Pi boot image. |
addons |
array of paths | List of CPIO addons to merge into the initrd rootfs. |
initrd_config |
path string | Custom configuration for the initrd process. |
3. Drivers (bsp/drivers.json)¶
Maps abstract driver names to kernel modules based on hardware.
| Key | Value Type | Description |
|---|---|---|
#spec |
string | Must be "driver-aliases@1". |
all |
object | Default module mappings for all hardware. |
dtb:<name> |
object | Module mappings specific to a Device Tree model. |
ovl:<name> |
object | Module mappings specific to a DT Overlay. |
Example module list:
"wifi": [ "cfg80211", "brcmfmac ${user-meta:wifi.opts}" ]
4. Infrastructure (device.json)¶
The unified hardware and orchestration manifest.
| Key | Value Type | Description |
|---|---|---|
disks |
array | List of Disk Definitions. Strict parsing — unknown types are fatal. |
disks_v2 |
array | Same schema as disks, additive. Parsed independently. |
disks_v3 |
array | Same schema as disks with lenient parsing (unknown types are warned and skipped). Required for the dual type — old firmware safely ignores this key. |
groups |
array | List of Orchestration Groups. |
volumes |
object | List of Persistent Volumes for Pantavisor itself. |
5. Orchestration (groups.json)¶
Defines how containers are grouped and started.
| Key | Value Type | Default | Description |
|---|---|---|---|
name |
string | Mandatory | Unique logical name for the group. |
description |
string | empty | Human-readable description. |
status_goal |
enum | STARTED |
Goal for all members: MOUNTED, STARTED, READY. |
restart_policy |
enum | container |
Policy on failure: system, container. |
timeout |
integer | 30 | Seconds to wait for members to reach status_goal. |
auto_recovery |
object | none | Default auto-recovery for containers in this group. Inherited all-or-nothing by containers without their own auto_recovery. |
6. Storage (disks.json)¶
Defines physical storage mediums. Each entry in the disks, disks_v2,
or disks_v3 array uses this schema. See the
Disks overview for type-specific details and
examples.
| Key | Value Type | Default | Description |
|---|---|---|---|
name |
string | Mandatory | Unique name used in run.json storage keys and mount paths. |
type |
enum | Mandatory | dm-crypt-caam, dm-crypt-dcp, dm-crypt-versatile, swap-disk, volume-disk, dual, directory. |
path |
string | Mandatory (crypt, swap, vol) | Device/image path. CAAM v2: -v2 <img>,<size>,<key>. DCP/versatile: <img>,<size>,<key>. |
mode |
enum | Mandatory (crypt) | mainline or nxp. Selects key subsystem. |
format |
enum | ext4 |
Filesystem format: ext4, ext3, or swap. |
provision |
string | empty | Backend provisioning: zram, file, or a custom value. Required for swap and volume types. |
provision_ops |
string | empty | Backend-specific options (e.g. disksize=128M comp_algorithm=lz4). |
mount_target |
path | empty | Where to mount the disk on the host. Required for volume-disk. |
mount_options |
string | empty | Comma-separated mount flags (e.g. MS_NOATIME,MS_NOSUID). |
format_options |
string | empty | Arguments for the mkfs or mkswap command. |
default |
string | "no" |
If "yes", this disk is used for all volumes without a disk key. |
uuid |
string | empty | Disk UUID. |
disks |
array | Mandatory (dual) | Sub-disk names: ["primary-name", "secondary-name"]. |
init_order |
array | Mandatory (dual) | Actions tried in sequence: primary, secondary, create-primary, create-secondary, copy-once-to-primary. |
7. Container (<container>/run.json)¶
Configures an individual container runtime.
| Key | Value Type | Mandatory | Description |
|---|---|---|---|
#spec |
string | Yes | Must be "service-manifest-run@1". |
name |
string | Yes | Logical name of the container. |
type |
enum | Yes | Runtime type (currently only lxc). |
config |
path string | Yes | Path to the LXC configuration file. |
root-volume |
path string | Yes | Path to the rootfs squashfs artifact. |
volumes |
array | No | Additional artifacts to mount as volumes. |
group |
string | No | Orchestration group name (from device.json). |
status_goal |
enum | No | Target state: MOUNTED, STARTED, READY. |
restart_policy |
enum | No | system (reboot on crash) or container (restart LXC). |
roles |
array | No | Capability roles: mgmt (control API access) or nobody. |
storage |
object | Yes | Persistence settings for rootfs paths. |
drivers |
object | No | Requirements: required, optional, or manual. |
services |
object | No | Service mesh requirements. |
logs |
array | No | Logger configurations. |
exports |
array | No | (Boolean flag in code) Marks container as an exporter. |
auto_recovery |
object | No | Auto-recovery configuration. If absent, inherited from group. |
Auto-Recovery Object¶
Configures automatic restart behavior when a container crashes. See Auto-Recovery overview for the broader context.
| Key | Value Type | Default | Description |
|---|---|---|---|
policy |
enum | no |
Recovery policy: no, always, on-failure, unless-stopped. Note: the current implementation does not distinguish exit codes — on-failure behaves the same as always. |
max_retries |
integer | 0 | Maximum restart attempts. 0 = unlimited. |
retry_delay |
integer | 0 | Initial delay in seconds before first restart. |
backoff_factor |
number | 1.0 | Multiplier applied to retry_delay on each subsequent retry. |
reset_window |
integer | 0 | Seconds of continuous uptime after which the retry counter resets to 0. |
stable_timeout |
integer | 0 | Seconds the container must survive after reaching its status goal to be considered stable. Used to gate TESTING commit. |
backoff_policy |
string | reboot |
Action after max_retries exhausted in steady state: reboot, never, or a duration string (10min, 1h, 30s). |
Storage Object¶
Defines persistence for specific directories. Keys are paths relative to container root.
* persistence: permanent (survives updates), revision (survives reboots), boot (volatile).
* disk: Logical disk name from device.json.
Service Requirements¶
Under the services key in run.json.
* required / optional: Arrays of service requirement objects.
* name: Logical name of the service to find.
* type: Protocol (rest, dbus, unix, drm, wayland).
* target: Path where Pantavisor should inject the socket/resource.
* role: Masquerade as this role when connecting.
* interface: Protocol-specific identifier.
8. Service mesh (<container>/services.json)¶
Declares services this container provides to others.
| Key | Value Type | Description |
|---|---|---|
#spec |
string | Must be "service-manifest-xconnect@1". |
services |
array | List of service objects (name, type, socket). |
9. Security (_sigs/<container>.json)¶
JWS-based artifact verification.
| Key | Value | Description |
|---|---|---|
#spec |
"pvs@2" |
Parser version. |
protected |
base64 string | Encoded headers including alg, typ, and pvs path filters. |
signature |
base64 string | The cryptographic signature of the protected header and payload. |
x5c |
array | (In protected) Certificate chain for verification. |
jwk |
object | (In protected) JSON Web Key for verification. |