# Platform Requirements for Running Claude-Obsidian Mutations

> Discover the essential platform requirements for running Claude-Obsidian mutations. Learn about POSIX compatibility, Python 3.11+, Bash, and filesystem needs for smooth operation.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Claude-Obsidian mutations require a POSIX-compatible host—Linux, macOS, or Windows Subsystem for Linux (WSL)—running Python 3.11 or newer with Bash, and a filesystem that provides stable inode and device identifiers.**

Claude-Obsidian is an open-source vault management system developed by AgriciDaniel that enforces strict platform constraints to guarantee safe mutation operations. Commands such as `transaction apply`, `init`, `adopt`, `migrate`, and `capture apply` rely on kernel-level directory-confinement primitives to prevent symlink redirection attacks and ensure all writes remain anchored to the vault root.

## Operating System and Platform Support

Claude-Obsidian supports **Linux**, **macOS**, and **Windows Subsystem for Linux (WSL)** for mutation operations. Native Windows environments cannot perform vault writes and will abort immediately with the error code `UNSUPPORTED_PLATFORM`. According to [`docs/windows-wsl.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/windows-wsl.md), this restriction exists because native Windows lacks the POSIX directory-descriptor capabilities required for secure write confinement.

## Software Prerequisites

### Python 3.11 or Newer

The codebase requires **Python 3.11** or later, as specified in [`docs/install-guide.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/install-guide.md). Earlier Python versions lack the specific `os` module interfaces and type-hinting support utilized by the transaction engine.

### Bash Shell

**Bash** is mandatory for executing installer scripts and running the test suites. While the core Python library can run within any shell, the automation scripts and development workflows assume a Bash environment.

## Filesystem and Security Constraints

To prevent concurrent symlink attacks and directory replacement vulnerabilities, Claude-Obsidian enforces two critical filesystem requirements.

### Stable Inode and Device Identity

The vault must reside on a filesystem that supplies **stable inode and device IDs**. Compatible filesystems include **NTFS** (on Windows via WSL) and **ext4** (on Linux). Filesystems such as FAT, exFAT, or network shares that lack stable identity guarantees are rejected with the error `UNSAFE_VAULT_IDENTITY`. This validation ensures the transaction engine can reliably track file identity across mutation operations, as documented in [`docs/windows-wsl.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/windows-wsl.md).

### POSIX Directory-Descriptor Confinement

The most stringent requirement is **POSIX-style directory-descriptor confinement**. The host must expose `os.open`, `os.mkdir`, `os.stat`, `os.unlink`, `os.rmdir`, and `os.rename` with `O_DIRECTORY`, `O_NOFOLLOW`, and `dir_fd` capabilities. These flags enable the library to operate within a directory file descriptor, ensuring that every write stays anchored to the vault root and cannot be redirected by concurrent symlink manipulation.

In [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), the function `_require_lock_dirfd_support` validates these capabilities at runtime, while `_require_write_platform` enforces the broader platform constraints. If the host kernel lacks these primitives, the library raises `TransactionValidationError` before any disk mutation occurs.

## Runtime Platform Validation

Before executing mutations, invoke the platform checks explicitly or rely on the automatic validation within transaction initialization:

```python
from claude_obsidian.transaction import _require_write_platform, TransactionValidationError

try:
    _require_write_platform()  # Raises if dirfd confinement is unavailable

except TransactionValidationError as e:
    print(f"Cannot mutate vault: {e.code} – {e}")

```

For WSL environments, execute mutations within the Linux shell:

```bash
wsl
python3 scripts/claude-obsidian.py capture apply --vault my_vault \
    --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    --operation-id capture-reviewed \
    --approved-plan-sha256 <sha256> \
    --apply

```

## Optional Development Dependencies

**Git** is required only for development workflows, release builds, or explicit checkpoint operations. It is not a runtime dependency for vault mutations themselves, as noted in [`docs/install-guide.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/install-guide.md).

## Summary

- **Operating System**: Linux, macOS, or WSL only; native Windows is unsupported for writes and returns `UNSUPPORTED_PLATFORM`.
- **Python**: Version 3.11 or newer is mandatory.
- **Shell**: Bash is required for installer and test scripts.
- **Filesystem**: Use NTFS, ext4, or similar with stable inode/device IDs; avoid FAT, exFAT, and unstable network shares to prevent `UNSAFE_VAULT_IDENTITY` errors.
- **Kernel Support**: The host must provide directory-descriptor operations with `O_DIRECTORY`, `O_NOFOLLOW`, and `dir_fd` support, validated by `_require_lock_dirfd_support` in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py).
- **Version Control**: Git is optional and only needed for development or checkpoint features.

## Frequently Asked Questions

### Can I run Claude-Obsidian mutations on native Windows without WSL?

No. Native Windows lacks the POSIX directory-descriptor primitives required for secure mutation confinement. Attempting to execute write operations on native Windows triggers a `TransactionValidationError` with code `UNSUPPORTED_PLATFORM`. You must use Windows Subsystem for Linux (WSL) to perform any vault modifications on Windows hardware.

### Why does Claude-Obsidian reject FAT and exFAT filesystems?

These filesystems do not provide stable inode and device identifiers, which the transaction engine requires to verify file identity across operations. Without stable identifiers, the system cannot guarantee that a file has not been replaced by a symlink or alternate directory entry between validation and write. Consequently, vaults on FAT or exFAT raise `UNSAFE_VAULT_IDENTITY` errors.

### Is Git required for running Claude-Obsidian mutations?

No. Git is only necessary for development workflows, building releases, or creating explicit checkpoints. The core mutation engine—`transaction apply`, `capture apply`, and related commands—operates independently of Git, as confirmed by the installation documentation in [`docs/install-guide.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/install-guide.md).

### What specific kernel capabilities does `_require_lock_dirfd_support` check?

The function verifies that the Python `os` module supports `open`, `mkdir`, `stat`, `unlink`, `rmdir`, and `rename` operations using the `dir_fd` parameter with `O_DIRECTORY` and `O_NOFOLLOW` flags. These capabilities enable **directory-descriptor confinement**, ensuring all filesystem operations remain scoped to the vault root and are immune to path traversal or symlink attacks during concurrent mutations.