This section demonstrates the current v3 workflow:
- Bootstrap host runtime once.
- Declare desired state in
/etc/cellman/*.lua.
- Preview drift with
cellman apply --dry-run --all.
- Converge runtime with
cellman apply --all.
1. Bootstrap Host Runtime
Prepare runtime directories, base sets, and baseline configuration:
doas cellman system bootstrap
Create one volume, one cell, and one apply document in /etc/cellman.
/etc/cellman/01-volume-demo-data.lua
volume("demo-data", {
mode = "0755",
})
/etc/cellman/02-cell-demo-web.lua
cell("demo-web", {
autostart = true,
create = {
profile = "medium",
reserved_ports = "8080",
},
supervise = {
cmd = "/usr/libexec/httpd -I 8080 -X -f -s /var/www/demo-web",
},
mounts = {
volume("demo-data", { target = "/var/www/demo-web", mode = "rw" }),
},
healthcheck = "test -f /var/www/demo-web/index.html",
})
/etc/cellman/03-apply-demo-web.lua
apply("demo-web", {
dir("/var/www/demo-web", { mode = "0755" }),
file("/var/www/demo-web/index.html", "<html><body>Hello from Cells</body></html>\n", {
mode = "0644",
}),
})
3. Preview Convergence
Run a dry run first. Exit code 2 means drift was detected, which is expected
after new or changed declarations.
cellman apply --dry-run --all
4. Apply Desired State
Converge volumes and cells, execute apply actions, and start the supervised
service according to desired state.
5. Verify Read Views
Use compact/merged views to confirm intent and runtime alignment:
cellman cell list --view compact
cellman cell show demo-web --view merged
cellman volume list --view merged
For scripting, use explicit fields and TSV:
cellman cell list --view runtime -T -H -o name,state,running,cid,procs,cpu1s,cpu10s,memory,age
6. Access the Cell and Metrics
Open a shell in the running cell:
doas cellman cell shell demo-web
Export Prometheus-compatible runtime metrics:
Next Steps
- See
cellman(8) for command-level operations
- See
cellman-spec(5) for the full DSL/action reference
- Use
cellui for interactive lifecycle and backup operations on the same backend
