If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/OpenListTeam/OpenList shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 41+ active contributors
• Distributed ownership (top contributor 19% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live OpenListTeam/OpenList repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/OpenListTeam/OpenList.

What it runs against: a local clone of OpenListTeam/OpenList — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in OpenListTeam/OpenList | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of OpenListTeam/OpenList. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/OpenListTeam/OpenList.git
#   cd OpenList
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of OpenListTeam/OpenList and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "OpenListTeam/OpenList(\\.git)?\\b" \\
  && ok "origin remote is OpenListTeam/OpenList" \\
  || miss "origin remote is not OpenListTeam/OpenList (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/root.go" \\
  && ok "cmd/root.go" \\
  || miss "missing critical file: cmd/root.go"
test -f "cmd/server.go" \\
  && ok "cmd/server.go" \\
  || miss "missing critical file: cmd/server.go"
test -f "drivers/alias/driver.go" \\
  && ok "drivers/alias/driver.go" \\
  || miss "missing critical file: drivers/alias/driver.go"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/OpenListTeam/OpenList"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

OpenList is a community-driven fork of AList (a file listing server) designed as a resilience layer against trust-based attacks on open-source projects. It provides a Go-based file browsing and sharing platform supporting 40+ cloud storage backends (115, Aliyun OSS, Azure Blob, AWS S3, SMB, SFTP, etc.) with AGPL-3.0 licensing to ensure code transparency and prevent proprietary derivatives. Monolithic Go application: cmd/ contains CLI entry points (root.go → server.go for daemon, admin.go for user management), drivers/ contains modular storage backend implementations (115, 115_open, etc.), with internal packages managing auth, storage, and API. Dockerfile and docker-compose.yml indicate containerized deployment as primary use case.

System administrators and self-hosted enthusiasts who want to centrally manage and browse files across multiple cloud storage services without trusting closed-source intermediaries. Also appeals to open-source maintainers concerned about supply-chain security and proprietary forks.

Actively developed but in transition: migrated to v4 with Go 1.24 toolchain, has comprehensive CI/CD (build.yml, release.yml, beta_release.yml workflows), Docker support, and multi-language documentation (Chinese, Japanese, Dutch). However, being a recent fork from AList, community adoption and test coverage are not yet established. Production-ready for self-hosted deployment, but ecosystem is still stabilizing.

Moderate risk: 40+ driver dependencies for various cloud backends create a large attack surface (Azure SDK, AWS SDK, Aliyun, SMB/SFTP libraries). Small team (OpenListTeam) maintains this, creating single-point-of-failure risk. Dependencies like github.com/SheltonZhu/115driver and github.com/foxxorcat/mopan-sdk-go are third-party and may have infrequent updates. AGPL-3.0 licensing could conflict with some enterprise use cases.

Active CI/CD pipeline suggests regular releases (beta_release.yml, release.yml workflows). Recent file structure shows focus on driver expansion (115_open added alongside 115), multi-language docs maintenance (README_cn.md, README_ja.md, README_nl.md), and community governance (CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md). Workflows include automated changelog generation and Docker image testing.

git clone https://github.com/OpenListTeam/OpenList.git && cd OpenList && go mod download && go build -o ./bin/openlist ./cmd && ./bin/openlist server

Daily commands: Development: air (via .air.toml for hot-reload), then server listens on configured port. Production: Dockerfile or docker-compose.yml. Makefile exists but specifics not visible—likely contains standard targets. Start with: go run ./cmd server (after env setup in cmd/flags/config.go).

• cmd/root.go — Application entry point and CLI root command setup—every contributor must understand the command-line interface structure and initialization flow.
• cmd/server.go — HTTP server initialization and routing—essential for understanding how requests are dispatched and how the core API is structured.
• drivers/alias/driver.go — Base driver interface abstraction—foundational for all storage driver implementations; understanding this is critical for adding new storage backends.
• .github/workflows/build.yml — Build pipeline and release process—defines how code is tested, built, and deployed; crucial for understanding CI/CD expectations.
• go.mod — Go module dependencies and version constraints—reveals all critical external libraries (Azure SDK, AWS SDK, crypto libraries) and Go version requirements.

• CLI Command Layer (cmd/) (Cobra, Go flag parsing, YAML config) — Parses command-line arguments, initializes configuration, and executes user-initiated operations (server start, user management, cryptography).
  • Failure mode: Invalid config or missing credentials cause startup failure with clear error messages; prevents server from starting in unsafe state.
• Driver Interface & Registry (Go interfaces, reflection/plugin system (if applicable)) — Abstract interface that all storage backends implement; router selects appropriate driver based on request path or storage ID; handles driver lifecycle.
  • Failure mode: Unsupported driver returns 404; missing credentials return 401; API rate limits or network errors return 503 or retry with backoff.
• Individual Storage Driver (e.g., 115, 123, Azure) (Cloud-specific SDKs (Azure SDK, AWS SDK, etc.); HTTP clients; credential encryption) — Authenticates with specific cloud provider, translates abstract file operations to provider-specific API calls, handles pagination and streaming.
  • Failure mode: Network timeout → retry with exponential backoff; invalid credentials → 401; quota exceeded → 429 (too many requests).
• Credential Cache & Encryption (AES encryption (ProtonMail/go-crypto), in-memory map, optional persistent storage (Tache)) — Stores encrypted cloud API credentials and tokens; refreshes tokens before expiry; abstracts credential lifecycle from drivers.
  • Failure mode: Credential decryption failure →

Add a New Storage Driver

1. Create new driver directory under drivers/ (e.g., drivers/mynewservice/) (drivers/alias/driver.go)
2. Implement the driver interface in driver.go following the pattern from drivers/alias/driver.go and drivers/115/driver.go (drivers/alias/driver.go)
3. Add metadata and type definitions in meta.go and types.go similar to drivers/115/meta.go and drivers/115/types.go (drivers/alias/meta.go)
4. Register the driver in cmd/storage.go or equivalent driver registry (cmd/storage.go)

Add a New CLI Command

1. Create a new file in cmd/ directory (e.g., cmd/mycommand.go) (cmd/root.go)
2. Define command using Cobra framework following the pattern in cmd/admin.go or cmd/user.go (cmd/admin.go)
3. Register command in cmd/root.go by adding it to the root command's AddCommand() (cmd/root.go)
4. Add any required flags in cmd/flags/config.go if needed (cmd/flags/config.go)

Build and Release a New Version

1. Update version in cmd/version.go with new version string (cmd/version.go)
2. Push commit to main branch; GitHub Actions in .github/workflows/release.yml automatically detects version tags (.github/workflows/release.yml)
3. Docker images are built and pushed automatically via .github/workflows/release_docker.yml (.github/workflows/release_docker.yml)
4. Release artifacts are generated and published to GitHub Releases (.github/workflows/release.yml)

• Go 1.24+ — Provides excellent concurrency model for handling multiple storage backends and long-running server processes; strong standard library for HTTP and crypto.
• Cobra CLI framework — De-facto standard Go CLI framework; enables clean, modular command structure with automatic help generation and flag parsing.
• Multi-cloud SDK support (Azure, AWS, Aliyun, etc.) — Enables OpenList to abstract over multiple cloud storage providers; critical for the 'anti-trust' mission of avoiding vendor lock-in.
• Go-cache & Tache — In-memory and persistent caching for credentials and metadata; reduces API calls and improves response latency for frequently accessed resources.
• Docker & docker-compose — Containerization for reproducible deployments across environments; simplifies testing, local development, and production rollout.

• Pluggable driver architecture instead of unified cloud abstraction layer

  • Why: Allows each storage backend (115, 123, Aliyun, Azure, AWS) to fully exploit its unique API features without compromising to a lowest-common-denominator interface.
  • Consequence: Developers must write driver-specific code for new backends; added code duplication across drivers but better performance and feature completeness per storage service.

• In-memory caching (go-cache) with optional persistent cache (Tache) rather than requiring external Redis/Memcached

  • Why: Reduces deployment complexity and external dependencies; easier to self-host on minimal infrastructure.
  • Consequence: Cache is lost on restart (memory) or limited by disk (Tache); multi-instance deployments require sticky sessions or shared cache backend.

• CLI-first operations (cmd/) for admin/user management rather than REST API endpoints

  • Why: Simpler to implement; reduces attack surface for sensitive operations like password reset and 2FA management.
  • Consequence: Administrative tasks require SSH/shell access to server; less suitable for remote web-based admin panels.

• Real-time file synchronization or watch-directory mirroring
• Built-in user authentication UI or web-based admin dashboard (CLI-only)
• Cross-region replication or disaster recovery orchestration
• Full S3-compatible object storage API (uses native cloud APIs instead)

1. drivers/ are pluggable via registration in cmd/server.go—missing driver import silently disables that backend. 2) cmd/flags/config.go uses caarlos0/env with struct tags—environment variable names are case-sensitive and tied to struct field names. 3) Two versions of 115 driver (drivers/115 and drivers/115_open)—unclear which is preferred; check cmd/server.go for active initialization. 4) SQLite (glebarez/sqlite) is default persistence—migrations may be embedded; check internal/ for schema. 5) AGPL-3.0 requires source distribution if you run modified versions as a service—commercial self-hosted deployments must handle this.

