Deploy small stateful apps to a single Linux box — a Raspberry Pi, a mini PC, a cheap VM — as one portable file that carries the code and its live database together.
BUILDING WITH CLAUDE
Normally your code and your production data live in different worlds. Code flows one way, laptop to server. Data accumulates on the server, and you guard it and never pull it back. So when you want to test a change against real data, you invent a ritual: seed scripts, anonymised dumps, a staging database that drifted out of date months ago.
For a small app — a personal tool, a family thing, a side project with one SQLite file — that ritual costs more than the app does.
conclave inverts it. The unit you move around is a bundle: the app's code and its live state, in a single file that round-trips.
edit on laptop → load onto server (it runs) → eject (data comes back)
↑ ↓
└──────────────── open on laptop ←───────────────────┘
Because the data comes back with the code, production data simply is your dev fixture. Always current, no seeding ceremony. You test a migration once, against exactly the rows it will hit.
A .conclave file is a system-container export containing:
- the container's root filesystem — sealed; you don't edit this
/app— a git repo with your code. The commit history travels inside the bundle, so a bundle handed to you is a repo you cangit log/data— the live state, typically one SQLite file/etc/conclave/manifest.yaml— a short manifest declaring the port to expose, resource limits, and a hook to run before capture
Two ways of remembering history, one physical artifact: git for code, retained bundles for state.
server (on the Linux box)
conclave server run the runner daemon
client (on your laptop)
conclave connect <host> pair with a server
conclave ls list apps on the paired server
conclave load <bundle> import and start a bundle on the server
conclave eject <name> capture an app to a local bundle, then remove it
conclave backup <name> capture an app, but keep it serving
conclave open <bundle> explode a bundle into ./<name>/ for editing
conclave pack <name> splice ./<name>/ back into its bundle
One binary does both roles, so it's one download on each machine.
open and pack work directly on the tarball, which means your laptop never
needs a container runtime installed — only the server does.
A few rules the implementation is held to, because they're what make this safe to point at real data:
- Ejecting never destroys the only copy. Capture, retain the last few bundles on the host, stream to the laptop, and only then remove the instance.
- One editable copy at a time. If it's ejected to your laptop, the server isn't still serving it.
- Capture is stop-then-export, with a hook that runs first so a database can flush cleanly. No live checkpointing.
- State lives strictly under
/data, code strictly under/app.
Early — not usable yet. The groundwork is done and the core premise is proven end to end by hand, but the commands above are still stubs.
| Area | State |
|---|---|
| Manifest parsing, CLI scaffold | done |
| Development host (Incus in a local VM) | done |
| Round-trip validated manually | done — code and state survive export → delete → import, and a laptop-side edit plus a migration redeploy cleanly |
| Export format recorded + test fixture | done |
| Runner daemon, client commands | not started |
If you're reading this hoping to deploy something today, come back later.
The design brief, build plan, and host runbooks are kept outside the repository while the shape of things is still moving.
- A Linux box running Incus — a Pi 5, an x86 mini PC, or a small cloud VM all work. Currently developed against 7.2.
- Go 1.22+ to build.
- Your laptop needs neither Incus nor Linux; macOS is fine.
Bundles are architecture-locked — an arm64 bundle won't start on an amd64 host — so pick one architecture and stay on it.
cmd/conclave/ the single binary, subcommand dispatch
internal/manifest/ conclave.yaml parsing and validation
internal/bundle/ bundle surgery (open/pack) — today, just its test fixture
conclave.yaml the canonical manifest schema, annotated
The bundle fixture under internal/bundle/testdata/ is worth a look if you're
curious about the format: it mirrors a real container export structurally —
including the symlink, hardlink and odd ownership that break naive archive
surgery — while being small enough to read. make-sample.py regenerates it
byte-identically.
Sandstorm grains, balena, and Fly Machines all circle this idea. conclave is the deliberately small version: one box, one binary, no orchestration, no separate state store. The tight coupling between code and state is the point, not an oversight.
Apache-2.0. See LICENSE.