### Install and Run AltMount via CLI

Source: https://github.com/javi11/altmount/blob/main/README.md

Install the AltMount CLI using 'go install' and then run the server with a specified configuration file. Ensure Go is installed and configured in your PATH.

```bash
go install github.com/javi11/altmount@latest
altmount serve --config config.yaml
```

--------------------------------

### Example Backend Configuration

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

An example of the backend configuration file ('config.yaml'). It specifies server port and host, and database path.

```yaml
# Example configuration
server:
  port: 8080
  host: "localhost"

database:
  path: "./altmount.db"
# Add your specific configuration here
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Install frontend dependencies using Bun. This command should be run after navigating to the frontend directory.

```bash
bun i
```

--------------------------------

### Start Local Development Server

Source: https://github.com/javi11/altmount/blob/main/docs/README.md

Starts a local development server for live previewing changes. Changes are reflected without server restarts.

```bash
npm start
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/javi11/altmount/blob/main/docs/README.md

Run this command in the project root to install all necessary npm packages.

```bash
npm install
```

--------------------------------

### Initialize AltMount Configuration and Start Service

Source: https://github.com/javi11/altmount/blob/main/docs/docs/1. intro.md

Create the required metadata directory and launch the containerized service.

```bash
mkdir -p ./config/metadata
docker-compose up -d
```

--------------------------------

### Stremio Addon Integration Example

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/stremio.md

A JavaScript example using stremio-addon-sdk to proxy AltMount stream requests.

```javascript
const { addonBuilder } = require("stremio-addon-sdk");

const ALTMOUNT = "http://altmount.example.com";
const KEY      = "YOUR_DOWNLOAD_KEY"; // sha256(api_key)

const builder = new addonBuilder({
  id: "com.example.my-addon", version: "1.0.0", name: "My Addon",
  resources: ["stream"], types: ["movie", "series"], catalogs: [], idPrefixes: ["tt"],
});

builder.defineStreamHandler(async ({ type, id }) => {
  const res  = await fetch(`${ALTMOUNT}/stremio/${KEY}/stream/${type}/${id}.json`);
  const data = await res.json();
  return { streams: data.streams ?? [] };
});

module.exports = builder.getInterface();
```

--------------------------------

### Install Backend Dependencies

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Install backend dependencies using the 'make tidy' command. This ensures all necessary Go modules are downloaded and managed.

```bash
make tidy
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Start the frontend development server using Bun. This enables hot reloading and typically runs on port 5173.

```bash
bun dev
```

--------------------------------

### Custom NZB Resolution JavaScript Example

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/stremio.md

A JavaScript example demonstrating how to upload an NZB file to AltMount for processing.

```javascript
builder.defineStreamHandler(async ({ type, id }) => {
  // Your addon resolves the NZB however it likes
  const nzbBuffer = await myIndexer.fetchNzb(id);

  const form = new FormData();
  form.append("download_key", KEY);
  form.append("file", new Blob([nzbBuffer], { type: "application/x-nzb" }), `${id}.nzb`);
  form.append("category", type === "movie" ? "movies" : "tv");
  form.append("timeout", "300");

  const res  = await fetch(`${ALTMOUNT}/api/nzb/streams`, { method: "POST", body: form });
  if (!res.ok) return { streams: [] };

  const data = await res.json();
  return { streams: data.streams ?? [] };
});
```

--------------------------------

### Docker Volume Setup for SYMLINK Integration

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/integration.md

Example Docker Compose configuration for setting up volumes to allow both AltMount and Sonarr containers to access the same paths. This ensures symlinks resolve correctly across containers.

```yaml
services:
  altmount:
    volumes:
      - /mnt/mnt:rshared

  sonarr:
    volumes:
      - /mnt/mnt
```

--------------------------------

### Good: Start Server with Context Logging

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

Shows how to log the startup of a server using slog.InfoContext, including relevant parameters like the port number. Always pass the context.

```go
// ✅ Good: Log at appropriate levels with context
func StartServer(ctx context.Context, port int) error {
    slog.InfoContext(ctx, "Starting server", "port", port)
    // ... server logic
}
```

--------------------------------

### Build AltMount from Source

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Clone the AltMount repository and build the binary using make. Ensure Go 1.24.5+ and Bun are installed.

```bash
# Prerequisites: Go 1.24.5+ and Bun
git clone https://github.com/javi11/altmount.git
cd altmount

# Build everything (frontend + backend)
make

# The binary is now available as ./altmount
```

--------------------------------

### Create AltMount Docker Directories

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Before starting the AltMount Docker container, create the necessary './config' and './metadata' directories in your project.

```bash
mkdir -p ./config ./metadata
```

--------------------------------

### Docker Compose configuration

Source: https://github.com/javi11/altmount/blob/main/docker/README.md

Example configuration for deploying AltMount using Docker Compose.

```yaml
version: '3.8'
services:
  altmount:
    image: your-registry/altmount:latest
    container_name: altmount
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/config
      - ./metadata:/metadata
      - /var/run/docker.sock:/var/run/docker.sock # Required for the auto-update feature
    group_add:
      - "999" # GID of the docker group on the host
    ports:
      - "8080:8080"
    restart: unless-stopped
