loom

loom is an open-source runtime primitive service for near-instant container state branching.

It provides first-class APIs for:

• snapshot
• fork
• clone
• resume
• lineage, pin/unpin, and operation tracking

This project intentionally keeps one execution architecture end-to-end:

• command contract is strict argv JSON
• no implicit shell wrapping
• snapshot/fork/clone filesystem materialization uses one shared copy primitive
• operation state is persisted in SQLite

Scope

loom is runtime-primitive focused. It does not include multi-tenant auth/RBAC/user scoping.

API Surface

• POST /api/containers
• GET /api/containers
• GET /api/containers/:id
• DELETE /api/containers/:id
• POST /api/containers/:id/kill
• POST /api/containers/:id/snapshot
• POST /api/containers/:id/fork
• POST /api/containers/:id/resume
• GET /api/snapshots
• GET /api/snapshots/:id
• DELETE /api/snapshots/:id
• GET /api/snapshots/:id/lineage
• POST /api/snapshots/:id/pin
• POST /api/snapshots/:id/unpin
• POST /api/snapshots/:id/clone
• GET /api/operations/:id
• GET /health

Quick Start

cargo run

By default:

• HTTP: 127.0.0.1:18090
• data dir: ./data
• SQLite DB: ./data/loom.db

Override:

LOOM_HTTP_ADDR=127.0.0.1:18100 LOOM_DATA_DIR=/tmp/loom-data cargo run

Example

Create a fixture rootfs and register a container:

mkdir -p /tmp/loom-fixture/rootfs
echo hello > /tmp/loom-fixture/rootfs/hello.txt

curl -s -X POST http://127.0.0.1:18090/api/containers \
  -H 'content-type: application/json' \
  -d '{
    "name":"demo",
    "rootfs_path":"/tmp/loom-fixture/rootfs",
    "command":["/bin/sh","-lc","sleep 60"],
    "start_immediately":true
  }' | jq

Snapshot and clone:

curl -s -X POST http://127.0.0.1:18090/api/containers/<container_id>/snapshot \
  -H 'content-type: application/json' \
  -d '{"consistency_mode":"crash-consistent"}' | jq

curl -s -X POST http://127.0.0.1:18090/api/snapshots/<snapshot_id>/clone \
  -H 'content-type: application/json' \
  -d '{"resume_policy":"immediate"}' | jq

Testing

Standard

cargo fmt
cargo check

End-to-end smoke

tests/e2e_loom.sh

Fozzy

fozzy run tests/fozzy/loom.guard.fozzy.json --proc-backend host --json
fozzy run tests/fozzy/loom.e2e.fozzy.json --proc-backend host --json

The Fozzy scenarios are designed to catch refactor regressions and extraction drift.

License

Apache-2.0