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/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 inDIRinstead of the current directory.self -a DIR: also attachDIRand give Claude access to it (passed toclaudeas--add-dir=DIR). Repeat it for more directories. The directory Claude starts in stays the primary one: memory and sessions are filed under it.-Cand-acan 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 toclaude.self help: showkelder's own usage.self version: showkelder's version.self setup: create and provision the machine; safe to re-run, it updates packages, config andtestvmon 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).
These environment variables set by the host also change how it behaves:
VM=<name>: the smolvm machine to use (defaultsmol); also read bykelder self setup.CLAUDE_STATE=<dir>: where Claude's state lives on the host (default~/.local/share/kelder/claude).IMAGE=<image>: base image forkelder self setup(defaultdebian).NO_UPDATE=1: skip the weekly package update (below) for this run.DRY_RUN=1: print everysmolvmcall 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 (use
VM=<name> for a second machine). 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 'smol' ...), 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.
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=.venv-smol:
uv run in the guest builds and uses .venv-smol in each project and leaves
.venv to the host.
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 smol is stopped, upgrade smolvm, then run
kelder self smoketest from a project directory. It creates a throwaway
smol-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 smol 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
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.
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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kelder-0.0.1.tar.gz | 38.4 kB | With provenance | Details for kelder-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kelder-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for kelder-0.0.1-py3-none-any.whl |
Total release size: 78.1 kB
Release files / kelder-0.0.1.tar.gz
| Download URL | kelder-0.0.1.tar.gz |
|---|---|
| Size | 38.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
50e2b0c4196c910a5f59201a5c40981e32449f7d88cc436daf0c78472d5fd3c7
|
|
BLAKE2b-256 checksum How to use checksums |
a5baf2a537ad32a6f6b31131cb5b50a672228ee36bfd3259e2b492a5b4eb38c8
|
| 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 16, 2026.
Transparency logRelease files / kelder-0.0.1-py3-none-any.whl
| Download URL | kelder-0.0.1-py3-none-any.whl |
|---|---|
| Size | 39.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4bcb3d78982710e897048c0effe8bdf0a53a9917184fdeae0a3adf82fc963cdb
|
|
BLAKE2b-256 checksum How to use checksums |
db935642f175d47d8bca21b3fdf5946c32f4915df60fcf1186ba11139df81db1
|
| 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 16, 2026.
Transparency logSecurity for kelder 0.0.1
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.
Attestation for kelder-0.0.1.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 16, 2026.
Transparency logA 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.