# reported.json (/docs/reference/reported)



The file the host writes to `reported.json` in `paths.state_dir` after every reconcile pass. The
metrics page is built from the same data. A control plane that reads only this file learns the
result of its last write to `desired.json`, and the reason for any failure.

Schema: [reported.schema.json](https://raw.githubusercontent.com/ilbertt/nibrunner/main/crates/protocol/schema/reported.schema.json)

## HostReportedState [#hostreportedstate]

What one host is running, as the daemon last wrote it to `reported.json` in its `paths.state_dir`.

| Name                                                                                                        | Type                                               | Description                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="hostreportedstate-hostId" className="scroll-mt-28">`hostId`</span>                                | [HostId](#hostid)                                  |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-reportedAt" className="scroll-mt-28">`reportedAt`</span>                        | [Timestamp](#timestamp)                            |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-state" className="scroll-mt-28">`state`</span>                                  | [HostState](#hoststate)                            |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-capacity" className="scroll-mt-28">`capacity`</span>                            | [HostCapacity](#hostcapacity)                      | What the machine has.                                                                                                                                                                                                                                                                                                                                      |
| <span id="hostreportedstate-allocatable" className="scroll-mt-28">`allocatable`</span>                      | [HostCapacity](#hostcapacity)                      | What is left once every booted app is taken off.                                                                                                                                                                                                                                                                                                           |
| <span id="hostreportedstate-versions" className="scroll-mt-28">`versions`</span>                            | [HostVersions](#hostversions)                      |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-cron" className="scroll-mt-28">`cron`</span>                                    | array of [CronListing](#cronlisting) \| null       |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-volumes" className="scroll-mt-28">`volumes`</span>                              | array of [ReportedVolume](#reportedvolume)         |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-instances" className="scroll-mt-28">`instances`</span>                          | array of [ReportedInstance](#reportedinstance)     |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-checkpoints" className="scroll-mt-28">`checkpoints`</span>                      | array of [ReportedCheckpoint](#reportedcheckpoint) |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-exports" className="scroll-mt-28">`exports`</span>                              | array of [ReportedExport](#reportedexport)         |                                                                                                                                                                                                                                                                                                                                                            |
| <span id="hostreportedstate-acceptedDigest" className="scroll-mt-28">`acceptedDigest`</span> *optional*     | [Sha256Digest](#sha256digest) \| null              | The document this host is converging on, as `sha256sum` reads the file it came from. Absent until one has been taken up. A control plane checks it against the write it made to learn that this host is on that document rather than on the one before it — which is what `instances` alone cannot say about a document that changed nothing about an app. |
| <span id="hostreportedstate-acceptedRevision" className="scroll-mt-28">`acceptedRevision`</span> *optional* | [Revision](#revision) \| null                      | The `revision` that document named, if it named one — the control plane's own word for what this host is converging on, beside the digest that is this host's.                                                                                                                                                                                             |
| <span id="hostreportedstate-message" className="scroll-mt-28">`message`</span> *optional*                   | [StateMessage](#statemessage) \| null              | Set when the last document this host was handed was refused — malformed, or not the document this host reads — and cleared when a readable one is taken up. A control plane that only reads this file learns from it that its last write did not land, and why.                                                                                            |

## HostId [#hostid]

an identifier

string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$`

## Timestamp [#timestamp]

an ISO 8601 instant with an offset

string, matching `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$`

## HostState [#hoststate]

One of `"registering"`, `"ready"`, `"draining"`, `"unreachable"`.

## HostCapacity [#hostcapacity]

| Name                                                                            | Type                | Description |
| ------------------------------------------------------------------------------- | ------------------- | ----------- |
| <span id="hostcapacity-vcpuCount" className="scroll-mt-28">`vcpuCount`</span>   | integer, at least 0 |             |
| <span id="hostcapacity-memoryMib" className="scroll-mt-28">`memoryMib`</span>   | integer, at least 0 |             |
| <span id="hostcapacity-cacheBytes" className="scroll-mt-28">`cacheBytes`</span> | integer, at least 0 |             |

## HostVersions [#hostversions]

| Name                                                                              | Type   | Description |
| --------------------------------------------------------------------------------- | ------ | ----------- |
| <span id="hostversions-agent" className="scroll-mt-28">`agent`</span>             | string |             |
| <span id="hostversions-guestImage" className="scroll-mt-28">`guestImage`</span>   | string |             |
| <span id="hostversions-zerofs" className="scroll-mt-28">`zerofs`</span>           | string |             |
| <span id="hostversions-firecracker" className="scroll-mt-28">`firecracker`</span> | string |             |

## CronListing [#cronlisting]

| Name                                                                               | Type                                             | Description |
| ---------------------------------------------------------------------------------- | ------------------------------------------------ | ----------- |
| <span id="cronlisting-appId" className="scroll-mt-28">`appId`</span>               | [AppId](#appid)                                  |             |
| <span id="cronlisting-deploymentId" className="scroll-mt-28">`deploymentId`</span> | [DeploymentId](#deploymentid)                    |             |
| <span id="cronlisting-enabled" className="scroll-mt-28">`enabled`</span>           | boolean                                          |             |
| <span id="cronlisting-timeZone" className="scroll-mt-28">`timeZone`</span>         | string                                           |             |
| <span id="cronlisting-jobs" className="scroll-mt-28">`jobs`</span>                 | array of [RegisteredCronJob](#registeredcronjob) |             |

## ReportedVolume [#reportedvolume]

| Name                                                                                               | Type                                        | Description |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------- |
| <span id="reportedvolume-volumeId" className="scroll-mt-28">`volumeId`</span>                      | [VolumeId](#volumeid)                       |             |
| <span id="reportedvolume-appId" className="scroll-mt-28">`appId`</span>                            | [AppId](#appid)                             |             |
| <span id="reportedvolume-state" className="scroll-mt-28">`state`</span>                            | [VolumeState](#volumestate)                 |             |
| <span id="reportedvolume-sizeBytes" className="scroll-mt-28">`sizeBytes`</span>                    | integer, at least 0                         |             |
| <span id="reportedvolume-usage" className="scroll-mt-28">`usage`</span>                            | [FilesystemUsage](#filesystemusage) \| null |             |
| <span id="reportedvolume-devicePath" className="scroll-mt-28">`devicePath`</span> *optional*       | string \| null                              |             |
| <span id="reportedvolume-message" className="scroll-mt-28">`message`</span> *optional*             | [StateMessage](#statemessage) \| null       |             |
| <span id="reportedvolume-storagePrefix" className="scroll-mt-28">`storagePrefix`</span> *optional* | [ObjectKey](#objectkey) \| null             |             |

## ReportedInstance [#reportedinstance]

| Name                                                                                               | Type                                        | Description                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="reportedinstance-appId" className="scroll-mt-28">`appId`</span>                          | [AppId](#appid)                             |                                                                                                                                                                                                                               |
| <span id="reportedinstance-deploymentId" className="scroll-mt-28">`deploymentId`</span>            | [DeploymentId](#deploymentid)               |                                                                                                                                                                                                                               |
| <span id="reportedinstance-state" className="scroll-mt-28">`state`</span>                          | [InstanceState](#instancestate)             |                                                                                                                                                                                                                               |
| <span id="reportedinstance-compute" className="scroll-mt-28">`compute`</span>                      | [ComputeUsage](#computeusage) \| null       |                                                                                                                                                                                                                               |
| <span id="reportedinstance-restartCount" className="scroll-mt-28">`restartCount`</span>            | integer, at least 0                         | Times the supervisor inside the guest has restarted the tenant since this host last booted the app afresh. A restore from a snapshot keeps the count; a cold boot starts it over.                                             |
| <span id="reportedinstance-convergedAt" className="scroll-mt-28">`convergedAt`</span> *optional*   | [Timestamp](#timestamp) \| null             | When the instance first became what the document asks of it, for the `deploymentId` and `desiredState` it now carries. Absent while it is still on its way there, and for a deployment this host was not there to see arrive. |
| <span id="reportedinstance-guestIpv4" className="scroll-mt-28">`guestIpv4`</span> *optional*       | [Ipv4Address](#ipv4address) \| null         |                                                                                                                                                                                                                               |
| <span id="reportedinstance-hostPort" className="scroll-mt-28">`hostPort`</span> *optional*         | [HostPort](#hostport) \| null               |                                                                                                                                                                                                                               |
| <span id="reportedinstance-lastExitCode" className="scroll-mt-28">`lastExitCode`</span> *optional* | integer \| null                             |                                                                                                                                                                                                                               |
| <span id="reportedinstance-lastRestart" className="scroll-mt-28">`lastRestart`</span> *optional*   | [ReportedRestart](#reportedrestart) \| null | The last of those restarts. Absent until there has been one.                                                                                                                                                                  |
| <span id="reportedinstance-layerDigests" className="scroll-mt-28">`layerDigests`</span> *optional* | array of [Sha256Digest](#sha256digest)      | The layers the running microVM was booted from, bottom first. Empty until one has been.                                                                                                                                       |
| <span id="reportedinstance-message" className="scroll-mt-28">`message`</span> *optional*           | [StateMessage](#statemessage) \| null       |                                                                                                                                                                                                                               |
| <span id="reportedinstance-startedAt" className="scroll-mt-28">`startedAt`</span> *optional*       | [Timestamp](#timestamp) \| null             |                                                                                                                                                                                                                               |

## ReportedCheckpoint [#reportedcheckpoint]

| Name                                                                                           | Type                                  | Description |
| ---------------------------------------------------------------------------------------------- | ------------------------------------- | ----------- |
| <span id="reportedcheckpoint-checkpointId" className="scroll-mt-28">`checkpointId`</span>      | [CheckpointId](#checkpointid)         |             |
| <span id="reportedcheckpoint-volumeId" className="scroll-mt-28">`volumeId`</span>              | [VolumeId](#volumeid)                 |             |
| <span id="reportedcheckpoint-state" className="scroll-mt-28">`state`</span>                    | [CheckpointState](#checkpointstate)   |             |
| <span id="reportedcheckpoint-message" className="scroll-mt-28">`message`</span> *optional*     | [StateMessage](#statemessage) \| null |             |
| <span id="reportedcheckpoint-readyAt" className="scroll-mt-28">`readyAt`</span> *optional*     | [Timestamp](#timestamp) \| null       |             |
| <span id="reportedcheckpoint-reference" className="scroll-mt-28">`reference`</span> *optional* | [StateMessage](#statemessage) \| null |             |

## ReportedExport [#reportedexport]

| Name                                                                                             | Type                                  | Description |
| ------------------------------------------------------------------------------------------------ | ------------------------------------- | ----------- |
| <span id="reportedexport-exportId" className="scroll-mt-28">`exportId`</span>                    | [ExportId](#exportid)                 |             |
| <span id="reportedexport-state" className="scroll-mt-28">`state`</span>                          | [ExportState](#exportstate)           |             |
| <span id="reportedexport-checkpointId" className="scroll-mt-28">`checkpointId`</span> *optional* | [CheckpointId](#checkpointid) \| null |             |
| <span id="reportedexport-message" className="scroll-mt-28">`message`</span> *optional*           | [StateMessage](#statemessage) \| null |             |
| <span id="reportedexport-readyAt" className="scroll-mt-28">`readyAt`</span> *optional*           | [Timestamp](#timestamp) \| null       |             |
| <span id="reportedexport-sizeBytes" className="scroll-mt-28">`sizeBytes`</span> *optional*       | integer, at least 0 \| null           |             |

## Sha256Digest [#sha256digest]

a lowercase hex sha-256

string, matching `^[0-9a-f]{64}$`

## Revision [#revision]

between 1 and 128 printable characters, without spaces

string, matching `^[\x21-\x7e]{1,128}$`

## StateMessage [#statemessage]

string, at most 512 characters

## AppId [#appid]

an identifier

string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$`

## DeploymentId [#deploymentid]

an identifier

string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$`

## RegisteredCronJob [#registeredcronjob]

| Name                                                                                              | Type                                            | Description |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------- |
| <span id="registeredcronjob-jobId" className="scroll-mt-28">`jobId`</span>                        | string                                          |             |
| <span id="registeredcronjob-schedule" className="scroll-mt-28">`schedule`</span>                  | [CronSchedule](#cronschedule)                   |             |
| <span id="registeredcronjob-command" className="scroll-mt-28">`command`</span>                    | [CronCommand](#croncommand)                     |             |
| <span id="registeredcronjob-nextRunAt" className="scroll-mt-28">`nextRunAt`</span>                | [Timestamp](#timestamp) \| null                 |             |
| <span id="registeredcronjob-environment" className="scroll-mt-28">`environment`</span> *optional* | [TenantEnvironment](#tenantenvironment) \| null |             |

## VolumeId [#volumeid]

an identifier

string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$`

## VolumeState [#volumestate]

One of `"pending"`, `"ready"`, `"detached"`, `"deleted"`, `"failed"`.

## FilesystemUsage [#filesystemusage]

| Name                                                                               | Type                    | Description |
| ---------------------------------------------------------------------------------- | ----------------------- | ----------- |
| <span id="filesystemusage-totalBytes" className="scroll-mt-28">`totalBytes`</span> | integer, at least 0     |             |
| <span id="filesystemusage-usedBytes" className="scroll-mt-28">`usedBytes`</span>   | integer, at least 0     |             |
| <span id="filesystemusage-measuredAt" className="scroll-mt-28">`measuredAt`</span> | [Timestamp](#timestamp) |             |

## ObjectKey [#objectkey]

between 1 and 1024 characters

string, 1 to 1024 characters

## InstanceState [#instancestate]

One of `"pending"`, `"starting"`, `"running"`, `"unhealthy"`, `"stopping"`, `"stopped"`, `"idle"`, `"failed"`.

## ComputeUsage [#computeusage]

| Name                                                                                        | Type                    | Description |
| ------------------------------------------------------------------------------------------- | ----------------------- | ----------- |
| <span id="computeusage-memoryTotalBytes" className="scroll-mt-28">`memoryTotalBytes`</span> | integer, at least 0     |             |
| <span id="computeusage-memoryUsedBytes" className="scroll-mt-28">`memoryUsedBytes`</span>   | integer, at least 0     |             |
| <span id="computeusage-measuredAt" className="scroll-mt-28">`measuredAt`</span>             | [Timestamp](#timestamp) |             |
| <span id="computeusage-cpuShare" className="scroll-mt-28">`cpuShare`</span> *optional*      | number \| null          |             |

## Ipv4Address [#ipv4address]

an IPv4 address

string, matching `^((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9])$`

## HostPort [#hostport]

integer, 1 to 65535

## ReportedRestart [#reportedrestart]

A tenant restart as the host heard of it: what the guest said, and when it said it.

| Name                                                                             | Type                          | Description                                                                                                  |
| -------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| <span id="reportedrestart-at" className="scroll-mt-28">`at`</span>               | [Timestamp](#timestamp)       |                                                                                                              |
| <span id="reportedrestart-attempt" className="scroll-mt-28">`attempt`</span>     | integer, at least 0           | 1 for the first restart since the tenant last stayed up long enough to earn its budget back, up to `budget`. |
| <span id="reportedrestart-budget" className="scroll-mt-28">`budget`</span>       | integer, at least 0           |                                                                                                              |
| <span id="reportedrestart-exit" className="scroll-mt-28">`exit`</span>           | [TenantExit](#tenantexit)     |                                                                                                              |
| <span id="reportedrestart-reason" className="scroll-mt-28">`reason`</span>       | [StateMessage](#statemessage) |                                                                                                              |
| <span id="reportedrestart-backoffMs" className="scroll-mt-28">`backoffMs`</span> | integer, at least 0           |                                                                                                              |

## CheckpointId [#checkpointid]

an identifier

string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$`

## CheckpointState [#checkpointstate]

One of `"pending"`, `"ready"`, `"deleted"`, `"failed"`.

## ExportId [#exportid]

an identifier

string, matching `^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$`

## ExportState [#exportstate]

One of `"pending"`, `"preparing"`, `"ready"`, `"failed"`, `"expired"`.

## CronSchedule [#cronschedule]

string

## CronCommand [#croncommand]

string, at most 32768 characters

## TenantEnvironment [#tenantenvironment]

map of [TenantValue](#tenantvalue), keys matching `^[A-Za-z_][A-Za-z0-9_]*$`

## TenantExit [#tenantexit]

How a tenant process ended: the code it exited with, or the signal that killed it.

One of the following:

### code [#code]

| Name                                                        | Type    | Description |
| ----------------------------------------------------------- | ------- | ----------- |
| <span id="code-code" className="scroll-mt-28">`code`</span> | integer |             |

### signal [#signal]

| Name                                                              | Type    | Description |
| ----------------------------------------------------------------- | ------- | ----------- |
| <span id="signal-signal" className="scroll-mt-28">`signal`</span> | integer |             |

## TenantValue [#tenantvalue]

Only complete `${NAME}` references are filled in for NAME in NIBRUN\_HOSTNAME, NIBRUN\_HTTP\_PORT. Bare names, incomplete references and other dollar signs remain literal; complete references to unknown `NIBRUN_` names are refused.

string, at most 32768 characters
