Installation ​

Install the kdeps CLI to start building agents locally. Docker is optional - only needed if you want to build container images for deployment.

Works in workflow and agent mode.

Already installed? Quickstart or Run locally.

Installing the kdeps CLI ​

macOS (Homebrew) ​

bash
brew install kdeps/tap/kdeps

Desktop app (standalone, no CLI needed): brew install --cask kdeps/tap/kdeps-desktop. Linux and Windows (Scoop, packages, or manual) install steps are in Desktop app.

Windows (Scoop) ​

powershell
scoop bucket add kdeps https://github.com/kdeps/scoop-bucket
scoop install kdeps           # CLI
scoop install kdeps-desktop   # desktop app, standalone

Linux packages (deb, rpm, apk, Arch) ​

Each release attaches native CLI packages, so the package manager tracks the install. Pick the file for your distro from the releases page:

bash
sudo apt install ./kdeps_<version>_linux_amd64.deb            # Debian, Ubuntu
sudo dnf install ./kdeps_<version>_linux_amd64.rpm            # Fedora, RHEL
sudo pacman -U kdeps_<version>_linux_amd64.pkg.tar.zst        # Arch
sudo apk add --allow-untrusted ./kdeps_<version>_linux_amd64.apk   # Alpine

Use linux_arm64 in the name on ARM machines. The desktop app has its own .deb, .rpm and Arch package that pull in the GTK and WebKit libraries for you; see Desktop app.

Linux, macOS, and Windows (curl) ​

bash
curl -LsSf https://raw.githubusercontent.com/kdeps/kdeps/main/install.sh | sh

Windows (PowerShell) ​

powershell
irm https://raw.githubusercontent.com/kdeps/kdeps/main/install.ps1 | iex

Installs kdeps.exe into %USERPROFILE%\.local\bin and adds it to your user PATH. To pin a version or choose a different directory:

powershell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/kdeps/kdeps/main/install.ps1))) -Tag v2.21.0 -BinDir C:\tools\bin

Windows (wget in WSL or Git Bash) ​

bash
wget -qO- https://raw.githubusercontent.com/kdeps/kdeps/main/install.sh | sh

Note: Git Bash or WSL also work if you prefer the shell-based installer above.

From source ​

Recommended: go install

bash
go install github.com/kdeps/kdeps/v2@latest

Or build manually:

bash
git clone https://github.com/kdeps/kdeps.git
cd kdeps
make build
./kdeps --version

On Windows without make (or Git Bash/WSL), build.ps1 and build.bat in the repo root do the same build with version/commit info embedded, matching make build:

powershell
.\build.ps1
cmd
build.bat

Verify installation ​

bash
kdeps --version

You should see output like:

kdeps version 2.21.0

Docker (optional) ​

Docker is only needed if you want to build container images for deployment. For local development and testing, kdeps runs natively without Docker.

Install Docker ​

Verify Docker installation ​

bash
docker --version

Local LLMs (no install needed) ​

Default backend is llamafile: no server, no GPU, no API key. The alias llama3.2:1b (~1.1 GB) downloads on first run. Full aliases, Ollama, and GGUF: Local models.

bash
kdeps llamafile list      # see all known model aliases
kdeps llamafile update    # refresh the registry from HuggingFace

First-run setup ​

The first time you run kdeps in a terminal with no ~/.kdeps/config.yaml, an interactive wizard asks how you want to run language models and writes the config for you:

text
  How should kdeps run language models?
    [1] llamafile  local, self-contained, no server install (recommended)
    [2] gguf       local GGUF models via llama.cpp
    [3] cloud      OpenAI, Anthropic, DeepSeek, Groq, xAI, ... (needs an API key)
    [4] ollama     connect to an Ollama server
    [5] router     route across multiple models by strategy (advanced)
    [6] m365       Microsoft 365 Copilot (browser login, no API key)
    [0] Skip (configure later)

Each choice fills in the matching llm: fields:

  • llamafile / gguf - sets backend and a default model.
  • cloud - sets backend, prompts for the provider's API key, and stores it under llm.<provider>_api_key.
  • ollama - sets backend: ollama and the host URL.
  • router - collects the models to route across and a strategy (fallback, round_robin, token_threshold, cost_optimized), written as llm.models + llm.strategy.
  • m365 - sets backend: m365. No API key: authenticates via a browser-cached Microsoft 365 sign-in (or headless credentials for CI/servers). See LLM Provider Reference - M365 Copilot.

In non-interactive environments (CI, pipes) kdeps skips the wizard and writes a fully commented template instead. Re-run the wizard any time by removing ~/.kdeps/config.yaml, or edit it directly with kdeps edit.

Ollama (optional) ​

To use Ollama instead of the default llamafile backend:

bash
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2:1b

Then select it in ~/.kdeps/config.yaml:

yaml
llm:
  backend: ollama  # default is "file" (llamafile)

Troubleshooting ​

Permission denied error ​

If you encounter a Permission Denied error during installation:

bash
curl -LsSf https://raw.githubusercontent.com/kdeps/kdeps/main/install.sh | sudo sh

Command not found ​

If kdeps is not found after installation, add ~/.local/bin to your PATH:

bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Then reload your shell:

bash
source ~/.bashrc  # or source ~/.zshrc

Docker permission issues (Linux) ​

If you get permission errors when running Docker commands:

bash
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

See also ​

Released under the Apache 2.0 License.

Copyright (c) 2024-present kdeps contributors