VersityGW: an S3 gateway in front of your POSIX filesystem

What VersityGW solves, and who it is for

Most S3 clients assume an object store. Most scientific and HPC data sits on a POSIX filesystem. VersityGW puts an S3 API in front of that filesystem so existing applications can talk to it without a migration. The README describes the project as "a simple to use tool for seamless inline translation between AWS S3 object commands and storage systems."

The intended audience is narrower than "anyone who wants S3". It is teams that already own storage: a ScoutFS cluster, a generic POSIX mount, an Azure Blob account, or another S3 server they want to front. The README lists four use cases, and the first is the telling one: turn your local filesystem into an S3 server with a single command. Protocol compatibility in the posix backend means the same files remain reachable over POSIX and over S3.

That dual-access property is the actual selling point. If you only need object storage and nothing else, a purpose-built object store is a simpler answer. VersityGW earns its place when the data must stay where it is.

How the translation layer is put together

The server receives S3 HTTP requests and rewrites them as operations against a backend. The HTTP and routing layer is the Fiber web framework, and S3 API compatibility leans on the official aws-sdk-go-v2 "whenever possible for maximum service compatibility with AWS S3", according to the README. Backends are pluggable: the README names generic POSIX, Versity's ScoutFS, Azure Blob Storage, and other S3 servers.

The gateway is stateless. Any instance can service any request, so a load balancer can spread traffic across a cluster of gateways for aggregate throughput. That is a clean scaling story, and it has a consequence worth stating plainly: the gateway holds no index of its own. Whatever consistency, locking or versioning guarantees you get come from the backend. The README's posix example points older object versions at a separate directory, which is where versioning state lives.

The repository layout reflects the modular design: backend/, s3api/, s3err/, s3response/, iamapi/, auth/, metrics/, webui/, plus rdma/, cubackend/ and cuwrapper/ for the RDMA and cuObject work. The go.mod pins fiber/v3, aws-sdk-go-v2, the Azure blob SDK, go-ldap, hashicorp/vault-client-go, NATS, Kafka and RabbitMQ clients, and scoutfs-go, which tells you which IAM and event paths the project actually supports.

Installing VersityGW and serving a directory over S3

The README points to binary release builds for Linux, macOS, BSD and Windows on amd64 and arm64, so the fastest path is to download the release for your platform from the GitHub releases page. Building from source requires Go, since go.mod declares go 1.26.0; the Makefile's BIN variable is versitygw and the Dockerfile builds cmd/versitygw with CGO_ENABLED=0.

The README's own first run creates two directories and starts the gateway with flat-file IAM accounts enabled. The --iam-dir option is what turns on simple JSON flat file accounts, and the README notes that setting is intended for testing.

mkdir /tmp/vgw /tmp/vers
ROOT_ACCESS_KEY="testuser" ROOT_SECRET_KEY="secret" ./versitygw --port :10000 --iam-dir /tmp/vgw posix --versioning-dir /tmp/vers /tmp/vgw

After that command the host listens on port 10000 and serves the directory /tmp/vgw, with older object versions kept in /tmp/vers. The README says it is fine for both directories to live on the same filesystem.

Option placement matters and is easy to get wrong. Global options come before the backend type; backend options come after it. The command format is versitygw [global options] command [command options] [arguments...], and ./versitygw --help prints the usage output.

./versitygw --help

Once the server is up, point any S3 client at http://localhost:10000 with the access key and secret you exported. The README does not walk through a client invocation, so the exact client flags are on you; the endpoint, port and credentials are the three values that matter.

Static website hosting and the RDMA path

Two features sit outside the basic translate-and-store flow. The first is static website hosting. A separate website endpoint is enabled with --website :8090 --website-domain example.com, which gives virtual-host style routing: blog.example.com serves the bucket named blog, and example.com serves the bucket example.com. If you omit --website-domain, the gateway falls into catch-all mode and the full hostname becomes the bucket name, so buckets have to be named as fully qualified domain names such as blog.example.com. The README defers the rest of the --website-* flags to the Global Options wiki page.