• Pluggable Driver Architecture — OpenList's core strength—adding new storage backends (S3, GCS, WebDAV) requires only implementing a driver interface, not forking the codebase. Essential to understand for maintainability.
• AGPL-3.0 Copyleft Licensing — Non-negotiable constraint in this fork—any commercial SaaS deployment or modification must open-source changes. Differs legally from permissive licenses like MIT; shapes contribution policy.
• JWT + WebAuthn Multi-Factor Auth — Security model relies on JWT tokens (cmd/crypt.go, golang-jwt/jwt) plus optional WebAuthn (hardware keys)—critical for self-hosted deployments where leaked credentials have full storage access.
• Full-Text Search via Bleve — Large file listings across multiple backends require fast searching; Bleve (blevesearch/bleve) provides inverted-index search without external dependencies like Elasticsearch.
• WebSocket Real-Time Notifications — gorilla/websocket enables live file listing updates and progress streaming for multi-backend operations without polling; critical for responsive UI in web frontend.
• SQLite as Embedded Database — glebarez/sqlite eliminates external DB dependency for single-node deployments; schema is likely embedded via SQL migrations—important for zero-configuration self-hosting.
• Supply-Chain Trust (Motivation) — OpenList exists explicitly to resist proprietary forks and closed-source derivatives of AList—understanding this antitrust philosophy shapes code review priorities and contributor expectations.

