XNDV is a sandboxed, GPU-accelerated, terminal-first development environment. A ready-to-run box of overpowered dotfiles, like a living Awesome List of development tools, all wired into the same AI control plane.
Unify agentic tools through a local AI gateway for greater visibility, multi-provider resilience, OAuth-friendly logins, and optional local LLMs.
Run it as a:
- GPU-accelerated terminal with clipboard integration ← recommended
- TTY-only terminal for headless servers
- Full desktop environment in a window (x11docker)
- Docker-in-Docker environment for nested containers (sysbox)
Developed on and for Linux. Other platforms untested.
git clone https://github.com/xendarboh/xndv.git ~/src/xndv
cd ~/src/xndv
cp .env-example .env # edit to enable optional tools
cp -a conf.local-example conf.local # local overrides (see Customization)
make build # headless server? use `make build-tty-sys` instead
./bin.host/xndv
# optionally add ~/src/xndv/bin.host to your PATH for direct access to the launchermake build produces the X11 images for a desktop host; make build-tty-sys produces the
smaller TTY-only images (no X11, no x11docker needed) for headless servers. See Build.
- Open Source!
- Latest greatest terminal tools, LTS versions, vi-bindings
- Unified theming via tinty with native Neovim colorscheme sync
- Reproducible environment from Ubuntu base
- Security via sandboxing with analog control over isolation vs. functionality
| Dependency | Required For | Notes |
|---|---|---|
| docker or podman | Core | Container runtime |
| docker compose | Building | Build orchestration |
| make | Building | Recommended; or run Makefile commands manually |
| x11docker | max, min, sys (x11) |
Desktop/GUI runner only; not needed for tty mode or headless (sys on a server). Install with make install-x11docker |
| NVIDIA driver runfile (optional) | GPU in min, sys |
make fetch-nvidia-driver caches the host-matching installer for x11docker's fallback GPU |
| sysbox | sys mode |
Recommended for Docker-in-Docker |
| rofi / dmenu / fzf | Launcher | Any one; detected in order |
pactl (pulseaudio-utils) or PipeWire ≥ 1.4 |
Audio (optional) | Host sound server + client tool x11docker probes; see Audio |
| Nerd Font | tty mode |
Container provides fonts for GUI modes |
| Docker Model Runner | Local AI (optional) | GPU-accelerated inference via nvidia-container-toolkit, etc |
The bin.host/xndv launcher provides an interactive menu (via rofi, dmenu, or fzf) for selecting modes, naming containers, and toggling volume mounts.
| Mode | Description | X11 | GPU | Use Case |
|---|---|---|---|---|
max |
Most host integration, direct GPU | Yes | Direct | Daily development |
min |
Minimal host integration, fallback GPU | Yes | Fallback | Sandboxed agents, untrusted code |
sys |
Docker-in-Docker via sysbox | Yes | Fallback | Stronger isolation, run containers |
tty |
TTY-only, no X11 | No | No | Headless servers, SSH sessions |
All modes are containerized and sandboxed; the difference is capability and host integration.
Runner: A mode is launched under one of two runners — x11 (x11docker + kitty window) or tty (headless docker run -d, re-enter via the menu). The launcher offers only the runners your host supports (x11docker installed vs. not) and only modes whose image is built. On a server without x11docker, sys and tty run headless automatically; where x11docker is installed, modes that support both (e.g. sys) show a runner choice (sys·x11, sys·tty).
Selector: The launcher probes for an available selector. Override with xndv -s <selector>.
Hostname: Each container reports <server>-<instance> — the short name of the server it runs on, then the container name you gave it. xndv-sys-1 on server1 is server1-xndv-sys-1 in every mode, and recreating it under the same name brings the same hostname back. There is nothing to configure: the value is derived at launch, so anything that keys on the machine name — WakaTime attribution, shell prompts, logs — stays pinned to the instance rather than drifting with the container id. Characters a hostname cannot hold (_, ., anything else outside a-z0-9-) become hyphens, and the name is capped at 63 characters by trimming the server segment first, so the instance stays distinguishable.
# interactive launcher: create or enter a container
xndv
# enter directly; maps host $PWD and remains in shell after the command exits
xndv enter xndv-sys -- lazygit
# omit the name with XNDV_CONTAINER or exactly one running container
XNDV_CONTAINER=xndv-sys xndv enter -- lazygit
xndv enter -- lazygit
# override the mapped working directory
xndv enter xndv-sys -C /container/path -- lazygit
# host entry exposes the first command token to Herdr
xndv enter xndv-sys -- claude "/do-stuff"
# quote compound (fish shell) commands
xndv enter xndv-sys -- 'git status; lazygit'These same commands work from inside a container, where enter simply runs the command there. The
automatic Herdr identity is host-only; container-local entry cannot annotate its host-side wrapper.
The launcher's Mount Selection menu lists the built-in mounts plus anything in conf.local/xndv/mounts.conf, so a host directory can appear at extra paths inside the container. That lets one repo live in several trees at once without duplicating it on disk — wherever a given tree wants to find it.
A mapping is just a pair of paths, so any layout works. For example, to organize a project by provider URL (~/src/github/user/repo) and also map it within a workspace:
# [+]tag:src:[dest]:[options]
+acme:~/src/github/acme/widget:~/src/workspace/acme/widget:ro
A leading + pre-selects the mount at launch; without it, the mount is listed but off until toggled. tag groups the entry in the menu — a workspace name works well. A leading ~/ is the host home in src and the container home in dest. See conf.local-example/xndv/mounts.conf.
The two ends of a mapping are handled differently, and the difference is deliberate.
A source that does not exist yet is created when the mount is selected, owned by the user running the launcher. Listing an entry alone puts nothing on disk — ticking it in the menu is the act that does. A source that must be root-owned is created that way beforehand: an existing path is mounted exactly as it is, never re-created and never chowned.
An explicit destination must already exist as a directory, and it is yours to make and to own. xndv never creates one, and never creates the tree above it. If a selected mount names a destination that is not there, the launch is abandoned before any command is generated — nothing is offered for confirmation and nothing reaches Docker. So mkdir -p ~/src/workspace/acme before the mapping above will resolve. xndv mount follows the same rule inside a running container, and fails visibly rather than creating the mount point.
Mounts are set at container creation, so a new mapping normally takes effect on the next launch.
Live mounts: xndv mount applies the same mounts.conf from inside a running container — a toggle menu by default, or add/rm/ls directly.
xndv mount # toggle the configured mounts, then apply
xndv mount ls # what is mounted here now
xndv mount add ~/src/github/acme/widget ~/src/workspace/acme/widget ro
xndv mount rm ~/src/workspace/acme/widgetThese binds live only in the container's mount namespace: the host never sees them, and they are gone when the container stops — so there is no host state to clean up, and mounts.conf re-establishes everything at the next launch. Binding needs CAP_SYS_ADMIN, so it is available in sys mode only; ls works in every mode.
Why not symlinks: agentic tools resolve paths before checking them against the session root, so a link pointing outside that root gets rejected — and @ file selectors, file watchers, and ignore-file semantics follow suit. A bind mount is the same directory at a second path, with nothing to resolve, so every tool treats it as ordinary.
Picking the right tool for one repo in several places:
| Need | Use |
|---|---|
| Same live state visible in two trees | Bind mount (mounts.conf) |
| Views on different branches | git worktree add — one clone, separate checkouts, no syncing |
| Read-only reference, path can be anywhere | The agent's own out-of-tree access (Claude Code: /add-dir or permissions.additionalDirectories) |
Every bind-mounted view is the same files: one .git, one branch, one index, and a deletion in any view is a deletion everywhere. Mount reference copies ro and keep exactly one writable location per repo.
Run directly without the interactive menu, for example:
# GPU-accelerated terminal with clipboard
x11docker --gpu --clipboard --network --user=RETAIN -- --tmpfs=/tmp:exec -- xen/dev
# Full desktop in a window
x11docker --desktop --gpu --clipboard --network -- xen/dev
# TTY-only (no x11docker needed)
docker run -it --rm --network=host xen/devThe sys mode uses sysbox for secure, rootless Docker-in-Docker without --privileged.
Headless servers: sys runs without x11docker. Build with make build-tty-sys (stacks xen/sys on the TTY xen/dev, no X11 layer) and the launcher runs it via plain docker run -d — create the instance, then re-enter it from the launcher menu (docker exec). x11docker is not required.
Tradeoffs: No direct GPU (uses --gpu fallback under x11), bridged networking (no --network=host).
Persistence: Inner Docker data stored at ~/.local/share/xndv/xndv/sysbox/docker.
Off by default. Sound is provided by the host's sound server — the container only ever runs clients — and x11docker does the wiring, so audio applies to the x11 runner (max, min, sys·x11), not to headless tty.
# in .env
ENABLE_AUDIO=1
make build # adds sound clients to the xen/x11 image
./bin.host/xndv # launcher adds the sound option to x11docker
./test/audio.sh # from inside the container: verify and play a sound
./test/microphone.sh # record five seconds, then play the recording backAUDIO_MODE names an x11docker sound option, written without its leading dashes. The default auto probes the host and picks the first that fits:
AUDIO_MODE |
What it shares | auto selects it when |
|---|---|---|
pipewire |
Sandboxed PipeWire socket minted by pw-container |
Host runs PipeWire ≥ 1.4 |
pulseaudio=host |
The host's existing PulseAudio/pipewire-pulse socket | Host runs pipewire-pulse, which cannot mint a second socket |
pulseaudio=socket |
A dedicated socket minted via pactl |
Host runs classic PulseAudio |
pulseaudio=tcp |
A PulseAudio TCP port | sys mode — sysbox cannot reach the host user's runtime dir |
alsa[=CARD] |
/dev/snd directly, bypassing the host sound server |
Nothing else is available |
Override with any of the above, e.g. AUDIO_MODE=alsa=PCH (card names from aplay -l).
Caveats:
- Every mode lets container applications capture audio output and microphone input — this is a deliberate loosening of isolation, which is why it is opt-in.
alsabypasses the host sound server, so host and container will fight over the device. Prefer apulseaudioorpipewiremode whenever a sound server is running.- Ubuntu 24.04 ships PipeWire 1.0, which has no
pw-container;--pipewireneeds 25.04 or newer.pulseaudio=hostis the equivalent there. - x11docker falls back to no sound rather than failing the launch. Run with
--verbose(already set formax/min/sys) to see which option it settled on. pulseaudio=hostandpipewirebind their socket under/tmp, where these modes also mount--tmpfs=/tmp:exec. Docker orders the tmpfs first so the socket lands inside it; if a silent container turns out to be missing/tmp/*.socket.host, useAUDIO_MODE=pulseaudio=tcp.
{alias}— invoke via shell alias (likeocfor OpenCode).
- x11docker: Secure GUI containers
- Sysbox: Rootless system containers, enabling Docker-in-Docker
- Xen: Elven Tech Wizard
- Neovim: Vim-fork focused on extensibility and usability
- LazyVim: Neovim config for the lazy (INSTALL_NVIM_LAZYVIM)
- better-escape.nvim: Escape from insert mode without delay
- gruvbox.nvim: Gruvbox colorscheme
- herdr-splits.nvim: Seamless navigation and resizing between Neovim and herdr
- markdown-preview.nvim: Markdown preview plugin
- noir.nvim: Syntax highlighting and LSP for Noir
- nx.nvim: NX console features for Neovim
- tinted-nvim: Tinty colorscheme sync with native fallback
- tokyonight.nvim: Tokyo Night colorscheme
- tuicr.nvim: Neovim integration for tuicr
- wakatime.nvim: Automatic time tracking
- LazyVim: Neovim config for the lazy (INSTALL_NVIM_LAZYVIM)
- aider: AI pair programming in your terminal (INSTALL_AIDER)
- aider.nvim: Neovim integration for aider
- claude-code: Agentic coding tool in your terminal (INSTALL_CLAUDECODE)
- GSD: Meta-prompting and spec-driven development system
- CLIProxyAPI: OAuth adapter for login-based LLM providers
- CLIProxyAPI Quota Inspector: Terminal tool for monitoring CPA quota usage
- Codex: Lightweight coding agent that runs in your terminal (INSTALL_CODEX)
- Docker Model Runner (DMR): Run LLMs locally via Docker
- herdr: Agent multiplexer that lives in your terminal
- herdr-git-status: Shows each space's git working-tree status in the sidebar
- herdr-splits.nvim: Seamless navigation and resizing between Neovim and herdr
- herdr-spreader: Reproduce herdr workspace layouts from declarative YAML files
- LiteLLM: Unified LLM proxy — 100+ providers, one endpoint, cost tracking, caching
- llmfit: Score and rank LLMs by hardware fit (RAM, CPU, GPU)
- Oh My Pi: Batteries-included terminal coding agent with LSP, debugger, and subagents (INSTALL_OMP)
- worked-for: xndv extension showing elapsed agent work time
- Open WebUI: Chat UI for local LLMs
- OpenCode: Open source coding agent (INSTALL_OPENCODE)
{oc}- GSD: Meta-prompting and spec-driven development system
- opentmux: Smart tmux integration for real-time agent panes
- opencode-notifier: Desktop notifications for OpenCode
- opencode-wakatime: OpenCode usage time tracking
- opencode.nvim: Neovim integration for opencode
- OpenPackage: Universal package manager for AI coding agent skills/rules/commands
- repomix: Pack repository into AI-friendly file
- rtk: Token-optimized CLI proxy (60-90% token savings on dev operations)
- tuicr: Human-in-the-loop code review TUI for AI-generated changes
- ack: Grep-like tool for searching code
- bat: A cat(1) clone with syntax highlighting
- btop: Resource monitor with GPU support
- exa: Modern replacement for 'ls'
- fd: Simple, fast alternative to 'find'
- fish-shell: User-friendly command line shell
- fish-exa: exa aliases for fish
- fish-nx: Fish completions for Nx
- fisher: Plugin manager for Fish
- nix-env.fish: Nix environment for fish (INSTALL_NIX)
- Shortcuts: see Shell Shortcuts
- fzf: Command-line fuzzy finder
- htop: Interactive process viewer
- mani: CLI tool to help you manage multiple repositories
- jq: Command-line JSON processor
- ripgrep: Fast regex search respecting gitignore
- silversearcher-ag: Code search faster than ack
- ShellCheck: Shell script static analysis tool
- spacer: Insert spacers in command output
- starship: Minimal, fast, customizable prompt
- stow: Symlink farm manager
- tinty: Unified colorscheme manager for 70+ apps
- tmux: Terminal multiplexer
- tmux-resurrect: Persist environment across restarts
- tmux-window-name: Smart window naming
- tpm: Tmux Plugin Manager
- tree: Directory tree viewer
- zoxide: Smarter cd command
- delta: Syntax-highlighting pager for git, diff, grep, and blame output
- gh: GitHub's official CLI
- git: Latest stable version
- git-absorb: Automatic fixup commits
- git-crypt: Transparent file encryption [fork]
- git-filter-repo: Rewrite git history fast
- gfr-bfg-ish: BFG Repo Cleaner reimplementation
- gfr-clean-ignore: Remove gitignored files from history
- gfr-insert-beginning: Insert a file at history start
- gfr-lint-history: Lint all non-binary files across history
- gfr-signed-off-by: Add Signed-off-by tags to commit range
- git-lfs: Large file versioning
- lazygit: Terminal UI for git
{lz} - woodpecker-cli: CLI for the Woodpecker CI/CD engine (INSTALL_WOODPECKER)
- Bun: Fast JS runtime, bundler, test runner, package manager
- Deno: Modern JavaScript/TypeScript runtime
- Go: The Go programming language
- LLVM: Clang toolchain (INSTALL_LLVM)
- Nix: Purely functional package manager (INSTALL_NIX)
- Node.js: JavaScript runtime
- fnm: Fast Node.js version manager
- npm-check-updates: Find newer package versions
- npm-check: Check for outdated dependencies
- pnpm: Fast, disk space efficient package manager
- yarn: Dependency management
- Python: Programming language
- uv: Extremely fast Python package and project manager
- Ruby: Dynamic programming language
- rake: Ruby build automation tool
- Rust: Reliable and efficient software
- cargo-edit: Manage cargo dependencies from CLI
- rust-analyzer: Rust compiler front-end for IDEs
- rustup: Rust toolchain installer
- circom: zkSnark circuit compiler (INSTALL_CIRCOM)
- Foundry: blazing fast, portable and modular toolkit for Ethereum app dev
- Noir: DSL for zero knowledge proofs (INSTALL_NOIR)
- barretenberg: ZK prover backend
- Solidity: Smart contract language
- Ansible: IT automation
- AWS CLI v2: AWS interaction
- OpenTofu: Open source Terraform alternative
- Packer: Machine image builder
- terraform-local: Deploy to LocalStack
- Terraform: Infrastructure as code
- CMake: Cross-platform build system generator
- cpanminus: CPAN module installer
- cypress: Browser testing deps (INSTALL_CYPRESS_DEPS)
- dprint: Pluggable and configurable code formatting platform
- fastmod: Large-scale codebase refactors
- grip: GitHub Markdown preview server (INSTALL_GRIP)
- ImageMagick: Image manipulation
- kpcli: KeePass CLI
- ncdu: NCurses Disk Usage
- ninja-build: Fast build system
- platformio-core: Embedded development (INSTALL_PLATFORMIO)
- prettier: Opinionated code formatter
- protobuf: Protocol Buffers (INSTALL_PB)
- buf: Modern protobuf workflow
- ranger: VIM-inspired file manager
- sqlite: SQL database engine
- tauri-cli: Build desktop apps (INSTALL_TAURI)
- Tomb: Crypto Undertaker (INSTALL_TOMB)
- tree-sitter-cli: Parser generator for syntax trees
- watchexec: Execute on file changes
- websocat: WebSocket CLI client
- Brave browser (INSTALL_BROWSER_BRAVE)
- Chromium (INSTALL_BROWSER_CHROMIUM)
- kitty: GPU-accelerated terminal
- Nerd Fonts: Developer fonts with icons
- Hack: Typeface for code
- xclip: X11 clipboard CLI
- Xfce: Lightweight desktop environment
- xfce4-notifyd: Desktop notification daemon
- xfce4-taskmanager: Process/task manager
- xfce4-terminal: Terminal emulator
- docker: The Docker CLI
- docker-compose: Orchestrate multi-container Docker apps
Scripts in bin/ are available inside the container:
- x-ai: Query a local LLM (via Docker Model Runner) directly from the terminal
- x-aztec-ai-tools: Setup a project with Aztec/Noir AI Tooling (MCP servers, skills, platform configs)
- x-claude-attribution-off: Disable all Claude Code commit/PR attribution in the current project
- x-git-commit: AI-generated conventional git commit messages
- auto-selects local LLM (DMR) when available, falls back to opencode
- opens editor (neovim) with N alternatives for final selection
- invoke from lazygit with
CTRL+a
- x-herdr-clear: Clear the current herdr pane's agent authority
- x-herdr-exec: Run a command while reporting its state to the herdr pane
- x-herdr-spreader-apply: Apply every
herdr-spreader.yamlfound beneath the current directory--dry-runlists the files without applying them
Scripts in bin.host/ run on the host (outside the container):
- xndv: Interactive menu and direct entry for managing the xndv environment
launch: Select mode, name container, toggle mounts, attach to running instancesclean: Disk monitor and selective cleanup for host-persistent directoriesenter: Enter a running instance, optionally run a command, then remain in Fish- also on the container's PATH as
xndv, where it runs the command in place
- also on the container's PATH as
mount: Bindmounts.confentries inside a running container (sysmode); see Mounts
Optional tools installed on-demand via setup.d/:
- Aztec Toolchain: Privacy-first L2
- WhisperX: Speech recognition with timestamps
Fish abbreviations and functions from config.fish, available in every container shell:
| Shortcut | Runs |
|---|---|
s |
git status |
d |
git diff |
b |
git branch -av |
gb |
git branch |
gg |
git grep |
gl |
git log --show-signature |
gln |
git log --oneline | nl |
ga |
git absorb --base HEAD~N; N = commits ahead of upstream |
gr [N] |
git rebase -i --autosquash HEAD~N; N defaults to commits ahead |
gra [N] |
gr + --exec amend each commit with --reset-author |
see [DUR] |
files changed within DUR (default 1m) via fd, noise-filtered |
vimgit X |
open every file with git status code X in nvim, e.g. vimgit M |
mkcd DIR |
mkdir -p DIR then cd into it |
dc |
docker compose |
fm |
fastmod --hidden |
grip |
grip --theme=dark |
hc |
x-herdr-clear |
hr |
herdr --remote-keybindings server --remote |
hs |
x-herdr-spreader-apply |
hx |
x-herdr-exec |
kt-clip |
kitty +kitten clipboard |
kt-diff |
kitty +kitten diff |
kt-icat |
kitty +kitten icat |
lz |
lazygit |
oc |
opencode |
tc |
tinty cycle through configured themes |
v |
nvim |
vd |
nvim -d (diff mode) |
vr |
nvim -R (read-only) |
x |
cd $XNDV_DIR then open nvim there |
xm |
xndv mount — toggle live bind mounts (see Mounts) |
Two commands are also transparently wrapped: nx repaints the prompt afterward, and tuicr adds
--no-update-check --stdout and copies its output to the clipboard. Where installed,
brave-browser and chromium gain --no-sandbox.
Edit .env to set versions and enable optional tools (copy from .env-example).
make build # X11 images: xen/x11 → xen/dev → xen/sys
make build-tty # TTY-only image (smaller, no X11)
make build-tty-sys # TTY-only + sysbox layer, for headless `sys` mode
make help # all available targetsmake retag # tag current images :prev first, to keep a rollback
make rebuild # rebuild X11 images with --no-cache, pulling a fresh
CD6B
base
make rebuild-tty # same for TTY-only (also: make rebuild-tty-sys)
make refresh # pull peripheral images (models, gateway) and reinstall the DMR runnerVerify terminal and environment capabilities with scripts in test/:
./test/truecolor.sh # terminal color support
./test/tput.sh # 256-color tput table
./test/glyphs.sh # nerd font rendering
./test/test-fonts.sh # full nerd font codepoint sweep
./test/kitty-debug-fonts.sh # log kitty's font fallback chain
./test/italics.sh # italic text
./test/gpg.sh # GPG volume mapping
./test/audio.sh # sound wiring and playback (requires ENABLE_AUDIO=1)
./test/microphone.sh # microphone recording and playback (requires ENABLE_AUDIO=1)
./test/herdr-notification.sh # herdr notification (title, body, sound)
./test/ai-gateway.sh # LLM gateway routes; run from the host with the gateway up
./test/mounts.sh # mounts.conf resolution; asserts, exits non-zero on failure
./test/hostname.sh # container hostname contract; asserts, exits non-zero on failuremounts.sh and hostname.sh run unattended. Both exercise the runtime with a throwaway container when a local image is present; set XNDV_TEST_IMAGE to name one other than alpine.
conf/— Git-tracked user configuration, stowed to the user's home directory during the image buildconf.local/— Private/local user configuration, gitignored and stowed to the user's home directory at runtimeconf.system/— Git-tracked system configuration, stowed to the root filesystem (/) during the image build
The build-time Stow links target files under the xndv source tree. When the host source tree is mounted at
~/src, edits to existing files in conf/ and conf.system/ are visible in the container without rebuilding
the image. For example, conf.system/etc/codex/config.toml is available as /etc/codex/config.toml.
Runtime-only and private files belong in conf.local/ (for example, conf.local/.aws/ → ~/.aws/):
cp -a conf.local-example conf.localNotable files in conf.local/, for example:
| File | Purpose |
|---|---|
xndv/bash.sh |
Custom env vars (GH_TOKEN, FLEEK_API_KEY, etc.) |
xndv/directory_map.txt |
Path mappings for tmux/kitty CWD preservation |
xndv/mounts.conf |
Extra bind mounts (see Mounts) |
.wakatime.cfg |
Wakatime/Wakapi config |
.aws/ |
AWS credentials |
The image installs the latest stable herdr with some herdr plugins. Run the same installer directly on a host when the herdr server lives outside xndv:
make install-herdr # or: ./build/install.d/herdr.shOn a host this installs herdr (a static binary — no toolchain) and links the plugin binaries already built
in the xen/dev image, extracted via a throwaway container to minimize host dependencies. Re-run after rebuilding the image to
pick up newer plugins.
Configuration remains Stow-managed. When launched from a host herdr pane, bin.host/xndv mounts the host
herdr directory at ~/.config/herdr-host inside the container and forwards its socket, pane, client, and
herdr-splits environment. For a host-issued xndv enter -- COMMAND, the host-side Docker foreground
process exports the first command token as HERDR_AGENT, so herdr can identify the agent hidden behind
the container boundary without a caller-supplied prefix:
./bin.host/xndv enter xndv-sys -- codex '$worker-prime $msg wC'Remote clients should use the server's plugin-action keybindings:
herdr --remote <host> --remote-keybindings serverInclude xndv's git config conditionally:
# ~/.config/git/config
[includeIf "gitdir:/home/xndv"]
path = ~/src/xndv/conf/gitconfigColorschemes are managed by tinty, providing unified theming across apps.
Set OPTIONS_THEME in .env for the image build-time default.
Neovim listens for theme changes and applies the corresponding native plugin (tokyonight, gruvbox) when available.
Change theme at runtime:
tinty cycle # cycle through preferred schemes
tinty apply base24-tokyo-night-dark # or any scheme from `tinty list`Run local AI model(s) with Docker Model Runner and interact via Open WebUI, OpenCode, or bin/x-ai. Optional, independent of the main xndv build.
# Edit MODELS_* vars in .env (see .env-example) to configure the model
make models-upAccess Open Webui at http://localhost:12444
Model downloads on first start. See docker model list and use docker model for management.
For more models, check out the published Docker Hub AI models or Hugging Face Transformers (compatible with Docker Model Runner). Pull any model with docker model pull and set MODELS_PRIMARY to your chosen image.
| Variable | Description |
|---|---|
MODELS_PRIMARY |
Model (any docker model pull compatible) |
MODELS_WEBUI_PORT |
Open WebUI port |
make models-up # Start docker containers (detached)
make models-down # Stop
make models-logs # Follow logs
make models-status # Show containers
make models-thinking-enable # turn on model reasoning (also: models-thinking-disable)Route LLM traffic through a local LiteLLM proxy for unified observability, cost tracking, and response caching across AI clients and model providers. This is an optional, independent component of the main environment.
cp conf.local-example/xndv/litellm.yaml conf.local/xndv/
# Edit conf.local/xndv/litellm.yaml for your setup
make gateway-up # on docker host
# set ENABLE_GATEWAY=1 in .env, then restart shell in containerAccess LiteLLM UI at http://localhost:4000
By default, gateway services bind to 127.0.0.1 only, which works for max/tty modes but not sys/min. Override GATEWAY_BIND_HOST in .env if you intentionally want LAN or wider access.
| Variable | Description |
|---|---|
ENABLE_GATEWAY |
Set to 1 to activate gateway routing in the container |
GATEWAY_BIND_HOST |
Host interface for published gateway ports (default: 127.0.0.1) |
GATEWAY_MASTER_KEY |
LiteLLM master key (used as default client auth) |
GATEWAY_PROXY_PORT |
LiteLLM proxy port (default: 4000) |
GATEWAY_OAUTH_PORT |
CLIProxyAPI OAuth port (default: 8317) |
GATEWAY_API_KEY_* |
Provider API keys passed to LiteLLM |
GATEWAY_CLIENT_BASE_URL |
Override gateway URL (default: http://${XNDV_HOSTNAME}:PORT) |
GATEWAY_CLIENT_API_KEY |
Override client auth key (default: GATEWAY_MASTER_KEY) |
XNDV_HOSTNAME is injected by the launcher at runtime so containers can reach host-exposed services across modes. It defaults to localhost in host-networked modes and host.docker.internal in isolated modes such as sys and min. It is an address the container dials out to — not the container's own name, which is Hostname.
Set GATEWAY_BIND_HOST=0.0.0.0 to listen on all interfaces, or set it to a specific LAN IP to expose the gateway only on that trusted network interface.
Route login-based providers through the gateway via CLIProxyAPI:
cp conf.local-example/xndv/cliproxyapi.yaml conf.local/xndv/
make gateway-up
make gateway-login # see list of supported providers
make gateway-login PROVIDER=someprovider # one-time per account: follow the URL to authorizeSupports any provider available in CLIProxyAPI. Run once per account. Re-run if a token is revoked or to add accounts for load balancing.
After logging in, uncomment the corresponding entries in conf.local/xndv/litellm.yaml and restart the gateway. Each model can have multiple deployments across providers and accounts — the gateway tries them in priority order, falling back to the next if one is rate-limited or down.
make gateway-up # Start gateway (detached)
make gateway-down # Stop
make gateway-logs # Follow logs
make gateway-status # Show containers
make gateway-login PROVIDER=<provider> # OAuth login
make gateway-quota # Check quota for connected OAuth providers