The second is S3 over RDMA. The README states that VersityGW supports S3 over RDMA to bypass the kernel network stack for high-throughput, low-latency transfers, aimed at HPC and data-intensive workloads where network overhead is the bottleneck. Setup details live on the S3 RDMA wiki page. There is also vgwrdma, described as a VersityGW-based service exposing a standard S3 API accelerated with NVIDIA's cuObject protocol, and the Makefile shows it is built from ./cmd/vgwrdma with a separate builder image and CUDA library paths.

Both features are real, and both are documented primarily on the wiki rather than in the README. Treat the README as an index, not a manual.

Where VersityGW is the wrong choice

The stateless design is the limitation as much as the feature. Because the gateway keeps no index, S3 semantics are only as strong as the backend allows. A shared POSIX directory gives you whatever your filesystem gives you for concurrent writes, and the README does not claim otherwise. If your workload depends on read-after-write consistency across multiple gateway instances writing the same key, verify that against your actual filesystem before trusting it.

Versioning is a second area to check. The posix example routes older versions to a separate directory via --versioning-dir, which means version data is a filesystem concern, not a gateway-internal log. The README does not document rollback procedures or what happens to version directories during restore.

Third, the flat-file IAM setup in the quickstart is explicitly described as being for testing. The dependency list shows LDAP, Vault, JWT and an IAM API surface, but the README itself does not explain how to move from --iam-dir to a production identity backend. If you need a documented, README-level IAM story before you commit, this is a gap.

Finally, if you have no existing storage investment, the premise does not apply. Adding a translation layer between an S3 client and an S3 backend buys you indirection, not capability.

VersityGW compared with Garage and SeaweedFS

The comparison people search for is against Garage and SeaweedFS, and the difference is architectural rather than feature-by-feature. Garage and SeaweedFS are object stores that own their data layout: they decide how objects are placed, replicated and indexed, and the filesystem underneath is an implementation detail you are not meant to touch. VersityGW inverts that. The filesystem is the source of truth and the gateway is a protocol adapter in front of it.

That inversion is why the posix backend can offer "common access to files via posix or S3", as the README puts it. You can read the same bytes with cat and with an S3 GET. You cannot generally do that with an object store that chunks and erases data internally.

The cost is that VersityGW inherits the failure modes of the filesystem it sits on, and it cannot offer guarantees the filesystem does not. A purpose-built object store can promise consistency and durability properties because it controls the whole stack. VersityGW can promise S3 protocol compatibility and let the backend answer for the rest. Choose based on which of those two you actually need.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-23. Recent releases run v1.6.0 on 2026-06-26, v1.7.0 on 2026-07-15 and v1.8.0 on 2026-09-04, so the release cadence over that window is roughly one minor version every six to eight weeks. The README describes a review process in which every pull request must pass the test suite and at least one human reviews the change, with LLMs allowed to augment but never to be the sole reviewer.

Licensing is Apache-2.0, and the repository carries both a LICENSE and a NOTICE file. Apache-2.0 permits commercial use and modification, and the NOTICE file is the part redistribution obligations usually turn on. If you ship VersityGW inside a product or a container image you hand to others, read the NOTICE and decide what you need to carry forward. That is a factual description of the licence, not legal advice.

Upgrade cost is dominated by the backend, not the binary. A new gateway version is a binary swap, and because the gateway is stateless there is no local state to migrate. What can change underneath you is on-disk layout: the versioning directory, any extended attributes the posix backend uses (the dependency list includes pkg/xattr), and backend-specific configuration. The README does not publish an upgrade guide, so the safe move is to test a new release against a copy of your data before replacing a running gateway.

Editorial conclusion

Adopt VersityGW when you already have data on a POSIX filesystem or ScoutFS and need S3-speaking tools to read and write it without a migration. Skip it if you need multi-writer semantics that the underlying filesystem cannot provide, or if you expect the wiki to answer every operational question: several flags are referenced there without being documented in the README. Before rollout, verify versioning behaviour on your filesystem, confirm which IAM backend you will use in production, and check the licence and NOTICE files against your own distribution requirements.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. versity/versitygw on GitHub