AvyOS Filesystem Hierarchy

AvyOS uses a redesigned filesystem hierarchy that separates immutable system files from mutable user data.

/
├── avyos/          # Immutable system root (squashfs)
│   ├── cmd/        # System commands
│   ├── config/     # Default configurations
│   ├── data/       # Static data files
│   ├── apps/       # User applications
│   └── services/   # System services
├── config/         # Mutable config overrides
├── users/          # User home directories
├── cache/          # Runtime and kernel filesystems
│   ├── kernel/     # Kernel-managed directories
│   └── runtime/    # Runtime state (like /run)
├── linux/          # Linux compatibility layer
└── volumes/        # User data volumes

The /avyos/ directory contains the immutable system image, mounted as read-only squashfs.

/avyos/cmd/ — Commands

System commands and utilities. Mounted with nosuid, nodev.

/avyos/config/ — Default Configuration

Default system configuration files. Mounted with noexec, nodev, nosuid. Only text files allowed.

/avyos/config/
├── init.conf           # Init system configuration
├── services/           # Service definitions
│   ├── login.service
│   └── sutra.service
└── security/           # Security configurations
    ├── auth.conf
    ├── identity.conf
    └── capabilities.conf

/avyos/data/ — Static Data

Static data files like icons, fonts, and themes. Mounted with noexec, nodev, nosuid.

/avyos/data/
├── icons/
├── fonts/
└── themes/

/avyos/apps/ — Applications

User-facing applications. Run inside containers with capability restrictions.

/avyos/services/ — System Services

Privileged system services that run with elevated capabilities.

/config/ — Configuration Overrides

Mutable configuration that overrides /avyos/config/. When a config file exists in both locations, /config/ takes precedence.

Mounted with noexec, nodev, nosuid.

/config/
├── .firstboot-done     # Marker file after setup
├── init.conf           # Custom init config
└── security/
    └── identity.conf   # User identity database

/users/ — Home Directories

User home directories. Each user gets a directory at /users/<username>/.

/users/
└── alice/
    ├── .profile
    └── documents/

/cache/ — Runtime State

Runtime and temporary filesystems.

/cache/kernel/ — Kernel Filesystems

Kernel-managed virtual filesystems:

/cache/runtime/ — Runtime State

Runtime state directory (equivalent to /run on traditional Linux).

/cache/runtime/
├── sutra.sock      # IPC socket
└── services/       # Service state

For running traditional Linux applications, AvyOS provides containerized Linux environments:

/linux/
├── alpine/         # Alpine Linux container
├── debian/         # Debian container
└── fedora/         # Fedora container

Each container runs in isolation using a bwrap-like sandbox with:

• Namespace isolation (mount, pid, network)
• Capability restrictions
• Filesystem overlays

1. Immutability — System files cannot be modified at runtime
2. Separation — Clear boundaries between system, config, and user data
3. Security — Mount options prevent execution where not needed
4. Simplicity — Flat, predictable hierarchy
5. Atomicity — System updates replace the entire /avyos/ image