kdeps

kdeps

Before moving on, please consider giving us a GitHub star ⭐️. Thank you!

Git-native AI Appliance Builder - your agent is YAML in your repo; ship the workflow, tools, and model as one self-contained deployment that runs anywhere.

kdeps packages an AI workload - agent or deterministic API, not a chatbot - into a unit you can run as a terminal REPL, an HTTP API, a Docker image, Kubernetes manifests, a bootable ISO, or a single binary. The definition is text you commit: reviewed as a pull request, versioned by git tag, built reproducibly from a commit in CI. Change the YAML, and the appliance behaves differently - your git history is the changelog of the agent's behavior. One YAML file replaces a Python script wiring together an LLM SDK, a web server, retry logic, and a Dockerfile. It runs open-source, self-hosted models by default, so the built appliance has no per-token cost and no dependency on an external AI service - it works the same on a laptop and inside an air-gapped network. That makes kdeps a data-sovereignty tool: run your own LLM and coding agent on servers in your own country, and your prompts, code, and data never reach a foreign cloud. kdeps is a small number of bounded pieces - pick the one you need:

• kdeps agent - run kdeps and you are in an autonomous AI REPL: tool use, memory, fully offline against a local model. No config, no API key.
• kdeps workflow - define what the agent does in one workflow.yaml and run it as an HTTP API, a bot, or a file processor. Same file, laptop or server.
• kdeps agencies - coordinate several specialized agents as one system, delegating work through the agent: resource.
• kdeps LLM server - provision a standalone OpenAI-compatible inference appliance, no workflow path required.
• kdeps deploy - ship a workflow unchanged as a Docker image, Kubernetes manifests, a bootable ISO, or a single binary.
• kdeps registry (optional) - find, install, and publish shared agents and components by name. Not needed to build or run your own.

Data sovereignty

Run your own LLM and coding agent on your own country's servers - no prompts, source code, or customer data sent to foreign AI providers.

users -> kdeps agent/workflow (your server) -> LLM server (your server)
                                    \-> your data (files, DBs, repos)

kdeps                 # coding agent REPL on a local model - nothing leaves the machine
kdeps llm wizard      # stand up your own OpenAI-compatible LLM server in your datacenter
kdeps bundle build    # pin the model inside an image for air-gapped networks

Hosted backends are opt-in, never default. See Data sovereignty.

Quickstart

# workflow.yaml - a two-resource chat API. No LLM server needed: the default
# model (llama3.2:1b) runs as a local llamafile, downloaded on first run.
apiVersion: kdeps.io/v1
kind: Workflow
metadata:
  name: my-agent
  version: "1.0.0"
  targetActionId: response   # the resource whose output is the HTTP response
settings:
  apiServer:
    portNum: 16395
    routes:
      - path: /api/v1/chat
        methods: [POST]
resources:
  - actionId: llm
    name: LLM Chat
    validations:
      methods: [POST]
      routes: [/api/v1/chat]
      check:
        - get('q') != ''      # 'q' comes from the JSON body
      error:
        code: 400
        message: "'q' is required"
    chat:
      model: llama3.2:1b      # a name, "router"/"auto-router", or "system" (follow ~/.kdeps/config.yaml)
      role: user
      prompt: "{{ get('q') }}"
      timeout: 60s
  - actionId: response
    name: API Response
    requires: [llm]            # runs after 'llm' - the DAG resolves order
    apiResponse:
      success: true
      response:
        answer: get('llm').message.content

# KDEPS_API_AUTH_TOKEN is the HTTP endpoint's bearer token - not an LLM key
export KDEPS_API_AUTH_TOKEN=dev-token
kdeps run workflow.yaml

curl -s -X POST localhost:16395/api/v1/chat \
  -H "Authorization: Bearer $KDEPS_API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"q": "What is entropy, in one sentence?"}'
# {"success": true, "data": {"answer": "Entropy is a measure of disorder..."}}

More examples: kdeps.com/examples (25 walkthroughs, each a working project).

Install

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

Windows (PowerShell):

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

Or with Homebrew (macOS and Linux):

brew install kdeps/tap/kdeps

Desktop app

A chat window for the agent loop - the same slash commands, autocomplete and model picker (harvested llamafile/GGUF, Ollama and cloud models) as the terminal REPL, history, search, drag-and-drop files, and a settings modal (harness, custom instructions, memories, all config.yaml settings). One Go codebase for macOS, Linux and Windows; download it from the release page (macOS .dmg for Apple Silicon and Intel, Linux .tar.gz, Windows .zip) or build it with make desktop-package. It is standalone: the kdeps CLI does not need to be installed. Docs

