openrind-dev
Develop Openrind Shell's OpenShell-supervised PostgreSQL FUSE runtime, compatibility sync runtime, and just-bash library.
SKILL.md.claude/skills/openrind-dev/SKILL.md
GitHubOpenrind Shell Development
Read README.md, ARCHITECTURE.md, BUILD.md, FUSE-DESIGN.md, and the files
being changed before implementation. Keep the primary FUSE, compatibility, and
custom-agent library paths distinct.
Runtime Architecture
flowchart TB
subgraph openshell["Vendored OpenShell patch"]
api["Public --fuse resource"] --> driver["Docker operator gate<br/>and /dev/fuse passthrough"]
driver --> supervisor["Supervisor mount before TSYNC prelude"]
supervisor --> fds["Explicit FUSE and readiness FDs"]
fds --> critical["Critical-child lifecycle<br/>container restart on exit"]
end
subgraph primary["Primary sandbox image"]
init["TypeScript one-shot init<br/>migrations, volume, legacy import"]
fused["Rust openrind-shell-fused<br/>VFS, cache, lease, fencing"]
home["/sandbox/work<br/>native persisted HOME"]
proxy["OpenShell CONNECT proxy<br/>end-to-end PostgreSQL TLS"]
init --> home
home <--> fused
fused --> proxy
end
subgraph compatibility["Compatibility sandbox image"]
disk["Native /sandbox disk"] --> watcher["Node prefix-scoped watcher"]
watcher <--> legacy[("_openeral.workspace_files")]
end
subgraph library["Custom-agent library"]
justbash["createOpenrindShell"] --> workspacefs["WorkspaceFs"]
justbash --> pgfs["read-only PgFs at /db"]
end
critical --> fused
proxy --> normalized[("_openeral.fs_* tables")]
Route a change to exactly one path unless the public contract genuinely spans paths.
Primary FUSE must never start compatibility watchers; sandbox Claude never uses the
custom-agent WorkspaceFs or /db virtual filesystem.
Key Files
The source directories and _openeral database schema retain their historical names
for upgrade compatibility. Public commands and images use openrind-shell.
crates/openeral-fused/src/
main.rs inherited FUSE/readiness fds, critical-process lifecycle
runtime.rs database coordination, state, lease/fence transitions
connect.rs mandatory OpenShell CONNECT + PostgreSQL TLS
store.rs normalized inode/dirent/chunk transactions and fencing
cache.rs bounded coherent dirty cache and durability barriers
fs.rs fuser operation implementation
management.rs same-UID health and flush socket
openeral-js/src/
db/migrations.ts V1-V8 migrations; sole migration owner and rename bridge
db/fuse-init.ts volume preparation, marker, legacy import, lease check
sync.ts compatibility prefix-scoped sync only
shell.ts custom-agent just-bash factory
pg-fs/ read-only /db virtual filesystem
workspace-fs/ custom-agent workspace adapter
sandboxes/openeral/
Dockerfile primary FUSE image source
Dockerfile.compat compatibility image source
setup-fuse.sh one-shot primary initialization
openeral-claude-fuse.sh primary Claude parent + final flush
setup.sh compatibility initialization
openeral-bash.mjs compatibility daemon/watchers
policy.yaml FUSE declaration and egress policy
vendor/openshell/
UPSTREAM source commit/tree provenance
crates/openshell-driver-docker/
crates/openshell-supervisor-process/
crates/openshell-policy/
crates/openshell-server/
Non-Negotiable Boundaries
- OpenShell supervisor performs the mount before its TSYNC seccomp prelude.
- Claude receives no
/dev/fuse, mount syscall, capability, or daemon selection. - TypeScript owns V7 FUSE migration, V8 compatibility bridge, and import. Rust validates but never migrates.
- Primary persistence uses FUSE only. Never start
watchAndSyncfor/sandbox/work. - PostgreSQL uses OpenShell HTTP CONNECT with end-to-end TLS and no direct fallback.
- Lease loss is terminal. A fenced process never reacquires in-process.
- FUSE loop/daemon exit terminates the supervisor/container; remount is impossible.
_openeralremains the storage schema until an explicit data migration exists.- Preserve old executable and environment aliases during the public rename window.
- Ignore artifacts through
.gitignore, never through selective commit omission.
Build And Test
cargo fmt --all --check
cargo test -p openeral-fused
cargo clippy -p openeral-fused --all-targets -- -D warnings
cd openeral-js
pnpm install
pnpm check
Vendored OpenShell patch:
cd vendor/openshell
cargo fmt --all --check
cargo check -p openshell-cli -p openshell-driver-docker \
-p openshell-policy -p openshell-supervisor-process
cargo test -p openshell-policy -p openshell-driver-docker \
-p openshell-supervisor-process -p openshell-cli
The gateway binary needs libz3.so.4 at runtime (libz3-4/libz3-dev, or
LD_LIBRARY_PATH to an extracted copy); see BUILD.md.
Build only the child image; do not rebuild NVIDIA's base image:
docker pull ghcr.io/nvidia/openshell-community/sandboxes/base:latest
docker build --pull=false -f Dockerfile.openrind-shell -t openrind-shell-fuse:local .
docker build --pull=false -f Dockerfile.openrind-shell-compat -t openrind-shell-compat:local .
Real FUSE E2E:
DATABASE_URL='postgresql://...' \
OPENSHELL_GATEWAY_ENDPOINT='http://127.0.0.1:18770' \
OPENRIND_SHELL_FUSE_E2E_IMAGE='openrind-shell-fuse:local' \
tests/fuse/test_openshell_e2e.sh
Without a Supabase URL, use the local TLS fixture in tests/fuse/postgres-fixture/
(compose + gen-certs.sh; see BUILD.md "Local TLS PostgreSQL Fixture") and build the
derived image with --build-arg BASE_IMAGE=openrind-shell-fuse:local, then set
OPENRIND_SHELL_FUSE_E2E_IMAGE=openrind-shell-fuse-localdb:test.
Required FUSE Semantics
- stable inode identity across rename;
- byte-preserving names, symlinks, sparse files, and partial writes;
- open-unlinked lifetime and restart-time orphan cleanup;
- bounded shared dirty state across handles;
fsync/fdatasyncand sync-open durability;- atomic dirty-source rename replacement;
- existing-file
O_TRUNCclose barrier; - synchronous namespace/metadata commits;
- uncertain-commit operation deduplication;
- one-writer advisory lock, lease epoch, and terminal fencing.
Source Pin Discipline
Before rebasing vendor/openshell, verify its UPSTREAM commit and tree, compare a
pristine archive, and review mount ordering, seccomp, ProcessHandle, lifecycle state,
and Docker restart behavior before replaying the patch.