Skip to main content

kelder: Claude Code in a smolvm guest

Claude Code runs inside a minimal smolvm VM (Debian, nested KVM). It can start its own VMs (testvm) and containers (podman) there to run tests.

Install

Needs, on the host: smolvm 1.32 or newer, KVM with nested virtualization, Python 3.11 or newer and bash. kelder itself has no Python dependencies.

uv tool install kelder            # puts kelder on PATH
kelder self setup                 # create and provision the machine (safe to re-run)

uv tool uninstall kelder removes it again. From a checkout, uv tool install . installs that copy instead, and uv run kelder runs it without installing.

src/kelder/cli.py          the kelder command: arguments, running claude in the guest
src/kelder/session.py      which directories are attached, and by which sessions
src/kelder/config.py       a project's .kelder.toml
src/kelder/smolvm.py       settings and every smolvm CLI assumption
src/kelder/provision.py    create and provision the guest (kelder self setup)
src/kelder/smoketest.py    test a smolvm upgrade (kelder self smoketest)
src/kelder/guest/          files setup copies into the guest:
  testvm                     throwaway QEMU/KVM VMs (/usr/local/bin)
  smoketest                  checks smolvm behaviour after an upgrade (/usr/local/bin)
  containers-tsi.conf        podman DNS workaround (see below)

Usage

cd ~/git/app && kelder                  # attach ~/git/app and start Claude there
kelder self -C ~/git/other              # or name the directory
cd ~/git/app && kelder self -a ../lib   # also give Claude ~/git/lib
kelder -p "run the tests" | less        # non-interactive works too
kelder [--] [CLAUDE_ARGS...]
kelder self [-C DIR] [-a DIR]... [--] [CLAUDE_ARGS...]
kelder self help
kelder self setup
kelder self version

Only arguments after self (which must come first) are kelder's own:

  • self -C DIR: attach and start Claude in DIR instead of the current directory.
  • self -a DIR: also attach DIR and give Claude access to it (passed to claude as --add-dir=DIR). Repeat it for more directories. The directory Claude starts in stays the primary one: memory and sessions are filed under it.
  • -C and -a can be given in any order and combined; they end at -- or at the first argument that isn't one of them, and the rest goes to claude.
  • self help: show kelder's own usage.
  • self version: show kelder's version.
  • self setup: create and provision the machine; safe to re-run, it updates packages, config and testvm on an existing machine.
  • self smoketest: test the installed smolvm in a throwaway machine (see Testing a smolvm upgrade).

Without self, every argument goes to claude. To give claude a prompt starting with "self", use kelder -- self ....

Everything else is passed unchanged to claude in the guest, so -p, --resume, --continue, --model and the rest are Claude Code's own options (see kelder --help, which shows claude --help).

A project can have a .kelder.toml in the directory Claude starts in:

vm = "homelab"
packages = [
    "ansible-lint",
    "zfsutils-linux",
]
memory = "homelab"
  • vm: the smolvm machine this project runs in, instead of kelder. Projects with different machines can have sessions open at the same time. Each machine is set up once, with kelder self setup run from the project.
  • packages: extra Debian packages kelder self setup, run from the project, installs in that machine. Only setup installs them: after adding one, run setup again. A session in a machine that lacks any of them says so and starts anyway. Projects that share a machine each add their own; a package taken off the list stays installed.
  • memory: the folder Claude's memory for this project is kept in, memory/<name> in the state directory. Without it Claude Code files memory under the project's path, so it is left behind when the directory moves. Projects that give the same name share one memory. It reaches Claude as --settings with autoMemoryDirectory; session transcripts are still filed under the project's path. Claude takes only one --settings, so a session given one of your own is refused in a project with this key.

Every key is optional. Only the directory Claude starts in is checked: a file in a directory above it, or in one added with -a, is ignored.

These environment variables set by the host also change how it behaves:

  • VM=<name>: the smolvm machine to use (default kelder), overriding the project's .kelder.toml; also read by kelder self setup.
  • CLAUDE_STATE=<dir>: where Claude's state lives on the host (default ~/.local/share/kelder/claude).
  • IMAGE=<image>: base image for kelder self setup (default debian).
  • NO_UPDATE=1: skip the weekly package update (below) for this run.
  • DRY_RUN=1: print every smolvm call instead of running it.

One machine serves every project. kelder starts it if needed and attaches each directory to it (smolvm machine mount add) at the same path it has on the host, and detaches it when the last session using it exits. Only one set of directories is attached at a time: a session for a different set is refused while another is open, since mounts are visible machine-wide (give the project its own machine in .kelder.toml, or use VM=<name>). A session that crashes leaves its directories attached until the next run cleans them up.

The session that boots the machine also keeps it up to date: if the guest was last updated more than a week ago, it upgrades the packages, uv and Claude Code before starting Claude (kelder: updating machine 'kelder' ...), which can take a minute. A failed update is reported and the session starts anyway. kelder self setup does the same update whenever it runs.

When the last session exits, kelder stops the machine, so anything left running in it (testvm VMs, containers) stops too. The next session boots it again.

Claude's state (login, settings, history, memory) is kept on the host in ~/.local/share/kelder/claude (override with CLAUDE_STATE), mounted at /var/lib/kelder in the machine, with CLAUDE_CONFIG_DIR pointing there. The machine itself is disposable: delete it and run kelder self setup to rebuild, and nothing is lost. Changing IMAGE works the same way.

Git in the machine does not see your global gitignore. Put the patterns you want ignored there in a gitignore file in the state directory (~/.local/share/kelder/claude/gitignore); sessions point git's core.excludesFile at it when it exists.

Sessions start with ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN unset: either would outrank the stored login and bill the Console instead of the subscription.

