Codchi
Docs
Docs

Installation

Windows 10 & 11

Prerequisites

On Windows, Codchi uses the Windows Subsystem for Linux, which is available for free from Microsoft.

WARNING

Installing WSL enables Microsoft's Hyper-V Hypervisor, which might cause issues with older virtualisation technologies like VMware. Don't worry, you can disable or re-enable Hyper-Vat any time.

Make sure that WSL2 is installed and up to date. In a terminal, wsl.exe --version should output something like the following, where WSL-Version should be 2.0.14 or greater:

WSL-Version: 2.0.14.0 Kernelversion: 5.15.133.1-1 WSLg-Version: 1.0.59 MSRDC-Version: 1.2.4677 Direct3D-Version: 1.611.1-81528511 DXCore-Version: 10.0.25131.1002-220531-1700.rs-onecore-base2-hyp Windows-Version: 10.0.22631.3296

If WSL is not installed:

wsl.exe --install --no-distribution --web-download

If WSL is installed but too old:

wsl.exe --update --web-download

Now recheck wsl.exe --version.

Install Codchi

Download, open and install the latest codchi.msix. MSIX or AppX is the packaging format for Windows Apps and should work out of the box. Windows even handles subsequent updates of Codchi automatically, but you can download and install a newer codchi.msix at any time.

Shell Completions

On some Windows Systems running PowerShell scripts is considered a security vulnerability and often completely disabled. Therefore Codchi doesn't try to automatically run PowerShell scripts and you have to manually add the following to the end of your PowerShell configuration (find it by running $PROFILE in PowerShell):

Invoke-Expression (& codchi completion powershell | Out-String)

Further Recommendations

  • For better tab complete and history search:
    # Shows navigable menu of all options when hitting tab Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete # Autocompletion for arrow keys (when something was already typed) Set-PSReadlineKeyHandler -Key UpArrow -Function HistorySearchBackward Set-PSReadlineKeyHandler -Key DownArrow -Function HistorySearchForward
  • Install Starship.rs for a better prompt

Linux

Prerequisites

On Linux Codchi uses LXD for virtualisation. Follow the official installation instructions until lxd init.

Install Codchi

Currently, Codchi is only packaged with Nix on Linux.

Install Nix (uses the Determinate Nix Installer):

# with SystemD: curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install # without SystemD: curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install --init none

You might want to add codchi's binary cache to speed things up (this step is optional):

nix-env -iA cachix -f https://cachix.org/api/v1/install cachix use codchi

Now install codchi:

nix profile install github:aformatik/codchi

Shell Completions

When installed via Nix, shell completions should automatically work inside bash, zsh and fish. There are also completions available for the following shells which must be installed manually by the user:

  • carapace
  • elvish
  • fig
  • nushell

For example for elvish:

eval (codchi completion elvish | slurp)

NixOS

Prerequisites

Flakes need to be activated.

Install LXD and add codchi's binary cache (optional but faster):

virtualisation.lxd.enable = true; virtualisation.lxc.lxcfs.enable = true; virtualisation.lxd.recommendedSysctlSettings = true; # Allow your user to use LXD users.users.<your user>.extraGroups = [ "lxd" ]; # optional but recommended: nix.settings = { extra-substituters = [ "https://codchi.cachix.org" ]; trusted-public-keys = [ "codchi.cachix.org-1:dVwdzogJgZO2x8kPKW02HNt2dpd/P/z46pY465MkokY=" ]; }; # If you use a local DNS server. See https://github.com/NixOS/nixpkgs/issues/263359 firewall.interfaces.lxdbr0.allowedTCPPorts = [ 53 ]; firewall.interfaces.lxdbr0.allowedUDPPorts = [ 53 67 ];

Now, nixos-rebuild. Then run lxd init manually.

Shell Completions

Shell completions should automatically work inside bash, zsh and fish, provided that shell completion is enabled:

{ programs.bash.enableBashCompletion = true; programs.zsh.enableBashCompletion = true; programs.fish.vendor.completions.enable = true; }

There are also completions available for the following shells which must be installed manually by the user:

  • carapace
  • elvish
  • fig
  • nushell

For example for nushell (via home-manager):

{ pkgs, inputs, ... }: { programs.nushell.extraConfig = '' source ${pkgs.runCommand "codchi-nushell-complete" {} '' ${inputs.codchi.packages.${pkgs.system}.default}/bin/codchi complete nushell > $out ''} ''; }

Install Codchi

In your flake.nix:

inputs.codchi.url = "github:aformatik/codchi"; inputs.codchi.nixpkgs.follows = "nixpkgs"; outputs = inputs@{ ... }: { # Pass inputs to your NixOS configuration (e.g. via extraArgs) };

In your NixOS configuration:

{ inputs, ... }: { environment.systemPackages = [ inputs.codchi.packages.x86_64-linux.default ]; }

MacOS

DETAILS

Currently not implemented. Possible Drivers are https://orbstack.dev/ (proprietary) and https://lima-vm.io/(open source, limited support for the newer faster virtualisation on Macs)