Channel Management

Channels are how Grove controls which versions of packages you get. Think of them as different “streams” of the package repository - some have the latest and greatest, others focus on stability.

What are channels?

Channels are basically different versions or branches of the nixpkgs package repository. Each channel represents a snapshot of the repository at a particular point in time, with different stability guarantees:

• unstable: The latest packages with all the newest features (this is the default).
• stable: Well-tested packages that change less often.
• custom: Your own channel definitions for specific needs.

How channels work

When Grove needs to find a package, here’s what happens:

1. Grove looks at your devenv.yaml file to see which channels are configured.
2. Grove searches the specified channel for the package you requested.
3. Grove finds the version of the package available in that channel.
4. Grove downloads that specific version and all its dependencies.

Channel hierarchy

Grove uses a priority system for channels:

1. Explicit channel: If you specify --channel stable, Grove uses that channel.
2. Default channel: If no channel is specified, Grove uses the default (usually unstable).
3. Fallback: If a package isn’t found, Grove may search other configured channels.

Channel configuration

Channels are configured in your devenv.yaml file:

inputs:
  nixpkgs:
    url: github:NixOS/nixpkgs/nixpkgs-unstable
  nixpkgs-stable:
    url: github:NixOS/nixpkgs/nixos-23.11
  my-custom-channel:
    url: github:myorg/my-nixpkgs/main

Channel updates

When you run kanuka grove channel update, Grove:

1. Fetches the latest commit hash for each channel.
2. Updates the channel references in your configuration.
3. Downloads any new package definitions.
4. The next time you enter your environment, you get the updated packages.

Channel pinning

You can pin a channel to a specific commit to ensure reproducibility:

kanuka grove channel pin nixpkgs-stable abc123def456

This locks the channel to that exact commit, so everyone on your team gets the same package versions.

Why channels matter

Channels give you control over the trade-off between stability and freshness:

Unstable channel

• Pros: Latest features, newest packages, frequent updates.
• Cons: Occasional breaking changes, less tested.
• Best for: Development, experimentation, staying current.

Stable channel

• Pros: Well-tested, predictable, fewer breaking changes.
• Cons: Older package versions, slower updates.
• Best for: Production environments, critical projects.

Custom channels

• Pros: Complete control, specific package versions, organizational standards.
• Cons: Maintenance overhead, need to manage updates yourself.
• Best for: Enterprise environments, specific compliance requirements.

Channel mixing

You can use different channels for different packages in the same environment:

kanuka grove add nodejs --channel unstable    # Latest Node.js
kanuka grove add python3 --channel stable     # Stable Python
kanuka grove add my-tool --channel custom     # Custom package

This gives you fine-grained control over which packages get which level of stability.

Channel caching

Grove leverages Nix’s binary cache system:

• Fast downloads: Pre-built packages are cached and ready to download.
• Reproducible builds: Same inputs always produce the same outputs.
• Efficient storage: Packages are deduplicated across environments.
• Offline capability: Once downloaded, packages work offline.

Continue reading to learn about how Grove builds containers from your environment.