Arguments go straight to claude, so sessions resume as usual. When Claude exits it suggests claude --resume <id>; run kelder --resume <id> instead, from the same directory (sessions are filed by the primary directory, which matches the host path). kelder --continue and a bare kelder --resume (to pick from a list) work too. Plain claude on the host won't find these sessions, because they live in the kelder state directory, not ~/.claude.

The guest has uv, make and shellcheck for running a project's own checks. The attached directory is shared with the host, whose .venv points at the host's Python, so sessions set UV_PROJECT_ENVIRONMENT to .venv- followed by the machine's name (.venv-kelder in the default machine): uv run in the guest builds and uses that environment in each project and leaves .venv to the host. Each machine gets its own.

In the guest:

testvm run -- 'apt-get update && apt-get install -y nginx'   # fresh VM, destroyed after
testvm up web -p 8080:80 && testvm ssh web                   # keep one around
testvm cp ./build web:/opt/ && testvm down web
podman run --rm docker.io/library/debian:trixie ...          # use full image names

Testing a smolvm upgrade

Exit every kelder session so kelder is stopped, upgrade smolvm, then run kelder self smoketest from a project directory. It creates a throwaway kelder-test machine (VM=<name> picks another name), runs the guest's smoketest in it with the current directory attached, checks the smolvm behaviour relied on (see below) from the host, and deletes the machine if everything passed. FAIL means the upgrade broke something kelder needs; KNOWN is a smolvm bug the guest config works around; CHANGED means that bug is gone and its workaround may be removable.

A machine that fails is kept for inspection. If kelder itself stops starting after an upgrade, keep it too and create the replacement under another name.

Development

uv run pytest         # the tests
uv run ruff check     # lint
uv run ty check       # type check

The tests need neither smolvm nor a network. The unit tests cover argument parsing and the attachment bookkeeping. The rest run kelder against tests/fake_smolvm.py, a stand-in selected with SMOLVM_BIN that records each call and runs exec commands locally with a fake claude; they check the smolvm calls made and the environment claude would get. They are plain unittest tests, so PYTHONPATH=src python3 -m unittest discover -s tests runs them without uv.

Releasing

With X.Y.Z as the new version, from an up-to-date main:

uv version X.Y.Z
uv run git-cliff --unreleased --tag vX.Y.Z --prepend CHANGELOG.md
git commit -am "chore(release): bump version to X.Y.Z"
git tag -a vX.Y.Z -m "kelder X.Y.Z"
git push origin main vX.Y.Z
  • uv version sets the version in pyproject.toml and uv.lock. Choose the number by hand: while the version is 0.0.x anything may change in a patch release, from 0.1.0 a minor bump means a breaking change, and from 1.0 the project follows semantic versioning.
  • git-cliff adds one section to CHANGELOG.md for the commits since the last tag, under the header, and leaves the earlier sections as they are. Only feat, fix, refactor and perf commits are listed (see cliff.toml), so the release commit itself never appears.
  • Pushing the tag starts the Release workflow, which fails unless the tag is the version in pyproject.toml prefixed with v, then builds the distributions and publishes them to PyPI.

Quirks found while setting this up

Nested VMs must boot with UEFI. Under smolvm's nested KVM (AMD host), a cloud image booted through BIOS GRUB resets the moment GRUB jumps into the kernel. The same kernel boots fine when QEMU loads it directly, and the image boots fine with OVMF. testvm always uses OVMF, so ovmf is a required package.

UDP inside containers. The guest has no real NIC: libkrun's TSI (tsi_hijack) proxies every socket to the host. Inside a container network namespace, a connected UDP socket can send only one datagram; later sends fail with EINVAL. Unconnected sendto works, and the guest's own namespace is unaffected. glibc sends DNS A and AAAA queries on one connected socket, so container DNS broke (apt: "Temporary failure resolving"). The single-request-reopen resolver option fixes DNS. Other UDP-heavy workloads in containers (QUIC, statsd, syslog) may need --network host. This is a libkrun bug, still present in smolvm 1.35.0, worth reporting upstream.

smolvm behaviour relied on (checked against the v1.34.4 source): machine status exits 0 for a running or stopped machine and fails for an unknown one (an unreadable state database is also reported as not found); machine start on a running machine prints "already running" and succeeds, and fails for a paused one; machine exec takes -i and -t as separate flags.

License

Copyright (C) 2026 Adam Mercer. kelder is free software, licensed under the GNU General Public License, version 3 or (at your option) any later version. See LICENSE.

Metadata

Release files for kelder 0.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kelder 0.0.3
File Size Uploaded Provenance Actions
kelder-0.0.3.tar.gz 43.0 kB With provenance Details for kelder-0.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kelder 0.0.3
File Interpreter ABI Platform Actions
kelder-0.0.3-py3-none-any.whl Python 3 none any Details for kelder-0.0.3-py3-none-any.whl

Total release size: 86.7 kB

Release files / kelder-0.0.3.tar.gz

Download URL kelder-0.0.3.tar.gz
Size 43.0 kB
Tags Source
SHA-256 checksum
How to use checksums
93950526cf6d90fb56df9be37a450d158ca540a92327d3109c5c010e7d17d022
BLAKE2b-256 checksum
How to use checksums
587e3f87a36f6e695452c06770c2634810230c4570ace73403ed7f8fc39ac9e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / kelder-0.0.3-py3-none-any.whl

Download URL kelder-0.0.3-py3-none-any.whl
Size 43.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6335feebb03a4bdb20408f116de8e1f7a447b925e867d153644f1ce425fa6e10
BLAKE2b-256 checksum
How to use checksums
4d3910419dacf2d59e8b2b2193fa3ee5686901b50d9105847b51458e5ed53ccd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for kelder 0.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kelder-0.0.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page