brew install --cask kdeps/tap/kdeps-desktop   # macOS (Apple Silicon and Intel)

Windows: scoop bucket add kdeps https://github.com/kdeps/scoop-bucket && scoop install kdeps-desktop. Linux: .deb, .rpm, Arch package or .tar.gz. Full steps: Desktop app docs.

make desktop-package   # macOS: dist/desktop/*.dmg | Linux: .tar.gz | Windows: .zip

How it works

Whichever piece you use, a workflow runs in one of two execution modes - and an agency bundles several workflows into one system.

Workflow mode

DAG-deterministic request/response pipelines. Each resource declares its dependencies via requires: and runs in order, ending in an apiResponse.

The LLM call inside a chat: resource is still probabilistic, but the pipeline around it is not: the same request takes the same path, validation runs before any model call, and the response is shaped to a fixed schema.

Resources cover LLM chat, HTTP, Python, shell, SQL, email, web scraping, browser automation, embeddings, local and web search, and calls to other agents or components. Expressions (get(), output(), set(), plus Jinja2 control flow) wire the steps together.

kdeps run workflow.yaml          # local, instant startup
kdeps run ./my-agent/            # or point at a directory containing workflow.yaml
kdeps run workflow.yaml --dev    # hot reload

Agent loop mode

An autonomous LLM loop. Every workflow becomes a callable tool, and the LLM decides which to call, in what order, to complete the task. Runs as an interactive REPL until you exit (Ctrl+D). Each prompt is rewritten for clarity before the turn (/refine off to disable), and a built-in governor soft-stops read-only exploration loops (ls/read_file over and over) and forces the model to produce output, and soft-stops every failed tool or model call so the model retries with the error and the surrounding file lines on a hidden channel (/efficiency off to disable). Sessions and memory are kept per working directory under ~/.kdeps/; kdeps in a folder with history offers a resume picker.

kdeps                            # bare agent loop REPL (resume picker if this folder has history)
kdeps --new                      # start a clean session, skip the picker
kdeps ./my-agent/ --model llama3.2 --system "You are a DevOps assistant."
kdeps --theme black              # flat legible dark-gray disguise theme (model name abbreviated); also linux, vim, emacs

Agencies

A collection of agents that work together. Each agent is its own workflow.yaml with its own resources, model, and logic, wired together with the agent: resource type - like calling a function, but the function is an entire AI pipeline.

kdeps run agency.yaml

Docs: Workflow mode · Agent loop mode · Agencies · Resources overview

Build and deploy

The workflow you run locally exports unchanged to any target:

kdeps bundle build .        # Docker image
kdeps export iso            # bootable edge ISO
kdeps bundle prepackage     # self-contained binary per arch
kdeps export k8s            # Kubernetes manifests

For a public HTTPS endpoint, add static PEM files or automatic Let's Encrypt to workflow.yaml, point DNS at the host, and open ports 80 and 443:

settings:
  letsEncrypt:
    domain: api.example.com
    email: [email protected]
  apiServer:
    hostIp: "0.0.0.0"
    portNum: 443

Docs: Deployment guide · TLS and HTTPS

Reference

• Registry - kdeps registry search|install|submit for pre-built components. kdeps.io
• Agent skill - npx skills add https://github.com/kdeps/skill --skill kdeps teaches Claude Code, Cursor, and other agents to scaffold kdeps projects. Docs
• LLM server appliance - kdeps llm wizard builds a standalone OpenAI-compatible inference server (ollama, llamafile, gguf, vllm, tgi, sglang, and more), no workflow path required. Docs · Commands
• Global config - machine-local settings (LLM backend, API keys, SQL/SMTP/IMAP connections) live in ~/.kdeps/config.yaml, never in workflow.yaml. kdeps edit to open it, kdeps doctor to check it. Docs
• Security - when apiServer is set, requests require a bearer token (KDEPS_API_AUTH_TOKEN) and pass through rate-limit, body-size, and concurrency caps before reaching the DAG. Docs
• Logging - structured JSON via log/slog. KDEPS_LOG_FORMAT=json for production; default level WARN; --verbose (INFO), --debug (DEBUG).
• Innovation technology - two standalone Go tools built alongside kdeps: kdeps/kartographer (graph library for resolving dependent nodes - powers the requires: DAG and folder/skill graphs) and kdeps/turo (reduces prose to content words to cut LLM input tokens - the optional agent-mode prompt reducer).
• Book - AI Appliances - Build & Deploy Autonomous AI Agents and Agencies in YAML. Free (PDF, EPUB, web).

---

Documentation | Registry | Apache 2.0