Skip to content

Mount Management

← API Documentation

This document describes backend mount management in Nexus.

Nexus supports both static (configured via YAML) and dynamic (added at runtime) backend mounts, allowing you to attach different storage backends to different paths.

Static vs Dynamic Mounts

Static Mounts (YAML Configuration)

Static mounts are defined in your nexus.yaml configuration file and are loaded when the Nexus instance starts. These are ideal for permanent infrastructure like archive storage, shared resources, or multi-cloud setups.

# nexus.yaml
mode: embedded
backend: local
data_dir: ./nexus-local

backends:
  - name: archives
    type: gcs
    mount_point: /archives
    bucket_name: archive-bucket
    readonly: true
    priority: 10

Use static mounts when: - The mount configuration is permanent - All users/applications need access - Configuration is managed through infrastructure-as-code - Server-side setup for remote mode

See Configuration for full YAML configuration details.

Dynamic Mounts (Runtime API)

Dynamic mounts are added programmatically at runtime using the mount management API. These are ideal for user-specific workspaces, temporary storage, or application-specific backends.

⚠️ NOTE: Dynamic mount methods exist in MountManager/PathRouter classes but are not directly exposed as NexusFS methods. Access via nx.mount_manager or nx.router.

Use dynamic mounts when: - Mounts are user-specific or session-based - Applications need to add/remove backends on-the-fly - Multi-tenant scenarios with isolated storage per tenant - Temporary mounts that should not persist in configuration

Dynamic Mount API

add_mount()

Add a dynamic backend mount to the filesystem.

def add_mount(
    mount_point: str,
    backend_type: str,
    backend_config: dict,
    priority: int = 0,
    readonly: bool = False
) -> str

Parameters: - mount_point (str): Virtual path where backend is mounted (e.g., "/personal/alice") - backend_type (str): Backend type - "local", "gcs", "google_drive", etc. - backend_config (dict): Backend-specific configuration - priority (int): Mount priority - higher values take precedence (default: 0) - readonly (bool): Whether mount is read-only (default: False)

Returns: - str: Mount ID (unique identifier)

Raises: - ValueError: If mount_point already exists or configuration is invalid

Examples:

# Add personal GCS mount for user
mount_id = nx.add_mount(
    mount_point="/personal/alice",
    backend_type="gcs",
    backend_config={
        "bucket": "alice-personal-bucket",
        "project_id": "my-project"
    },
    priority=10
)

# Add local shared mount
mount_id = nx.add_mount(
    mount_point="/shared/team",
    backend_type="local",
    backend_config={
        "data_dir": "/mnt/shared/team-data"
    },
    priority=5
)

# Add read-only archive mount
mount_id = nx.add_mount(
    mount_point="/archive/2024",
    backend_type="gcs",
    backend_config={
        "bucket": "archive-bucket",
        "prefix": "2024/"
    },
    priority=1,
    readonly=True
)

remove_mount()

Remove a backend mount.

def remove_mount(
    mount_point: str
) -> bool

Parameters: - mount_point (str): Virtual path of mount to remove

Returns: - bool: True if mount was removed, False if not found

Examples:

# Remove a mount
success = nx.remove_mount("/personal/alice")
if success:
    print("Mount removed")
else:
    print("Mount not found")

list_mounts()

List all active backend mounts.

def list_mounts() -> list[MountConfig]

Returns: - list[MountConfig]: List of mount configuration objects with fields: - mount_point: Virtual path - backend_type: Backend type - backend_config: Backend configuration (dict) - priority: Mount priority - readonly: Whether read-only - mount_id: Unique mount identifier - created_at: Creation timestamp - owner_user_id: Owner user ID (optional) - tenant_id: Tenant ID (optional)

Examples:

# List all mounts
mounts = nx.list_mounts()
for mount in mounts:
    print(f"{mount.mount_point}: {mount.backend_type} (priority={mount.priority})")

# Find user-specific mounts
user_mounts = [m for m in nx.list_mounts() if m.mount_point.startswith("/personal/alice")]

get_mount_info()

Get information about a specific mount.

def get_mount_info(
    mount_point: str
) -> MountConfig | None

Parameters: - mount_point (str): Virtual path of mount

Returns: - MountConfig | None: Mount configuration or None if not found

Examples:

# Get mount info
mount = nx.get_mount_info("/personal/alice")
if mount:
    print(f"Backend: {mount.backend_type}")
    print(f"Priority: {mount.priority}")
    print(f"Read-only: {mount.readonly}")
else:
    print("Mount not found")

See Also

Next Steps

  1. Configure backends
  2. Add dynamic mounts via nx.mount_manager
  3. Use CLI tools for mount management