An autonomous backup agent you deploy on a Debian VM in one command. It runs a reliable deterministic core out of the box, and gets smart when you connect your existing coding-agent subscription — with no API key.
Architecture
+------------------+ +------------------+ +------------------+
| Producer | --> | SQLite Queue | --> | OODA Loop |
| (cron / CLI) | | (tasks + deps) | | (Executor) |
+------------------+ +------------------+ +--------+---------+
|
+----------------------------+
|
+---------v----------+ +----------v---------+
| Deterministic | | LLM reasoning |
| backup handlers | | (optional CLI) |
+---------+----------+ +----------+---------+
| |
+---------v----------+ +----------v---------+
| Dead-letter + | | Retry / replay |
| prune / verify | | idempotency |
+--------------------+ +--------------------+
- Producer : cron, CLI (
agent.py enqueue), or external API - Queue : local SQLite, zero-config, zero-deps
- OODA Loop : observe, orient, decide, act
- Executor : deterministic handlers by default, LLM reasoning when a CLI is connected
- Retry : exponential backoff 10s -> 60s -> 600s
- Dead Letter : failed tasks kept, replayable
One-shot install (Debian/Ubuntu)
unzip agent-backup-v1.zip && cd agent-backup-v1
sudo bash install.sh # system deps + venv + systemd service (enabled)
The agent starts as a systemd service (agent-backup-v1), survives reboots, and
restarts on failure. Logs: journalctl -u agent-backup-v1 -f.
No root / no systemd?
bash install.sh --no-servicesets up the venv, then runvenv/bin/python agent.py run.
Connect your LLM (optional, no API key)
install.sh auto-detects the first CLI it finds. Install & log in to one:
| CLI | Install | Connect |
|---|---|---|
| Claude Code | npm i -g @anthropic-ai/claude-code |
run claude, /login |
| Kimi Code | see platform.moonshot.ai | kimi-code |
| Codex | npm i -g @openai/codex |
codex login |
Force a specific one with PACK_LLM=claude|kimi|codex. If none is connected, the
agent still runs.
LLM vs deterministic (honest by design)
| Capability | Without an LLM CLI | With an LLM CLI connected |
|---|---|---|
| Queue, priorities, scheduling | deterministic | deterministic |
| Retry + exponential backoff | deterministic | deterministic |
| Dead-letter + replay | deterministic | deterministic |
| Dependencies (block on failed dep) | deterministic | deterministic |
| Idempotency (at-most-once key) | deterministic | deterministic |
| Task execution / reasoning | built-in backup handlers | the LLM runs the Executor prompt (PROMPTS.md) |
If a CLI is installed but not logged in, the agent logs a warning and falls back to the deterministic handler for that task.
Quick commands
python agent.py status
python agent.py enqueue --type backup_file --payload '{"source":"/etc/hosts","dest_dir":"/backups"}'
python agent.py enqueue --type prune_backups --payload '{"directory":"/backups","retention_days":30}'
python agent.py run --once
python agent.py run --deterministic
python agent.py replay --task t-ab12cd34
bash smoke_test.sh
Contents
| File | Purpose |
|---|---|
agent.py |
Runnable backup agent — SQLite queue, retry, dead-letter, OODA, BYO-LLM wiring |
llm_adapter.py |
BYO-LLM CLI adapter (claude/kimi/codex), no API key |
install.sh |
One-shot Debian installer (deps + venv + systemd + LLM detection) |
agent-backup-v1.service |
Reference systemd unit (install.sh generates the real one) |
smoke_test.sh / test_agent.py |
Offline test suite (deterministic) |
PROMPTS.md |
Executor prompt loaded by the agent |
CUSTOMIZE.md |
5-minute guide to plug in your own storage/tasks |
OPERATING_COST_ESTIMATE.md |
Provider-agnostic LLM cost estimate |
README.md |
This file |
requirements.txt |
Python deps (stdlib only) |
deploy.sh |
Thin wrapper -> install.sh |
agent-backup-v1.json |
Pack manifest |