Skip to main content
A storage provider is the backend where NekoHub writes and reads image files when you upload an asset. NekoHub supports three provider types, each suited to different use cases.

​
Provider types

Local

Files are stored on the server’s local disk. Straightforward to set up and requires no external services.

S3-compatible

Files are stored in any S3-compatible object storage service, such as AWS S3 or MinIO. Recommended for production deployments.

GitHub Repo

Files are committed to a GitHub repository. Suited for supplementary or platform-backed storage scenarios.

​
Local

Local storage writes files to a directory on the server running NekoHub. It is the simplest option and works well for single-machine setups, local development, or situations where you don’t need external object storage. Best for: Single-machine deployments, local testing.

​
S3-compatible

S3-compatible storage uses the S3 API to store files in an object storage bucket. This works with AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces, and any other S3-compatible service. Best for: Production deployments requiring durability, scalability, or CDN integration.
Use S3-compatible storage for any production deployment. It gives you durability, scalability, and direct public URL support that local storage cannot match.

​
GitHub Repo

GitHub Repo storage commits image files directly to a GitHub repository. It is an experimental provider and behaves differently from traditional object storage — file access depends on repository visibility and GitHub’s API rate limits. Best for: Supplementary use cases where the repository is already the source of truth, or platform-style asset hosting on public repositories.
GitHub Repo storage is experimental and not recommended as your primary storage for a production deployment. It is subject to GitHub API rate limits and does not support the full range of storage capabilities (such as private reads and visibility toggles). Use a local or S3-compatible provider as your primary storage instead.

​
Storage provider profiles

A storage provider profile is a named configuration for a specific storage backend. You create and manage profiles from the /providers page in the admin console or via the /api/v1/system/storage/providers API. Each profile stores:
  • A display name and unique identifier
  • The provider type (local, s3, github-repo)
  • Provider-specific configuration (e.g. bucket name, region, endpoint URL)
  • Credentials (stored securely and not returned in plaintext after creation)
You can create multiple profiles — for example, one for your primary S3 bucket and one for a secondary local backup — and choose which profile to use when uploading each asset.

​
Default provider profile

One profile can be marked as the default. When you upload an asset without specifying a storage provider profile, NekoHub uses the default profile automatically. You can change the default profile at any time. Changing the default does not affect assets already uploaded to other providers.

​
Provider capabilities

Not all storage providers support the same features. The capabilities of a profile are reported when you fetch provider details:
CapabilityDescription
supportsPublicReadThe provider can serve files publicly without authentication.
supportsPrivateReadThe provider can serve private files through an access-controlled endpoint.
supportsVisibilityToggleYou can change an asset between public and private after upload.
supportsDeleteThe provider supports deleting files.
supportsDirectPublicUrlThe provider returns a direct, permanent public URL for each asset.
requiresAccessProxyPrivate file reads must be proxied through the NekoHub API rather than served directly.
recommendedForPrimaryStorageThe provider is suitable as a primary storage backend.
isExperimentalThe provider is experimental and may have limitations.
Check the capabilities of your chosen provider before relying on features like private asset access or visibility toggling.