pvc-explorer-agent is a lightweight HTTP file-browser agent that mounts a PersistentVolumeClaim and exposes its contents over a simple REST API.

Note

By default the agent has no authentication and is only reachable through the controller proxy, which enforces Basic Auth and role checks. Never expose the agent port directly.

Optional Bearer token authentication can be enabled by setting the AUTH_TOKEN environment variable. When set, every request must include an Authorization: Bearer <token> header.

Community

• Contributing guide
• Code of Conduct
• Security policy

Highlights

• HTTP file browser endpoints for listing, downloading, editing, and uploading files
• Read-only fallback when another workload is using the same PVC
• An embedded Vue UI for standalone use

🚀 Getting Started

Start with the overview in docs/getting-started.md.

For the runtime model and API surface, see docs/overview.md.

For local development and test commands, see docs/development.md.

For CRA, open source security, and license compliance notes, see docs/CRA_COMPLIANCE.md, docs/OPEN_SOURCE_SECURITY.md, and docs/LICENSE_COMPLIANCE.md.

Quick start

make run-agent ROOT=./testdata/demo PVC=demo-pvc

The repository includes a small demo dataset in ./testdata/demo for local UI and API testing. It includes nested directories plus text, YAML, JSON, CSV, and log files.

Container Images

• Stable OCI images are published to ghcr.io/pvc-explorer-operator/pvc-explorer-agent from GitHub releases.
• The latest stable release is also published as :latest.
• A mutable development image is published as :dev from main when changes affect the published image.
• Published images are multi-arch OCI indexes for linux/amd64 and linux/arm64.
• If you need a branch-specific or experimental image, build your own locally from Dockerfile.
• Dockerfile.acme is kept as a documented overlay example only. ACME images are not built or published by this project.

Pull images

docker pull ghcr.io/pvc-explorer-operator/pvc-explorer-agent:latest
docker pull ghcr.io/pvc-explorer-operator/pvc-explorer-agent:dev

Verify signatures

Published images are signed keylessly with cosign and GitHub Actions OIDC.

cosign verify ghcr.io/pvc-explorer-operator/pvc-explorer-agent:latest \
  --certificate-identity-regexp 'https://github.com/pvc-explorer-operator/pvc-explorer-agent/.github/workflows/oci-image.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The workflow enables BuildKit provenance and attaches an SBOM OCI artifact with cosign. The commands below show the supported, user-facing verification and retrieval flow.

Downloadable SBOM files are also published. The Syft-generated SPDX JSON SBOM is attached to the image as an OCI artifact via cosign attach sbom:

# Download the SBOM for the latest release
cosign download sbom ghcr.io/pvc-explorer-operator/pvc-explorer-agent:latest

# Download the SBOM for the dev image
cosign download sbom ghcr.io/pvc-explorer-operator/pvc-explorer-agent:dev

# Download the SBOM for a specific release
cosign download sbom ghcr.io/pvc-explorer-operator/pvc-explorer-agent:v<release>

Additionally:

• For stable releases: the same sbom-<tag>.spdx.json file is also attached as a release asset on the GitHub Release page for direct download.

Release process

1. Merge the release-ready changes into main.
2. Create and push a version tag such as <version>.
3. Draft or publish a GitHub Release for that tag.
4. Publishing the release triggers the image workflow.
5. The workflow builds from Dockerfile, pushes ghcr.io/pvc-explorer-operator/pvc-explorer-agent:<version>, signs it with cosign, and attaches provenance.
6. If the release is not marked as a prerelease, the same digest is also tagged as :latest.

Pushes to main that change published-image inputs refresh the mutable :dev image.

For a GitHub release reference and platform mapping, see docs/release-reference.md.

For maintainers, see RELEASE.md for a copy-paste release checklist.

📚 Documentation

• Contributor workflow: CONTRIBUTING.md
• Development workflow: docs/development.md
• Local usage and startup: docs/getting-started.md
• Overview and API surface: docs/overview.md
• Release reference: docs/release-reference.md
• Maintainer release playbook: RELEASE.md
• Security reporting: SECURITY.md
• UI overlays: docs/overlays.md
• CRA compliance: docs/CRA_COMPLIANCE.md
• Open source security: docs/OPEN_SOURCE_SECURITY.md
• License compliance: docs/LICENSE_COMPLIANCE.md

Local quality and compliance commands

make check
make vuln-check
make sbom
make license-check

🤝 Contributing

Contributions are welcome. Start with CONTRIBUTING.md and pick up an issue labelled good first issue when you want a small, well-scoped task.

👨‍💻 Maintainers

This project is maintained in public. If you need help, open an issue or start a discussion in the repository.

📝 License

Apache License 2.0. See LICENSE.