Install

LifeboatCache ships as one Python package, lifeboatcache, on PyPI. Installing it into the same Python environment as the engine registers the engine plugins; nothing runs until a server is started with LIFEBOAT_CACHE=1.

What do I need before installing?

Requirement	Value
Python	3.10 or newer
vLLM	0.32.x (`>=0.32.0,<0.33`)
SGLang	0.5.x (`>=0.5.19,<0.6`)
LMCache (only for vLLM’s LMCache mode)	0.5.x (`>=0.5.6,<0.6`)
Disk	a local directory for the KV tier — `~/.lifeboat_cache/kv` by default, 50 GB budget

The package itself depends only on pydantic, pyyaml, numpy and zstandard. It is a pure-Python wheel, so the same file installs on Linux x86-64 and ARM and on macOS. Full matrix: Supported versions.

Which pip command do I run?

Install into the environment that runs the engine — the engine loads the plugin from its own site-packages.

You serve with	Command
vLLM, default native mode (no LMCache)	`pip install lifeboatcache`
vLLM in LMCache mode	`pip install "lifeboatcache[vllm]"` (adds LMCache)
SGLang	`pip install lifeboatcache`
Lifeboat	see Quickstart on Lifeboat — the package is mounted into the container
any engine, with an S3 tier	add the `s3` extra, e.g. `pip install "lifeboatcache[s3]"` (adds `boto3`)

Pin the release in production:

pip install "lifeboatcache==0.1.23"

What gets registered when I install it?

Two engine entry points, loaded automatically by the engines in every process:

Entry point group	Name	What it does
`vllm.general_plugins`	`lifeboat`	registers `LifeboatConnector`; with `LIFEBOAT_CACHE=1` and no `--kv-transfer-config`, wires LifeboatCache into vLLM; fits vLLM’s CPU tier to `/dev/shm`
`sglang.srt.plugins`	`lifeboat`	with `LIFEBOAT_CACHE=1`, enables HiCache with the LifeboatCache storage backend unless the launch chose a backend

And two commands: lifeboat-cache (configuration, status, a shared LMCache server) and lifeboat-controld (the optional fleet controller).

Without LIFEBOAT_CACHE=1 the plugins change nothing, so installing the package on a shared engine environment is safe.

Do I need a configuration file?

No. With no file, LifeboatCache uses built-in defaults:

KV is written to ~/.lifeboat_cache/kv (the local fallback tier, capacity_gb: 50, keeping at least 10 GB free on the disk);
stored KV is compressed with fp8;
the dashboard listens on http://127.0.0.1:9400, Prometheus metrics on port 9402;
eviction is LRU.

To write a starter file you can edit:

lifeboat-cache init --capacity-gb 500 --kv-path /mnt/nvme/lifeboat-kv
# wrote /home/<you>/.lifeboat_cache/lifeboat.yaml

The configuration is resolved in this order: an explicit path or $LIFEBOAT_CACHE_CONFIG → $LIFEBOAT_CACHE_HOME/lifeboat.yaml (default ~/.lifeboat_cache/lifeboat.yaml) → built-in defaults. LIFEBOAT_CACHE_HOME moves everything LifeboatCache writes by default. See the Configuration reference.

How do I verify the install?

pip show lifeboatcache | head -2
# Name: lifeboatcache
# Version: 0.1.23

lifeboat-cache config validate ~/.lifeboat_cache/lifeboat.yaml
# OK: /home/<you>/.lifeboat_cache/lifeboat.yaml is valid (device=auto)

lifeboat-cache config show ~/.lifeboat_cache/lifeboat.yaml --section storage

config validate and config show take the file path as an argument (or read $LIFEBOAT_CACHE_CONFIG). Every key is checked strictly: a typo fails with Extra inputs are not permitted, rather than being ignored.

Then start your engine with LIFEBOAT_CACHE=1 — vLLM, SGLang or Lifeboat.

How do I upgrade or remove it?

pip install -U lifeboatcache      # upgrade; stored KV stays readable across releases
pip uninstall lifeboatcache       # the engines start exactly as before

Stored blocks carry a self-describing header: newer releases read blocks written by older ones, and a block a release cannot read (for example after a downgrade) is treated as a miss and recomputed, not as an error. The KV directory is left in place on uninstall; delete ~/.lifeboat_cache/kv (or your tier paths) to reclaim the space.