Package Management

Overview

Kloudlite uses Nix package manager to provide reproducible, declarative package management for your workspaces. Packages are installed at the workmachine (host) level and made available in each workspace's PATH based on its configuration.

Host-Level Installation

Packages are installed once at the workmachine host and shared across workspaces, saving disk space and installation time.

Per-Workspace Configuration

Each workspace has its own package configuration. Only the packages specified for a workspace are available in its PATH.

All packages come from the Nix package repository via the Devbox registry, providing access to thousands of packages with reproducible builds and version pinning.

How It Works

Add Package to Workspace

When you add a package using kl pkg add, it's added to your workspace's package configuration.

Host-Level Installation

Nix installs the package at the workmachine host level. If another workspace uses the same package, it references the same installation.

Available in Workspace PATH

The package binary becomes available in your workspace's PATH. You can immediately use it from the terminal or in your code.

Persistent Across Restarts

Packages persist at the host level. When you restart a workspace, all configured packages are immediately available without reinstallation.

Searching for Packages

Use the kl pkg search command to search the Devbox package registry for available packages.

Search Command

Search for packages by name or keyword:

kl pkg search nodejs

kl pkg search python

kl p s postgresql      # Using aliases

Output shows:

Package name
Available versions

Devbox Package Registry

Search queries the Devbox package registry, which provides curated access to Nix packages with simplified versioning.

Adding Packages

There are multiple ways to add packages to your workspace, depending on your needs for version control and interactive selection.

Interactive Mode (Recommended)

Run without arguments to search, select packages, and choose specific versions interactively using fuzzy-find:

kl pkg add

This lets you search for packages, view available versions, and select the exact version you want to install.

Quick Add (Latest Version)

Provide package names directly to install the latest version of each:

kl pkg add git vim curl

kl pkg add nodejs python

kl p a jq           # Using aliases

Install Specific Version

Use kl pkg install to specify exact versions, channels, or commits:

Available Options:

--version - Semantic version (e.g., 20.0.0)
--channel - Nixpkgs channel (e.g., nixos-24.05, unstable)
--commit - Exact nixpkgs commit hash

kl pkg install nodejs --version 20.0.0

kl pkg install python --version 3.11.0

kl pkg install vim --channel nixos-24.05

kl p i go --channel unstable

Installation Timeout

Package installation may take a few minutes depending on the package size. The CLI waits up to 5 minutes for installation to complete.

Managing Packages

List Installed Packages

View all packages configured for your workspace and their installation status:

kl pkg list

kl p ls        # Using aliases

Output includes:

Workspace spec packages with channel/commit information
Installed packages with version and binary path
Failed packages with error messages (if any)

Uninstall Packages

Remove packages from your workspace configuration:

kl pkg uninstall nodejs

kl pkg remove python

kl p rm vim              # Using aliases

Removing a package only removes it from your workspace's configuration. The package remains at the host level for other workspaces that may use it.

Troubleshooting

Package installation is declarative, but environment drift can still happen. Use these checks to diagnose issues quickly when binaries are missing or install commands fail.

Validate Current State

kl pkg list                 # Compare desired vs installed

which node                  # Confirm binary availability

nix-store --verify-path /nix/store/...-nodejs

If a binary path is missing, reinstall with kl pkg install or remove it from the spec and re-run kl pkg add.

Common Error Scenarios

Install timeout: Re-run the command; large packages may need up to five minutes to build the first time.
Unknown package: Use kl pkg search to confirm the name and available versions.
Version conflicts: Pin an explicit channel or commit so every workspace resolves the same derivation.

Team Workflows

Package configuration lives alongside workspace specs, so you can standardize toolchains across the organisation. Adopt a workflow that keeps dev machines reproducible and fast.

Version-Control Package Specs

Keep workspace manifests in Git so changes to packages go through review.
Use feature branches to experiment with new toolchains before merging to main.
Track a CHANGELOG entry whenever you upgrade or remove a shared package.

Share Curated Bundles

Create installation-level machine presets with pre-approved package sets.
Document when to use heavier bundles (e.g., data-science vs. backend).
Leverage the shared host cache by aligning on the same versions across teams.

Best Practices

Pin Versions for Reproducibility

Use kl pkg install with --version or --commit to ensure consistent package versions across team members and environments.

Keep Package List Minimal

Only install packages you actively need. This keeps your workspace configuration clean and reduces startup time.

Use Interactive Mode for Discovery

Use kl pkg add without arguments to explore available versions and make informed decisions about which version to install.

Leverage Host-Level Caching

Common packages are shared across workspaces at the host level. Using the same package versions across workspaces maximizes this efficiency.

Search Before Installing

Use kl pkg search to verify package names and check available versions before installation.

Reproducible Development Environment

By using Nix package manager, your workspace environment is fully reproducible. Package installations are deterministic and can be shared with your team through workspace configuration.