> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Single-Host Release Artifacts

> Manifest, artifact, compatibility, install, and upgrade contract for the OSS single-host appliance.

The `single_host_oss` appliance installs from a release manifest instead of
building runtime components from a source checkout. The manifest binds the API
binary, console bundle, guest agent, rootfs images, kernel, Firecracker,
jailer, migration bundle, and `nullspace-host` operator tool to checksums,
sizes, install paths, rollback metadata, and compatibility facts.

## Manifest

The checked-in schema and examples live in the repository:

```text theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
infra/deploy/schemas/single-host-release-manifest.schema.json
infra/deploy/single-host-release-manifest.dev.example.json
infra/deploy/single-host-release-manifest.release.example.json
```

Required component kinds:

* `api`
* `console`
* `guest_agent`
* `rootfs`
* `template`
* `kernel`
* `firecracker`
* `jailer`
* `migration_bundle`
* `operator_tool`

Every component records URL, SHA256, size, architecture, version,
compatibility class, release-local install path, optional active compatibility
path, required/optional status, and rollback metadata.

The manifest also records runtime compatibility facts for Firecracker
version/commit, Firecracker snapshot data format, kernel identity, rootfs and
template digests, guest-agent protocol version, runtime class, and snapshot
metadata format.

## Build A Local Manifest

Prepare a release directory with the expected artifact filenames, then generate
a manifest:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
python3 tools/ops/build_single_host_release_manifest.py \
  --artifact-dir /mnt/nullspace-release \
  --output /mnt/nullspace-release/manifest.json \
  --release-id 2026.06.10 \
  --version 0.1.0 \
  --arch "$(uname -m)" \
  --source-revision "$(git rev-parse HEAD)" \
  --firecracker-version v1.12.1 \
  --firecracker-commit reviewed-firecracker-build \
  --snapshot-data-format firecracker-v1.12 \
  --kernel-identity linux-6.1-nullspace
```

When `--base-url` is omitted, the manifest uses `file://` URLs suitable for
offline media. Pass `--base-url https://...` when publishing artifacts to an
HTTP release bucket.

## Install Or Fetch

Install the appliance from a manifest:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sudo nullspace-host install --manifest /mnt/nullspace-release/manifest.json
```

Fetch artifacts without re-rendering the rest of the appliance:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sudo nullspace-host artifacts fetch --manifest /mnt/nullspace-release/manifest.json
```

Artifacts install under `/opt/nullspace/releases/<release-id>/`; the active
release symlink at `/opt/nullspace/releases/current` is switched atomically.
Compatibility symlinks such as `/opt/nullspace/nullspace-api` and
`/opt/nullspace/artifacts/rootfs.ext4` point at the active release.

Validate active artifact state:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sudo nullspace-host doctor --json
```

`doctor` reports the active manifest id, manifest digest, installed component
versions, component checksums, verification evidence, and compatibility facts.

## Upgrade And Rollback

Validate a future release without switching:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sudo nullspace-host upgrade \
  --manifest /mnt/nullspace-release-next/manifest.json \
  --dry-run
```

Apply an upgrade:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sudo nullspace-host upgrade \
  --manifest /mnt/nullspace-release-next/manifest.json
```

The upgrade path validates the manifest, checks host and release
compatibility, fetches verified artifacts, switches the active release, and
runs the ingress fixture smoke unless `--skip-ingress-smoke` is set.

Rollback switches the active release back to the previous release recorded in
the upgrade state:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sudo nullspace-host rollback --json
```

Database migrations are not automatically rolled back. Use a verified
appliance backup when a migration must be reversed.

## Launch Evidence

Release artifacts alone do not prove a public launch. Before making public
claims for a release, run the launch gate on a supported Ubuntu x86\_64 KVM
host:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
sudo nullspace-host launch-gate \
  --mode localhost \
  --manifest /mnt/nullspace-release/manifest.json \
  --console-url http://localhost/console/ \
  --confirm "run nullspace launch gate" \
  --evidence-dir /var/lib/nullspace/evidence/launch-gate
```

Use `--mode owned-domain --public-hostname <domain>` for the signed
owned-domain preview path.

## Related

* [Self-Hosted Single-Host](../quickstarts/self-hosted-single-host)
* [Environment Variables](./env-vars)
* [Preview URLs](../networking/preview-urls)