• alist-org/alist — Original upstream project; OpenList is a fork, so tracking diff helps understand governance-specific changes
• rclone/rclone — Alternative multi-cloud sync tool; shares similar backend driver architecture for unified storage access
• nextcloud/server — Ecosystem competitor with similar self-hosted file-sharing model; relevant for feature parity and UX benchmarking
• syncthing/syncthing — FOSS-first distributed alternative; shares AGPL ethos and decentralization philosophy OpenList targets
• OpenListTeam/go-cache — Companion package maintained by same team; used internally for caching driver responses and reducing API calls

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for multi-driver storage operations

The repo has 20+ storage drivers (115, 123, Azure, AWS S3, SMB2, FTP, etc.) but no visible test files in the drivers/ directory. Adding comprehensive integration tests for common operations (List, Get, Put, Delete) across 3-4 major drivers would catch regressions early and serve as documentation for driver implementations.

• [ ] Create drivers//tests.go or drivers/_test.go for at least drivers/115/, drivers/123/, and drivers/azure/ (S3 available via AWS SDK)
• [ ] Implement test fixtures that mock cloud provider responses or use Docker containers (docker-compose.yml already exists)
• [ ] Add TestList, TestGet, TestPut, TestDelete functions covering success and error cases
• [ ] Update .github/workflows/test_docker.yml to run Go tests with -race flag to catch concurrency issues

Document storage driver implementation contract

With 20+ drivers in drivers/ directory, new contributors need clear guidance on implementing new drivers. Currently no CONTRIBUTING.md section or drivers/README.md explaining the required interfaces, configuration flow (meta.go, driver.go, types.go pattern), or authentication patterns (API keys, OAuth, etc.).

• [ ] Create drivers/README.md with driver architecture overview and the repeating pattern (meta.go defines DriverMeta, driver.go implements Driver interface, types.go defines config structs)
• [ ] Document required interface methods by examining one complete driver like drivers/123/ - List(), Get(), Put(), Remove() signatures
• [ ] Add a drivers/TEMPLATE directory with skeleton driver code showing auth setup, error handling, and pagination patterns
• [ ] Link new drivers/README.md from main CONTRIBUTING.md

Add GitHub Actions workflow for cross-platform binary release validation

Repo has release.yml and release_docker.yml workflows, but no validation that built binaries work on the multiple OSes and architectures they target. Given the cmd/ structure supports Windows (stop_windows.go) and Unix variants, add pre-release testing to prevent broken releases.

