Byssus

Byssus creates live filesystem attachments between isolated workspaces.

Byssus is a small Linux daemon that gives a group of isolated workspaces — for example, one container per project — a live view of each other's directories, read-only by default. Group membership is declared by creating or deleting empty files; the daemon turns that into bind mounts, and mount propagation carries them into already-running containers without restarts.

Status: early. Byssus is a young project. The daemon and CLI are functional and tested, but it has not seen wide deployment, and configuration and behavior may change before 1.0. See docs/TODO.md for remaining work and SECURITY.md for reporting issues.

How it works

touch /srv/example/membership/research/libcurl
        │
        ▼
byssusd (inotify) ──► validates the name ──► read-only bind mount of
                                             /srv/example/projects/libcurl/workspace
                                             at /srv/example/groups/research/view/libcurl
        │
        ▼
containers that mount …/research/view with rslave propagation
see /group/libcurl immediately

Removing the file removes the mount.

Key properties:

• No copies or sync — consumers read the source directory itself.
• Read-only, nosuid, nodev, noexec views, applied atomically before a mount becomes visible.
• Confined path resolution — every path is resolved beneath trusted root directories with openat2(RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS).
• Never touches mounts it did not create — ownership is verified by kernel mount identity.
• Least privilege — runs as an unprivileged user holding only CAP_SYS_ADMIN, with no ability to bypass file permissions.
• Nested mounts are never exposed from inside a source directory.
• Mounts survive daemon restarts; the daemon reconciles on startup.

Requirements

• Linux 5.12 or newer
• Rust 1.85 or newer to build

Binaries

Binary	Purpose	Privileges
byssusd	Daemon: watches membership directories and reconciles mounts	CAP_SYS_ADMIN
byssus	CLI: status, dry-run, reconcile, version	none, except reconcile

Configuration example

# /etc/byssus/byssus.toml
[daemon]
user = "byssus"

[groups.research]
source_root = "/srv/example/projects"
source      = "{name}/workspace"
target_root = "/srv/example/groups/research/view"
target      = "{name}"
membership  = "/srv/example/membership/research"

For groups your application creates at runtime, a group set defines them once: each directory beneath membership_root (here <org>/<group>) is a group, so creating a group is mkdir, with no configuration change or root.

[group_sets.projects]
membership_root = "/srv/example/membership/projects"
source_root     = "/srv/example/orgs"
source          = "{group}/projects/{name}/workspace"
target_root     = "/srv/example/orgs"
target          = "{group}/groups/{subgroup}/view/{name}"

See INTEGRATION.md.

Install

Each release provides .deb and .rpm packages and static binary archives for x86_64 and aarch64, with checksums and build provenance attestations:

sudo apt install ./byssus_<version>-1_amd64.deb     # Debian, Ubuntu
sudo dnf install ./byssus-<version>-1.x86_64.rpm    # Fedora, RHEL

Packages install the binaries, systemd unit and service user but do not start the daemon. Then set up source directories and group configuration, confirm the target roots are on a shared mount (the default on systemd hosts), check with sudo byssus dry-run, and start with sudo systemctl enable --now byssusd — see the installation and operations guide.

To build from source instead (Rust 1.85+), for example static binaries from crates.io:

rustup target add x86_64-unknown-linux-musl
cargo install --locked --target x86_64-unknown-linux-musl byssus
sudo install -m 0755 ~/.cargo/bin/byssusd ~/.cargo/bin/byssus /usr/local/bin/

Try it

On Linux 5.12+, without root:

scripts/playground.sh

This opens a shell in a throwaway namespace with a sample deployment, a simulated container and byssusd running. Type help for things to try.

Documentation

• Installation and operations guide — install, configure, run, troubleshoot
• Integration guide — containers and managing membership from an application
• Reference — configuration, naming rules, CLI, log format
• Design and security contract and design decisions
• Milestones and TODO · Releasing
• Security policy · Contributing

Background

Byssus was built for ElasticLoom, where it lets research projects read each other's findings. It has no dependency on ElasticLoom and is intended to be useful to any system that needs live, read-only directory sharing across container boundaries.

The name comes from the byssus threads mussels use to attach themselves to surfaces.

License

Licensed under the Apache License, Version 2.0.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you shall be licensed as above, without any additional terms or conditions.