```

--------------------------------

### Run AltMount Backend Server

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Start the AltMount backend server in development mode. The server will run on the default port 8080.

```bash
make
go run ./cmd/altmount serve --config=./config.yaml
```

--------------------------------

### Configure WebDAV Settings in AltMount

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Example configuration for WebDAV settings in AltMount's config.yaml. Uses defaults if not specified.

```yaml
webdav:
  port: 8080
  user: "usenet"
  password: "usenet"
```

--------------------------------

### Verify installation and health

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Commands to verify the mount status and check the health endpoint.

```bash
ls -la /mnt/remotes/altmount
curl http://localhost:8080/live
```

--------------------------------

### Stremio Addon Install URL

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/stremio.md

Generates a personalized manifest URL for Stremio addon installation.

```APIDOC
## Stremio Addon Install

Once the integration is enabled and the configuration is saved, AltMount generates a personalised manifest URL:

```
<base_url>/stremio/<download_key>/manifest.json
```

This URL is shown in the **Addon Install URL** card in the web UI. You can:

- **Copy** the URL and paste it into Stremio → Add-ons → Install from URL.
- **Install** to open Stremio directly via the `stremio://` URI scheme.

The `download_key` embedded in the URL is the SHA-256 hash of your API key — safe to share with the Stremio app (see [Authentication](#authentication--the-download_key)).
```

--------------------------------

### Install Rclone Docker Volume Plugin

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/docker-volume-plugin.md

Install the rclone Docker Volume Plugin on your Docker host. Ensure FUSE 3 is installed and configured before running this command.

```bash
sudo mkdir -p /var/lib/docker-plugins/rclone/config
sudo mkdir -p /var/lib/docker-plugins/rclone/cache

docker plugin install rclone/docker-volume-rclone:amd64 \
  args="-v --links --uid=1000 --gid=1000 --async-read=true --allow-non-empty --allow-other \
  --rc --rc-no-auth --rc-addr=0.0.0.0:5572 --vfs-read-ahead=128M --vfs-read-chunk-size=32M \
  --vfs-read-chunk-size-limit=2G --vfs-cache-mode=full --vfs-cache-max-age=504h \
  --vfs-cache-max-size=50G --buffer-size=32M --dir-cache-time=10m --timeout=10m" \
  --alias rclone --grant-all-permissions
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Common commands for frontend development using Bun, including starting the dev server, building for production, previewing the build, and running linting/type checks.

```bash
# Start development server
bun dev

# Build for production
bun run build

# Preview production build
bun run preview

# Run linting
bun run lint

# Run type checking and linting
bun run check
```

--------------------------------

### Avoid: Logging in Hot Paths or Loops

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

This example shows logging within a loop processing files, which should be avoided. Logging in hot paths or frequently executed loops can significantly impact performance.

```go
// ❌ Avoid: Logging in hot paths or loops
func ProcessFiles(ctx context.Context, files []File) {
    for _, file := range files {
        slog.DebugContext(ctx, "Processing file", "file", file.Name)
        // ... process file
        slog.DebugContext(ctx, "File processed", "file", file.Name)
    }
}
```

--------------------------------

### Example API Output

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/stremio.md

The JSON response received after executing the submission command.

```json
{
  "streams": [
    {
      "url":   "http://localhost:8080/webdav/movies/My.Movie.2024.mkv",
      "title": "My.Movie.2024.mkv",
      "name":  "AltMount"
    }
  ],
  "_queue_item_id": 7,
  "_queue_status":  "completed"
}
```

--------------------------------

### Configure Metadata Path in AltMount

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Example configuration for the metadata root path in AltMount's config.yaml.

```yaml
metadata:
  root_path: "./metadata"
```

--------------------------------

### Install FUSE 3 Driver

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/docker-volume-plugin.md

Install the FUSE 3 driver if it is not already present. This is a prerequisite for the rclone Docker Volume Plugin.

```bash
sudo apt install fuse3
```

--------------------------------

### AltMount service script

Source: https://github.com/javi11/altmount/blob/main/docker/README.md

The main service script executed by s6-overlay to start the application.

```bash
#!/usr/bin/with-contenv bash
exec s6-setuidgid abc /app/altmount serve --config=/config/config.yaml
```

--------------------------------

### Submit NZB via cURL

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/stremio.md

Example command to compute the download key and submit an NZB file to the API.

```bash
# 1. Compute your download_key
DOWNLOAD_KEY=$(echo -n "YOUR_API_KEY" | sha256sum | awk '{print $1}')

# 2. Submit the NZB and get stream URLs
curl -s -X POST "http://localhost:8080/api/nzb/streams" \
  -F "download_key=${DOWNLOAD_KEY}" \
  -F "file=@/path/to/release.nzb" \
  -F "category=movies" \
  -F "timeout=300" | jq .
```

--------------------------------

### Generate Backend Code

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Generate necessary code for the backend, including protobuf code and files generated by 'go generate'. This command must be run before starting the server.

```bash
make generate
```

--------------------------------

### Configure NNTP Providers in AltMount

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Example configuration for NNTP providers in AltMount's config.yaml. At least one provider is required.

```yaml
providers:
  - host: "ssl-news.provider.com"
    port: 563
    username: "your_username"
    password: "your_password"
    max_connections: 20
    tls: true
```

--------------------------------

### Start Library Sync

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/health-monitoring.md

Initiates the synchronization process for the health record library.

```APIDOC
## POST /api/health/library-sync/start

### Description
Initiates the synchronization process for the health record library.

### Method
POST

### Endpoint
/api/health/library-sync/start
```

--------------------------------

### Avoid: Using slog Without Context Methods

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

This example illustrates incorrect usage of the slog package by calling slog.Info without passing a context. Always use context-aware methods like InfoContext.

```go
// ❌ Avoid: Using slog without context methods
func BadExample(ctx context.Context) {
    // Don't do this - use InfoContext instead
    slog.Info("Starting operation")
}
```

--------------------------------

### DaisyUI Card with Badge and Actions

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

A comprehensive example of a DaisyUI card including a title with a badge and a footer with aligned actions.

```html
<div className="card bg-base-100 shadow-lg">
  <div className="card-body">
    <h2 className="card-title">
      Card Title
      <div className="badge badge-secondary">NEW</div>
    </h2>
    <p>Card description text here</p>
    <div className="card-actions justify-end">
      <button type="button" className="btn btn-primary">Action</button>
    </div>
  </div>
</div>
```

--------------------------------

### Migrate Handler to Response Builders

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

Example showing the refactoring of a delete handler from manual JSON responses to the standardized response builder functions.

```go
// Before (inline responses)
func (s *Server) handleDeleteItem(c *fiber.Ctx) error {
    id := c.Params("id")
    if id == "" {
        return c.Status(400).JSON(fiber.Map{
            "success": false,
            "error": fiber.Map{
                "code":    "BAD_REQUEST",
                "message": "Item ID is required",
                "details": "",
            },
        })
    }

    if err := s.repo.Delete(c.Context(), id); err != nil {
        return c.Status(500).JSON(fiber.Map{
            "success": false,
            "error": fiber.Map{
                "code":    "INTERNAL_SERVER_ERROR",
                "message": "Failed to delete item",
                "details": err.Error(),
            },
        })
    }

    return c.SendStatus(204)
}

// After (response builders)
func (s *Server) handleDeleteItem(c *fiber.Ctx) error {
    id := c.Params("id")
    if id == "" {
        return RespondBadRequest(c, "Item ID is required", "")
    }

    if err := s.repo.Delete(c.Context(), id); err != nil {
        return RespondInternalError(c, "Failed to delete item", err.Error())
    }

    return RespondNoContent(c)
}
```

--------------------------------

### Configure Multiple Providers with SSL/TLS

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/providers.md

Example of configuring multiple NNTP providers, including a primary with SSL/TLS enabled and a backup provider. Ensure 'tls: true' for secure connections.

```yaml
providers:
  # Primary provider with SSL
  - host: "ssl-news.provider.com"
    port: 563
    username: "your_username"
    password: "your_password"
    max_connections: 20
    tls: true

  # Backup provider
  - host: "backup.provider.com"
    port: 563
    username: "backup_username"
    password: "backup_password"
    max_connections: 10
    tls: true
    is_backup_provider: true
```

--------------------------------

### Configure NONE (Direct Access) Import Strategy

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/integration.md

This configuration sets AltMount to use the NONE import strategy, suitable for setups without ARR integration or when direct access via the WebDAV/FUSE mount is preferred. No import directory is needed.

```yaml
import:
  import_strategy: NONE
```

--------------------------------

### DaisyUI Menu with Active State and Badge

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

Example of a DaisyUI menu component demonstrating active item styling and displaying a badge for new items.

```html
<ul className="menu bg-base-200 rounded-box">
  <li>
    <a className={activeItem === 'home' ? 'active' : ''}>
      <HomeIcon className="h-5 w-5" />
      Home
    </a>
  </li>
  <li>
    <a>
      <SettingsIcon className="h-5 w-5" />
      Settings
      <span className="badge badge-warning badge-xs">New</span>
    </a>
  </li>
</ul>
```

--------------------------------

### Regenerate Archive Fixtures

Source: https://github.com/javi11/altmount/blob/main/internal/importer/testdata/README.md

Run this bash script to regenerate the archive fixtures. Ensure 'rar' (WinRAR CLI) and '7z' (p7zip / 7-Zip) are installed. The script is idempotent and produces byte-identical output.

```bash
cd internal/importer/testdata
bash gen_fixtures.sh
git add -A
```

--------------------------------

### Docker Compose Volume Mounting

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/docker-volume-plugin.md

Example of mounting a remote storage volume using the rclone driver in a Docker Compose file. Ensure the plugin is installed and configured.

```yaml
services:
  altmount:
    image: ...

  sonarr:
    image: ...
    volumes:
      - altmount:/mnt/remotes/altmount

  ubuntu:
    image: ubuntu
    command: sleep infinity
    volumes:
      - altmount:/mnt/remotes/altmount
    environment:
      - PUID=1000
      - PGID=1000

volumes:
  altmount:
    driver: rclone
    ...
```

--------------------------------

### Integrate React-Specific ESLint Plugins

Source: https://github.com/javi11/altmount/blob/main/frontend/README.md

Configure ESLint to include rules from `eslint-plugin-react-x` and `eslint-plugin-react-dom`. This setup requires these plugins to be installed. Ensure your `tsconfig` files are correctly configured.

```javascript
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}'],
    extends: [
      // Other configs...
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])
```

--------------------------------

### Download Sample AltMount Configuration

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Download the sample configuration file for AltMount.

```bash
wget https://raw.githubusercontent.com/javi11/altmount/main/config.sample.yaml -O config.yaml
```

--------------------------------

### Download and Edit AltMount Sample Configuration

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Download the sample configuration file and edit it with your specific settings. Use 'wget' to download and 'nano' or your preferred editor to modify.

```bash
# Download sample configuration
wget https://raw.githubusercontent.com/javi11/altmount/main/config.sample.yaml -O config.yaml

# Edit with your settings
nano config.yaml
```

--------------------------------

### Copy Sample Backend Configuration

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Copy the sample configuration file to 'config.yaml' in the project root. This file is used to configure the backend server.

```bash
cp config.sample.yaml config.yaml
```

--------------------------------

### Build Backend Application

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Build the backend application binary. This can be done directly with 'go build' or using the 'make build' target.

```bash
# Build binary
go build -o altmount ./cmd/altmount

# Or use the Makefile
make build
```

--------------------------------

### Confirm Full Project Build

Source: https://github.com/javi11/altmount/blob/main/docs/superpowers/plans/2026-06-10-parallel-iso-metadata-write.md

Run the 'make' command to ensure the entire project builds successfully. This confirms all components integrate correctly.

```bash
make
```

--------------------------------

### Verify FUSE 3 Installation

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/docker-volume-plugin.md

Check if the FUSE 3 driver is installed on your system. The rclone Docker Volume Plugin requires FUSE 3.

```bash
fusermount3 --version
```

--------------------------------

### FUSE Endpoints

Source: https://github.com/javi11/altmount/blob/main/docs/docs/4. API/endpoints.md

Start, stop, and check the status of FUSE mounts.

```APIDOC
## FUSE Endpoints

### Description
Endpoints for managing FUSE (Filesystem in Userspace) mounts, including starting, stopping, and checking their status.

### Base Path
/api/fuse
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Build the frontend application for production. The output will be placed in the 'frontend/dist' directory.

```bash
cd frontend
bun run build
```

--------------------------------

### Create mount point directory

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Prepares the directory structure for mounting on Linux or macOS systems.

```bash
# Linux/macOS
sudo mkdir -p /mnt/remotes/altmount
sudo chown $USER:$USER /mnt/remotes/altmount
```

--------------------------------

### Check System Architecture

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Verify your system's architecture to download the correct AltMount binary. 'x86_64' requires the 'amd64' binary, while 'aarch64' requires the 'arm64' binary.

```bash
# Check your architecture
uname -m

# x86_64 -> use amd64 binary
# aarch64 -> use arm64 binary
```

--------------------------------

### Reset All Checks

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/health-monitoring.md

Resets all health checks, effectively starting the monitoring process from scratch.

```APIDOC
## POST /api/health/reset-all

### Description
Resets all health checks, effectively starting the monitoring process from scratch.

### Method
POST

### Endpoint
/api/health/reset-all
```

--------------------------------

### Config Endpoints

Source: https://github.com/javi11/altmount/blob/main/docs/docs/4. API/endpoints.md

Get, update, patch, reload, and validate system configuration settings.

```APIDOC
## Config Endpoints

### Description
Endpoints for retrieving, updating, patching, reloading, and validating the system's configuration.

### Base Path
/api/config
```

--------------------------------

### Create AltMount Configuration Directory

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Create the necessary configuration directory structure for AltMount.

```bash
# Create configuration directory
mkdir -p ~/.config/altmount
cd ~/.config/altmount
```

--------------------------------

### Run Backend and Frontend Services

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Instructions for running both the backend and frontend services concurrently in separate terminals for full development.

```bash
# In project root
make
go run ./cmd/altmount serve --config=./config.yaml
```

```bash
# In frontend directory
cd frontend
bun install
bun dev
```

--------------------------------

### Download AltMount for Linux x64

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Download the latest AltMount binary for Linux x64, make it executable, and optionally move it to your system's path.

```bash
# Download latest release
wget https://github.com/javi11/altmount/releases/latest/download/altmount-linux-amd64

# Make executable
chmod +x altmount-linux-amd64

# Move to system path (optional)
sudo mv altmount-linux-amd64 /usr/local/bin/altmount
```

--------------------------------

### Run AltMount Server

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Commands to run the AltMount server, either with the default configuration file or a specified one. Includes help commands.

```bash
# Run with default config (./config.yaml)
altmount serve

# Run with specific config file
altmount serve --config=/path/to/config.yaml

# Get help
altmount --help
altmount serve --help
```

--------------------------------

### Download AltMount for Linux ARM64

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Download the AltMount binary for Linux ARM64, make it executable, and optionally move it to your system's path.

```bash
# Download ARM64 version
wget https://github.com/javi11/altmount/releases/latest/download/altmount-linux-arm64

# Make executable
chmod +x altmount-linux-arm64

# Move to system path (optional)
sudo mv altmount-linux-arm64 /usr/local/bin/altmount
```

--------------------------------

### Build and Run Docker Development Image

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Commands to build a Docker development image for AltMount and run it as a container, mapping the configuration file and exposing the server port.

```bash
# Build the development image
docker build -f docker/Dockerfile -t altmount:dev .

# Run the container
docker run -p 8080:8080 -v $(pwd)/config.yaml:/app/config.yaml altmount:dev
```

--------------------------------

### Clone AltMount Repository

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Clone the AltMount repository and navigate into the project directory. This is the first step for setting up the development environment.

```bash
git clone https://github.com/javi11/altmount.git
cd altmount
```

--------------------------------

### Build Static Website Content

Source: https://github.com/javi11/altmount/blob/main/docs/README.md

Generates the static website files into the 'build' directory, ready for hosting.

```bash
npm run build
```

--------------------------------

### Build container images

Source: https://github.com/javi11/altmount/blob/main/docker/README.md

Commands to build development and CI container images.

```bash
docker build -f docker/Dockerfile -t altmount:dev .
```

```bash
# Build frontend first
cd frontend && bun run build && cd ..
docker build -f docker/Dockerfile.ci -t altmount:ci .
```

--------------------------------

### Create Required Directories for AltMount

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Create the metadata and logs directories required by AltMount.

```bash
mkdir -p ./metadata ./logs
```

--------------------------------

### View Original Imports

Source: https://github.com/javi11/altmount/blob/main/docs/superpowers/plans/2026-06-10-parallel-iso-metadata-write.md

Before modifying, review the current import statements in `internal/importer/iso_expand.go` to understand the existing dependencies.

```go
import (
	"context"
	"fmt"
	"log/slog"
	"path"
	"path/filepath"
	"strings"

	"github.com/javi11/altmount/internal/importer/archive"
	"github.com/javi11/altmount/internal/importer/parser"
	metapb "github.com/javi11/altmount/internal/metadata/proto"
)
```

--------------------------------

### Good: Process Import Queue with Context Logging

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

Demonstrates using slog.InfoContext and slog.ErrorContext for logging within a function that processes items from a queue. Ensure context is passed correctly.

```go
import (
    "context"
    "log/slog"
)

// ✅ Good: Use slog with context methods
func ProcessImportQueue(ctx context.Context, items []ImportItem) error {
    slog.InfoContext(ctx, "Processing import queue",
        "item_count", len(items))

    for _, item := range items {
        if err := processItem(ctx, item); err != nil {
            slog.ErrorContext(ctx, "Failed to process import item",
                "error", err,
                "item_id", item.ID)
            return err
        }
    }

    return nil
}
```

--------------------------------

### Build Project

Source: https://github.com/javi11/altmount/blob/main/docs/superpowers/plans/2026-06-10-parallel-iso-metadata-write.md

After making code modifications, run `go build` in the `internal/importer` directory to ensure there are no compilation errors. A successful build will exit with code 0 and no output.

```bash
cd internal/importer && go build ./...
```

--------------------------------

### Deploy Website using SSH

Source: https://github.com/javi11/altmount/blob/main/docs/README.md

Deploys the built website using SSH. Ensure your SSH keys are configured.

```bash
USE_SSH=true npm run deploy
```

--------------------------------

### Troubleshooting Playback Freezes

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/streaming.md

If playback continues to freeze, consider increasing `--vfs-read-chunk-size` and `--vfs-read-ahead` to improve data streaming performance.

```bash
--vfs-read-chunk-size
```

```bash
--vfs-read-ahead
```

--------------------------------

### Avoid: Excessive Debug Logging in UpdateConfig

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

This example demonstrates excessive and unnecessary debug logging within a configuration update function. Avoid logging at the debug level for every step, especially in potentially performance-sensitive operations.

```go
// ❌ Avoid: Excessive debug logs everywhere
func UpdateConfig(ctx context.Context, cfg Config) error {
    slog.DebugContext(ctx, "UpdateConfig called")
    slog.DebugContext(ctx, "Config value", "config", cfg)
    slog.DebugContext(ctx, "Validating config")

    if err := validateConfig(cfg); err != nil {
        slog.DebugContext(ctx, "Validation failed")
        return err
    }

    slog.DebugContext(ctx, "Saving config")
    if err := saveConfig(cfg); err != nil {
        slog.DebugContext(ctx, "Save failed")
        return err
    }

    slog.DebugContext(ctx, "Config updated successfully")
    return nil
}
```

--------------------------------

### Run AltMount container

Source: https://github.com/javi11/altmount/blob/main/docker/README.md

Execute the AltMount container with necessary volume mounts and environment variables.

```bash
docker run -d \
  --name altmount \
  -e PUID=1000 \
  -e PGID=1000 \
  -p 8080:8080 \
  -v /path/to/config:/config \
  -v /path/to/metadata:/metadata \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add 999 \
  your-registry/altmount:latest
```

--------------------------------

### Custom Hook for Fetching Data

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

Implement custom hooks starting with `use` for data fetching. Return an object with data, loading state, and a fetch function. Use `useCallback` for the fetch function to prevent unnecessary re-renders.

```tsx
function useApi<T>(endpoint: string) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(false);
  
  const fetchData = useCallback(async () => {
    setLoading(true);
    try {
      const response = await fetch(endpoint);
      const result = await response.json();
      setData(result);
    } finally {
      setLoading(false);
    }
  }, [endpoint]);
  
  return { data, loading, fetchData };
}
```

--------------------------------

### Configure Streaming and Import Performance

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/performance.md

Adjust prefetch settings and processor workers based on available system resources and bandwidth requirements.

```yaml
streaming:
  max_prefetch: 60 # More prefetch for high-bandwidth setups

import:
  max_processor_workers: 4 # Multiple NZB processors
  queue_processing_interval_seconds: 2 # Fast queue processing
```

```yaml
streaming:
  max_prefetch: 30 # Default — good balance

import:
  max_processor_workers: 2 # Standard processing
  queue_processing_interval_seconds: 5 # Standard interval
```

```yaml
streaming:
  max_prefetch: 10 # Lower prefetch to save memory

import:
  max_processor_workers: 1 # Single processor
  queue_processing_interval_seconds: 10 # Slower processing
```

--------------------------------

### Troubleshoot Windows WebDAV Client

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Notes on registry changes and alternative client recommendations.

```bash
# Windows WebDAV client issues
# May need registry changes for HTTP (vs HTTPS)

# Try alternative clients like WinSCP or Cyberduck
```

--------------------------------

### Gather System Information

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Commands to collect version, system resources, and environment details for troubleshooting.

```bash
# AltMount version
./altmount --version

# System information
uname -a

# Available resources
free -h
df -h
```

--------------------------------

### Download AltMount for macOS

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Download the AltMount binary for macOS, make it executable, and optionally move it to your system's path.

```bash
# Download for macOS
wget https://github.com/javi11/altmount/releases/latest/download/altmount-darwin-amd64

# Make executable
chmod +x altmount-darwin-amd64

# Move to system path (optional)
sudo mv altmount-darwin-amd64 /usr/local/bin/altmount
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Command to run frontend tests using Bun. Ensure you are in the frontend directory.

```bash
cd frontend
bun test
```

--------------------------------

### Download AltMount for Windows

Source: https://github.com/javi11/altmount/blob/main/docs/docs/2. Installation/other-methods.md

Download the AltMount executable for Windows using PowerShell or curl, saving it as altmount.exe.

```powershell
# Download using PowerShell
Invoke-WebRequest -Uri "https://github.com/javi11/altmount/releases/latest/download/altmount-windows-amd64.exe" -OutFile "altmount.exe"

# Or download using curl (if available)
curl -L -o altmount.exe https://github.com/javi11/altmount/releases/latest/download/altmount-windows-amd64.exe
```

--------------------------------

### Run Go Tests

Source: https://github.com/javi11/altmount/blob/main/docs/superpowers/plans/2026-06-10-parallel-iso-metadata-write.md

Execute the existing tests for the importer package to ensure no regressions were introduced. Then, run the tests with the race detector enabled to check for data races.

```bash
go test -v ./internal/importer/... -run TestExpandBareISO
```

```bash
go test -race ./internal/importer/... -run TestExpandBareISO
```

```bash
go test -race ./internal/importer/...
```

--------------------------------

### Troubleshooting commands

Source: https://github.com/javi11/altmount/blob/main/docker/README.md

Commands to resolve permission issues and verify container status.

```bash
sudo chown -R 1000:1000 /path/to/config /path/to/metadata
```

```bash
docker logs altmount
```

```bash
id $(whoami)  # Shows your UID/GID
```

--------------------------------

### Run Backend Tests

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Commands to run backend tests, including options for coverage, race detection, and generating an HTML coverage report.

```bash
# Run all tests
make test

# Run tests with coverage
make coverage

# Run tests with race detection
make test-race

# View coverage report in browser
make coverage-html
```

--------------------------------

### Monitor System Resources

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Use standard Linux utilities to monitor CPU, memory, and disk I/O.

```bash
# Check CPU and memory usage
top
htop

# Check disk I/O
iotop
iostat -x 1
```

--------------------------------

### Backend Development Commands

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

A collection of Make targets for common backend development tasks, including checks, tests, linting, code generation, vulnerability scanning, building, and cleaning.

```bash
# Run all checks (linting, tests, etc.)
make check

# Run tests
make test

# Run tests with race detection
make test-race

# Run linting
make lint

# Generate code
make generate

# Run vulnerability checks
make govulncheck

# Build the application
make build

# Clean up generated files
make clean
```

--------------------------------

### Mount AltMount with Recommended Rclone VFS Settings

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/streaming.md

Use these flags when mounting the AltMount WebDAV endpoint with rclone to ensure smooth media playback and efficient caching.

```bash
rclone mount altmount: /mnt/remotes/altmount \
  --vfs-cache-mode full \
  --vfs-read-chunk-size 56M \
  --vfs-cache-max-size 150G \
  --vfs-cache-max-age 72h \
  --vfs-read-ahead 80G \
  --vfs-cache-min-free-space 1G \
  --vfs-read-chunk-streams 4 \
  --read-chunk-size 32M \
  --read-chunk-size-limit 2G \
  --dir-cache-time 5s \
  --buffer-size 0 \
  --allow-other
```

--------------------------------

### Project File Organization

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

Standard directory structure for organizing components, hooks, pages, services, and types.

```text
src/
├── components/
│   ├── ui/              # Reusable UI components
│   │   ├── Button.tsx
│   │   ├── Modal.tsx
│   │   └── index.ts
│   ├── auth/            # Domain-specific components
│   │   ├── LoginForm.tsx
│   │   └── index.ts
│   └── layout/          # Layout components
│       ├── Navbar.tsx
│       └── Sidebar.tsx
├── hooks/               # Custom hooks
│   ├── useAuth.ts
│   ├── useApi.ts
│   └── index.ts
├── pages/               # Page components
│   ├── Dashboard.tsx
│   └── ConfigurationPage.tsx
├── services/            # API and external services
│   ├── api.ts
│   └── webdavClient.ts
├── types/               # TypeScript type definitions
│   ├── auth.ts
│   ├── config.ts
│   └── index.ts
└── utils/               # Utility functions
    ├── format.ts
    └── validation.ts
```

--------------------------------

### Fix Binary Permissions

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Use this command to make the AltMount binary executable. Ensure you are in the directory containing the binary.

```bash
chmod +x altmount
```

--------------------------------

### Backend Linting Commands

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Commands for backend linting using Make targets. Includes running all checks and fixing auto-fixable issues.

```bash
# Run all linting checks
make lint

# Fix auto-fixable issues
make golangci-lint-fix
```

--------------------------------

### Implement API Response Builders in Go

Source: https://github.com/javi11/altmount/blob/main/CLAUDE.md

Comparison between using the recommended response builder functions and manual inline JSON responses in Fiber handlers.

```go
import "github.com/javi11/altmount/internal/api"

// ✅ Good: Use response builders
func (s *Server) handleGetItem(c *fiber.Ctx) error {
    item, err := s.repo.GetItem(c.Context(), id)
    if err != nil {
        return api.RespondInternalError(c, "Failed to get item", err.Error())
    }
    if item == nil {
        return api.RespondNotFound(c, "Item", "")
    }
    return api.RespondSuccess(c, item)
}

// ❌ Avoid: Inline JSON responses
func (s *Server) handleGetItem(c *fiber.Ctx) error {
    item, err := s.repo.GetItem(c.Context(), id)
    if err != nil {
        return c.Status(500).JSON(fiber.Map{
            "success": false,
            "message": "Failed to get item",
        })
    }
    return c.Status(200).JSON(fiber.Map{
        "success": true,
        "data": item,
    })
}
```

--------------------------------

### Run AltMount from Configuration Directory

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Ensure AltMount is run from the directory containing the 'config.yaml' file if not specifying the config path explicitly.

```bash
# Run from directory containing config.yaml
cd /path/to/altmount/config
./altmount serve
```

--------------------------------

### Verify Docker Compose Volume Syntax

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Check your 'docker-compose.yaml' file to ensure the volume syntax for mounting './config' and './metadata' is correct.

```yaml
volumes:
  - ./config:/config
  - ./metadata:/metadata
```

--------------------------------

### Update Imports for Test File

Source: https://github.com/javi11/altmount/blob/main/docs/superpowers/plans/2026-06-10-parallel-iso-metadata-write.md

Add 'sort', 'strings', and 'sync' packages to the existing imports in the test file.

```go
import (
	"context"
	"sort"
	"strings"
	"sync"
	testing"

	"github.com/javi11/altmount/internal/importer/archive"
	"github.com/javi11/altmount/internal/importer/parser"
	metapb "github.com/javi11/altmount/internal/metadata/proto"
)
```

--------------------------------

### Deploy Website without SSH

Source: https://github.com/javi11/altmount/blob/main/docs/README.md

Deploys the built website using HTTPS. Replace <Your GitHub username> with your actual username.

```bash
GIT_USER=<Your GitHub username> npm run deploy
```

--------------------------------

### Login and Use Cookie Jar with Curl

Source: https://github.com/javi11/altmount/blob/main/docs/docs/4. API/endpoints.md

This bash script demonstrates how to log in to the API and store the resulting JWT in a cookie file for subsequent requests.

```bash
# 1. Log in and store the cookie
curl -c cookies.txt -X POST 'http://altmount.local:8585/api/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"yourpassword"}'

# 2. Reuse the cookie on subsequent requests
curl -b cookies.txt -X POST 'http://altmount.local:8585/api/health/bulk/restart' \
  -H 'Content-Type: application/json' \
  -d '{"ids":[0]}'
```

--------------------------------

### Frontend Linting Commands

Source: https://github.com/javi11/altmount/blob/main/docs/docs/6. Development/setup.md

Commands for frontend linting and type checking using Bun. Includes running linters and combined check commands.

```bash
cd frontend
bun run lint
bun run check
```

--------------------------------

### Specify AltMount Configuration Path

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

If the configuration file is not found in the default location, specify its full path when running the AltMount serve command.

```bash
./altmount serve --config=/full/path/to/config.yaml
```

--------------------------------

### Configure Provider Connections

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/performance.md

Define primary and backup providers with specific connection limits and TLS settings to optimize throughput.

```yaml
providers:
  # Primary provider with maximum connections
  - host: "fastest-endpoint.provider.com"
    port: 563
    max_connections: 50 # Maximum allowed by provider
    tls: true

  # Backup provider for load balancing
  - host: "backup.provider.com"
    port: 563
    max_connections: 30
    tls: true
    is_backup_provider: true
```

```yaml
providers:
  # Tier 1 provider - highest performance
  - host: "premium.provider.com"
    port: 563
    max_connections: 40
    tls: true

  # Tier 2 provider - different backbone
  - host: "alternative.provider.com"
    port: 563
    max_connections: 30
    tls: true

  # Block provider for fill-in
  - host: "block.provider.com"
    port: 563
    max_connections: 15
    tls: true
    is_backup_provider: true
```

--------------------------------

### Third-Party Addon Integration - Pattern B: Your addon resolves the NZB

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/stremio.md

Your addon finds the NZB file itself and hands it to AltMount for processing.

```APIDOC
### Pattern B — Your addon resolves the NZB

Your addon finds the NZB file itself (from any indexer or source) and hands it to AltMount. AltMount queues the download, waits for it to complete (long-poll), and returns stream URLs your addon passes directly to `callback({ streams })`.

### Endpoint
```
POST <base_url>/api/nzb/streams
Content-Type: multipart/form-data
```

### Parameters
#### Request Body
- **download_key** (string) - Required - SHA-256 of your AltMount API key
- **file** (file) - Required - The `.nzb` file (max 100 MB)
- **category** (string) - Optional - Download category (e.g. `movies`, `tv`)
- **timeout** (integer) - Optional - Seconds to wait before returning 408 (default: `300`)

### Response
#### Success Response (200 OK)
- **streams** (array) - An array of stream objects.
  - **url** (string) - URL to access the media file via WebDAV.
  - **title** (string) - Title of the media file.
  - **name** (string) - Name of the stream provider (e.g., "AltMount").
- **_queue_item_id** (integer) - The ID of the download queue item.
- **_queue_status** (string) - The status of the download queue item (e.g., "completed").

#### Response Example
```json
{
  "streams": [
    {
      "url":   "http://altmount.example.com/webdav/movies/My.Movie.2024.mkv",
      "title": "My.Movie.2024.mkv",
      "name":  "AltMount"
    }
  ],
  "_queue_item_id": 42,
  "_queue_status":  "completed"
}
```

**408 Timeout** — download did not finish within `timeout` seconds. Use `queue_item_id` from the error details to poll `GET /api/queue/:id` and retry.

### JavaScript Example
```javascript
builder.defineStreamHandler(async ({ type, id }) => {
  // Your addon resolves the NZB however it likes
  const nzbBuffer = await myIndexer.fetchNzb(id);

  const form = new FormData();
  form.append("download_key", KEY);
  form.append("file", new Blob([nzbBuffer], { type: "application/x-nzb" }), `${id}.nzb`);
  form.append("category", type === "movie" ? "movies" : "tv");
  form.append("timeout", "300");

  const res  = await fetch(`${ALTMOUNT}/api/nzb/streams`, { method: "POST", body: form });
  if (!res.ok) return { streams: [] };

  const data = await res.json();
  return { streams: data.streams ?? [] };
});
```

> **Caching:** AltMount deduplicates by NZB filename within the configured TTL
> (`nzb_ttl_hours`). Submitting the same filename a second time returns cached stream URLs
> immediately without re-downloading.
```

--------------------------------

### Service structure directory tree

Source: https://github.com/javi11/altmount/blob/main/docker/README.md

Visual representation of the s6-overlay service configuration directory.

```text
root/
└── etc/
    └── s6-overlay/
        └── s6-rc.d/
            ├── svc-altmount/
            │   ├── run        # Main service script
            │   └── type       # Service type (longrun)
            └── user/
                └── contents.d/
                    └── svc-altmount  # Service dependency
```

--------------------------------

### Configure SYMLINK Import Strategy

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/integration.md

Recommended for ARR integration, this configuration sets AltMount to use the SYMLINK strategy. It requires specifying the root mount path and the directory where symlinks will be created for completed downloads.

```yaml
# Root-level mount path (NOT inside import section)
mount_path: /mnt/remotes/altmount
import:
  import_strategy: SYMLINK
  import_dir: /mnt/symlinks/altmount
```

--------------------------------

### Regular Config Backup Script

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

A bash script to create a timestamped backup of the configuration file.

```bash
# Regular config backup
cp config.yaml config.yaml.backup.$(date +%Y%m%d)
```

--------------------------------

### Configure AltMount Paths and ARR Instances

Source: https://github.com/javi11/altmount/blob/main/docs/docs/3. Configuration/health-monitoring.md

Defines the root mount path, import strategy, and health monitoring settings, along with connection details for Sonarr and Radarr instances.

```yaml
# Root level — where ARRs mount AltMount via WebDAV/rclone
mount_path: "/mnt/remotes/altmount"

# Import — where symlinks/STRM files are placed after import processing
import:
  dir: "/mnt/imports"
  strategy: "SYMLINK"  # or "STRM" or "NONE"

# Health — where your final library lives (e.g. where Plex/Jellyfin reads from)
health:
  enabled: true
  library_dir: "/mnt/library"

# ARR instances — their root folders must be under mount_path
arrs:
  enabled: true
  radarr_instances:
    - name: "radarr-main"
      url: "http://localhost:7878"
      api_key: "your-api-key"
      enabled: true
  sonarr_instances:
    - name: "sonarr-main"
      url: "http://localhost:8989"
      api_key: "your-api-key"
      enabled: true
```

--------------------------------

### Verify Binary File Type

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Use the 'file' command to check if the AltMount binary is corrupted. A valid executable should be identified as an ELF binary.

```bash
# Check if file is corrupted
file altmount

# Should show: ELF 64-bit LSB executable...

```

--------------------------------

### Verify WebDAV Credentials

Source: https://github.com/javi11/altmount/blob/main/docs/docs/5. Troubleshooting/common-issues.md

Check configuration for case sensitivity and special characters.

```yaml
webdav:
  user: "correct_username" # Check case sensitivity
  password: "correct_password" # Check special characters
```