• [ ] Create .github/workflows/release_validation.yml that builds binaries for linux/amd64, linux/arm64, windows/amd64, darwin/amd64 using go build in cmd/
• [ ] For each OS variant, run basic smoke tests: ./openlist --version, ./openlist --help, validate config file parsing with cmd/flags/config.go
• [ ] Add matrix strategy to test across Go 1.24.0 (specified in go.mod) and at least one older stable version
• [ ] Trigger workflow on PRs targeting release branches and before release.yml executes

• Add unit tests for drivers/115/util.go and drivers/115/meta.go—currently no *_test.go files visible; high test coverage is critical for security-focused project
• Document driver development guide in docs/—no internal/drivers/README exists; new contributors struggle to add storage backends (S3-compatible, Nextcloud, etc.)
• Create GitHub issue template for driver feature requests—existing templates are bug/feature generic; dedicated driver template would streamline 'add support for X storage' issues

• High · Docker Container Running as Root — docker-compose.yml (line: user: '0:0'). The docker-compose.yml configuration explicitly sets 'user: 0:0' (root), which runs the OpenList container with elevated privileges. This violates the principle of least privilege and increases the attack surface if the container is compromised. Fix: Remove the 'user: 0:0' directive and use the non-root user defined in the Dockerfile (openlist with UID 1001). Update to: user: '1001:1001' or remove the user directive entirely to use the image's default user.
• High · Overly Permissive UMASK Setting — docker-compose.yml (UMASK=022). UMASK=022 in the docker-compose.yml environment variables creates files with world-readable permissions (644 for files, 755 for directories). Combined with root execution, this could expose sensitive data stored in mounted volumes. Fix: Change UMASK to 0077 or 0027 to restrict file permissions to owner/group only. Alternatively, use 0077 for maximum security: 'UMASK=0077'.
• High · Unrestricted Volume Mount Permissions — docker-compose.yml (volumes section). The docker-compose.yml mounts '/etc/openlist:/opt/openlist/data' with no explicit permission controls. Combined with root user execution, any compromised process can modify system configuration files. Fix: Use bind mount options to restrict permissions: 'volumes: - /opt/openlist/data:/opt/openlist/data:rw' and ensure the host directory is properly secured. Never mount /etc directly. Use a dedicated data directory with restricted permissions.
• Medium · Incomplete Dockerfile CMD Instruction — Dockerfile (final line). The Dockerfile CMD instruction appears to be truncated/incomplete ('CMD [ "/entrypoint.s'). This could indicate a build issue or incomplete configuration that may cause unexpected container behavior. Fix: Complete the CMD instruction: 'CMD ["/entrypoint.sh"]' and verify the entrypoint.sh file exists and is properly configured.
• Medium · Alpine Edge Base Image — Dockerfile (line: FROM alpine:edge). The Dockerfile uses 'FROM alpine:edge AS builder' which pulls the bleeding-edge version. This introduces unpredictability and potential incompatibilities. Edge versions may contain unreleased security patches or unstable packages. Fix: Use a specific stable Alpine version: 'FROM alpine:3.20' or similar stable release to ensure reproducible builds and known package versions.
• Medium · Exposed Debug/Admin Ports Without Restrictions — docker-compose.yml (ports: 5244, 5245) and Dockerfile (EXPOSE). Ports 5244 and 5245 are exposed without documented access controls or authentication mechanism visibility. These could be admin/debug ports requiring protection. Fix: Document the purpose of each port. Implement network-level access controls (firewall rules, network policies). Consider requiring authentication for admin interfaces. Use read-only security contexts where possible.
• Medium · Missing Security Headers Configuration — File structure: No visible security middleware configuration. Based on the Gin-based framework detected in dependencies (github.com/gin-gonic/gin), no visible security headers middleware is evident in the file structure, which could leave the application vulnerable to XSS, clickjacking, and other header-based attacks. Fix: Implement security headers middleware: Use packages like 'github.com/urfave/negroni' or implement custom middleware to add: Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security headers.
• Medium · No Resource Limits in Docker Compose — docker-compose.yml (services.openlist section). The docker-compose.yml does not specify CPU, memory, or I/O limits, allowing the container to consume unlimited system resources and potentially cause denial of service. Fix: Add resource limits to the service configuration: 'deploy: resources: limits: cpus: "2" memory: 2G reservations: cpus: "1"

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.