# Guix Tribes Channel

This repository is the Guix channel for Tribes OS. It contains the package,
service, system, installer, deployment, and substitute-builder definitions used
to build and operate Tribes nodes.

## Contents

Network-bound disk encryption (NBDE):

- `nbde/packages/crypto.scm`: package definitions for `luksmeta`, `tang`, and
  `clevis`.
- `nbde/services/tang.scm`: standalone Tang service for Guix systems.
- `nbde/system/mapped-devices.scm`: Clevis-backed mapped-device kind with manual
  `cryptsetup` fallback.
- `nbde/system/initrd.scm`: early-boot Clevis support around `raw-initrd`.
- `docs/nbde.md`: operational notes for LUKS headers, initrd, Tang, and
  `/boot/nbde/local-boot.key`.

Tribes packages and systems:

- `tribes/packages/devtools.scm` and `tribes/packages/node.scm`: shared tooling
  package definitions used by repo-local Guix development manifests.
- `tribes/packages/source.scm`: source-built Tribes package producing a
  production release from pinned source plus vendored Mix/npm dependency FODs.
- `tribes/plugins/*.scm`: external plugin package definitions and plugin
  metadata.
- `tribes/services/*.scm`: Shepherd services for Tribes and supporting runtime
  components.
- `tribes/system/node.scm`: node operating-system constructor.
- `tribes/system/installer.scm`: installer-facing Tribes OS constructor.
- `manifests/substitutes/*.scm` and `tribes/ci/substitutes.scm`: substitute
  builder manifests and CI targets.

Deployment and diagnostics:

- `tribes/deploy/*.scm`: deployment helper API and worker/operation support used
  by Legion.
- `tribes/diagnostics/*.scm`: diagnostics helpers, including system generation
  comparison.
- `scripts/build-kexec-image`: builds the Legion kexec installer image.
- `scripts/build-tribes-docker-image`: builds the pinned Tribes debug Docker
  image.

## Pin maintenance

Refresh the upstream Guix channel pin intentionally with:

```sh
./scripts/update-base-channels-pin
```

The script updates `pins/base-channels.sexp` and syncs the Guix entry in
`pins/legion-channels.sexp`. It auto-detects whether the current pin uses the
local `guix-fork` channel or the mirrored official Guix channel, uses the
matching sibling checkout head by default (`../guix-fork` or `../guix`), accepts
`--commit COMMIT`, and can switch back to the mirrored official channel with
`--official`.

After changing the base channel pin, run Legion's generator in `../legion_kk`:

```sh
npm run generate:guix-base-channel
```

Refresh the Tribes and external plugin source pins with:

```sh
./scripts/update-tribes-and-plugin-pins
```

By default, the pin update scripts use local `guix` for hashing and fixed-output
builds. If the local host is not suitable for Guix networked fixed-output builds,
run them explicitly on an SSH build host:

```sh
./scripts/update-tribes-and-plugin-pins --build-host HOST
```

Use `--commit` to commit the affected pin files after a successful refresh:

```sh
./scripts/update-tribes-and-plugin-pins --commit
```

The combined script updates:

- `tribes/packages/source.scm`
- `tribes/plugins/sender.scm`
- `tribes/plugins/aether.scm`
- `tribes/plugins/supertest.scm`
- `tribes/plugins/kobold.scm`
- `tribes/plugins/trust.scm`

For one-off updates, use `scripts/update-tribes-pin` or
`scripts/update-plugin-pin --help` directly.

## Channel files

Checked-in channel files serve different roles:

- `pins/base-channels.sexp`: upstream Guix pin only; used for `guix pull -C` and
  related bootstrap tooling.
- `pins/legion-channels.sexp`: Legion/build-host default channel set containing
  the pinned upstream Guix channel plus default `tribes` channel metadata.
- The `kexec-installer` branch selects the default kexec installer source commit.

For pinned bootstrap usage, generate a `channels.scm` that combines the pinned
upstream Guix channel with this repository's current commit.

## Current development status

- NBDE packages and the disposable Tang + LUKS smoke path are working.
- The QEMU Phase-0 encrypted-root system boots unattended through Clevis/Tang and
  reaches a login prompt.
- The active Legion kexec image definition is based on
  `examples/build-host-kexec-installer.scm` and
  `nbde/system/build-host-kexec-installer.scm`.
- Tribes source, plugin, node, installer, Docker debug image, and substitute
  manifest definitions are maintained in this channel.