Setting Up a Self-Hosted S3 Gateway for AIOZ Storage

A self-hosted S3 gateway for AIOZ Storage exists for exactly one reason: server-side encryption, AIOZ Storage's default mode, still means AIOZ's own servers briefly hold your plaintext to decrypt it on each request. Running the gateway yourself moves that decryption step entirely inside your own environment, so AIOZ's infrastructure never touches unencrypted data at all. This article walks through actually standing one up, what each of its three setup commands does, what changes about how your applications connect afterward, and where AIOZ's documentation stops short of operational detail you'd want before running this in production.

TL;DR:

• The gateway is three commands: gw setup to configure it, gw server to run it, and gw add [access grant] to connect an AIOZ Storage access grant, which then issues S3 credentials scoped to your running gateway.
• Once it's running, your applications point their S3 client at the gateway's local endpoint instead of AIOZ's, and encryption/decryption happens inside your own environment before anything reaches AIOZ's network.
• AIOZ's documentation doesn't publish a Docker image, a port list, or a config file schema for the gateway, real operational gaps worth knowing about before you plan a production deployment around it.

Why Run a Self-Hosted Gateway at All

AIOZ Storage's default encryption mode is server-side: your data arrives at AIOZ's servers, gets encrypted there, and gets decrypted there again on every read, which means AIOZ's infrastructure genuinely handles your plaintext, briefly, on both ends of every request. For most use cases that's a reasonable trade for zero setup. For a use case where that brief exposure is unacceptable, healthcare data, financial records, anything under a contractual or regulatory requirement that a third party's servers never see plaintext at all, the self-hosted gateway is AIOZ's answer: run the encryption and decryption step yourself, so plaintext never leaves your own environment in the first place. That's the general distinction NIST's own glossary draws around end-to-end encryption more broadly, data stays encrypted across the network path rather than being decrypted by an intermediary along the way, applied here to a specific self-hosted implementation of it.

Step 1: Download and Configure the Gateway

The gateway's source is published on GitHub as w3s-gateway. After downloading it, the first command is gw setup, which walks through the gateway's own configuration, the equivalent of any CLI tool's first-run initialization step. AIOZ's documentation doesn't publish the full list of prompts or config options this step asks for, so the honest expectation going in is that gw setup is interactive and self-explanatory rather than something you can script blind on a first attempt.

Step 2: Start the Gateway

gw server starts the gateway process itself. From this point on, the gateway is a running service, not a one-shot command, it needs to keep running for anything that depends on it to work. That's a real operational commitment worth planning for before you build a workflow around it: a systemd service, a container that restarts on failure, or a process manager, so gw server doesn't quietly die and take your encrypted access down with it. AIOZ's documentation doesn't specify a supervised-process pattern or a health-check endpoint, so that reliability layer is entirely on you to build.

Step 3: Generate an Access Grant and Connect It

With the gateway running, generate an AIOZ Storage access grant the same way any other tutorial in this series covers, from your AIOZ Storage account. Then run gw add [access grant] to register that grant with your running gateway. That command is the actual handoff point: once it completes, the gateway automatically generates S3 credentials for API interaction, scoped specifically to your self-hosted gateway rather than to AIOZ's own servers directly.

What Actually Changes for Your Applications

This is the part AIOZ's own quickstart mention doesn't spell out: once the gateway is running and has its access grant, your applications stop pointing their S3 client at AIOZ's public endpoint (s3.aiozstorage.network) and instead point at your own gateway's local address, using the S3 credentials the gateway just issued. Every read and write now flows through your gateway process first, where encryption and decryption actually happen, before the (now server-side-encrypted, from AIOZ's perspective) data continues on to AIOZ's network. From AIOZ's servers' point of view, they're still just storing encrypted bytes, they simply never see the plaintext version, since your gateway did that step before the data ever left your environment.

That has a real, practical consequence worth planning around: your gateway is now a dependency in the request path for every single operation. If it's down, your applications can't reach their data through it, even though the data itself is sitting safely on AIOZ's network the whole time.

What AIOZ's Documentation Doesn't Specify

Worth being direct about the operational gaps here, since they matter if you're planning a production deployment rather than a quick test. AIOZ's documentation doesn't publish a Docker image for the gateway, doesn't publish a list of ports it listens on, and doesn't publish a config file schema beyond what gw setup walks you through interactively. That means containerizing it, exposing it behind a load balancer, or running more than one instance for redundancy are all things you'd be figuring out from the w3s-gateway source directly, not from documented deployment guidance. None of that makes the gateway not worth running, it just means treat the three-command quickstart as the starting point for evaluation, not a complete production runbook.

Is a Self-Hosted Gateway Worth Running?

The honest answer depends entirely on whether AIOZ's server-side default is actually disqualifying for your use case. If nothing in your compliance or trust model requires that a third party's infrastructure never touch plaintext, even briefly and even with AIOZ's own stated guarantee that it never stores your passphrase, server-side encryption's zero setup is the simpler, lower-maintenance choice. If that brief server-side exposure genuinely can't be accepted, the gateway is a real, working answer, at the real cost of running and maintaining another always-on service as a dependency for every request.

Frequently Asked Questions

What are the three commands to set up an AIOZ Storage gateway?
gw setup to configure it, gw server to start running it, and gw add [access grant] to connect an AIOZ Storage access grant, which then issues S3 credentials scoped to your gateway.

What does the self-hosted gateway actually protect against?
AIOZ Storage's default server-side encryption means AIOZ's own servers briefly handle your plaintext to encrypt and decrypt it. The gateway moves that step entirely into your own environment, so AIOZ's infrastructure only ever sees already-encrypted data.

Does the gateway need to run continuously?
Yes. Once started with gw server, it's a long-running service, not a one-time command. If it goes down, applications depending on it lose access through it, even though the underlying data on AIOZ's network is unaffected.

Does AIOZ publish a Docker image for the gateway?
No. AIOZ's documentation doesn't publish a Docker image, a port list, or a config file schema for the gateway. Anyone containerizing it or running it at scale is working from the w3s-gateway GitHub source directly, not documented deployment guidance.

Where do the S3 credentials for the gateway come from?
From running gw add [access grant] with an AIOZ Storage access grant you generate from your account. The gateway then automatically issues S3 credentials scoped specifically to itself, not directly to AIOZ's servers.

Should every AIOZ Storage user run a self-hosted gateway?
No. It's built for a specific requirement, a genuine need to keep plaintext data away from any third-party infrastructure entirely. For most use cases, AIOZ Storage's default server-side encryption is simpler to operate and already backed by AIOZ's own stated guarantee that it never stores your bucket passphrase.

Related Reading

• How AIOZ Storage Encryption Actually Works - the full key derivation chain and both encryption modes, including the gateway's role in the end-to-end path.
• Zero-Knowledge Encryption: AIOZ Storage Can't See Your Data - why AIOZ never holds your bucket passphrase under either encryption mode.
• AIOZ Storage Access Control: Macaroons and Access Grants - how to generate the access grant this gateway setup depends on.
• AIOZ Storage Explained: S3-Compatible Decentralized Storage - what AIOZ Storage is overall, including both encryption modes.

References

• AIOZ Storage Documentation: Gateway
• w3s-gateway Source (GitHub, AIOZNetwork)
• NIST CSRC Glossary: End-to-End Encryption