How to Run Garage S3-Compatible Object Storage on Decentralized Compute
Object storage is everywhere. Applications use it to store images, backups, documents, application assets, datasets, and just about any other file that needs to live somewhere outside the application itself.
For many developers, that means reaching for an S3-compatible storage service running in the cloud.
But S3 is an interface, not a location. S3-compatible storage implements the same API as Amazon S3, so applications and tools built for S3 can interact with it regardless of where the underlying storage is hosted. This is important because it lets us use familiar S3 tooling while running the storage itself on decentralized infrastructure.
In this guide, we’ll deploy Garage, an open-source S3-compatible object storage solution, on the Acurast decentralized processor network. We’ll configure the deployment, launch Garage using Cargo, connect to the resulting S3-compatible endpoint, and upload our first file.
By the end, you’ll have an S3-compatible storage instance running on an Acurast processor.
Storage Is a Compute Workload Too
When we think about decentralized compute, storage may not be the first workload that comes to mind. But an object storage server is ultimately software.
It needs a runtime, networking, compute resources, and somewhere to store its data. Give it the right Linux environment and it can run in many different places.
That’s where Codename Cargo comes in.
Cargo expands Acurast beyond its previous Node.js runtime by enabling full Linux-based workloads. Developers can deploy applications built with Python, Go, Rust, C++, and other technologies that run on Linux. That makes it possible to take existing software and run it across the Acurast network without rebuilding it specifically for a constrained runtime. Garage is a useful example.
Rather than building a custom storage protocol for decentralized infrastructure, we can deploy software that already implements the familiar S3 API.
The result is an object storage service that existing S3-compatible tools and applications can communicate with.
Deploying Garage on Acurast
The Acurast Example Apps repository contains a Garage example with most of the underlying setup already handled. The deployment scripts download Garage, configure the service, establish the required tunnel, and expose the information you’ll need to connect.
That leaves us with a relatively small amount of configuration before we can launch it.
Step 1: Open the Garage Example App
Start by checking out the Acurast Example Apps repository.
Navigate to the App Cargo Garage folder.
Inside, you’ll find all the files required for the deployment. Most of these are setup files and don’t need to be modified. They handle tasks such as downloading the Garage binary, preparing the environment, and establishing the tunnel that makes the service accessible.
The main configuration we’ll need to edit is the environment file.
Step 2: Configure the Deployment
The first value you’ll need is an Acurast mnemonic. This account is used to authorize and pay for the deployment. For security, don’t use the mnemonic associated with your primary wallet. Instead, generate a separate mnemonic for deployment purposes and transfer only the funds required for the workload. Sensitive wallet credentials should never be unnecessarily exposed in local configuration or CLI environments.
Next, configure the callback URL. When Acurast prepares the deployment, it generates unique URLs that you’ll use to access Garage. Those URLs need somewhere to be delivered. The example handles this by sending a POST request to the callback URL you provide. You can therefore use any service capable of receiving a POST request and displaying its contents. For this tutorial, we’re using webhook.watch. Create a personal endpoint, copy its URL, and add it to the configuration.
Once the deployment is ready, you’ll see the deployment information arrive at that endpoint.
Step 3: Configure SSH and the Network
You’ll also configure an SSH password. SSH access isn’t required during normal operation if everything works as expected. It’s primarily there as a fallback if you need to connect directly to the processor for debugging or troubleshooting.
Use a secure password. For the deployment network, mainnet is the recommended option because it provides access to a larger pool of available processors.
You’ll also see a setting for the domain suffix. At the time of this tutorial, you need to provide your own domain and configure the appropriate DNS records. This process is expected to become more automated, so the exact requirement may change as Cargo evolves.
Finally, configure the bucket name. For a basic deployment, you can simply leave this at its default value.
Review acurast.json
Before deploying, take a look at the acurast.json file. This contains additional settings that control how the workload runs.
One important parameter is the deployment duration. For this example, we’ll run Garage for four hours. That’s enough for testing, but you can increase the duration depending on what you’re building.
You can also configure the network here, although we’ll leave it on the mainnet. Make sure you’re targeting the required Android version as well. Older processor environments may not support all the features required by the Garage deployment.
With that done, we’re ready to launch the storage service.
Launch Garage
From the Garage example directory, run: acurast deploy
The Acurast CLI will walk you through the deployment process. Before submitting the deployment, you’ll be shown the associated fee. If the configured fee is higher than necessary, you can use the suggested value instead.
Confirm the deployment and Acurast takes over from there. The deployment is registered, a processor is prepared, and the required services begin automatically.
After a few minutes, you should start seeing requests arrive at the callback endpoint you configured earlier.
Verify the Deployment
The callback requests give us a useful view into what’s happening on the processor. First, you’ll see logs indicating that the environment is starting.
The processor then installs the SSH server, downloads Garage, and establishes the tunnel.
Eventually, you’ll receive the information we’re waiting for: the generated URLs and credentials required to access the Garage deployment.
The logs will then confirm that Garage is fully deployed and live. We now have an S3-compatible storage service running on an Acurast processor.
Let’s connect to it.
Connect to Your S3-Compatible Storage
For this example, we’ll use a simple UI created to demonstrate the connection.
To connect, we need four pieces of information from the deployment:
- The generated endpoint URL
- The access key ID
- The secret access key
- The bucket name
Enter those values into the client and click Connect. The client is now communicating with the Garage instance running on your Acurast processor.
Because Garage provides an S3-compatible interface, you aren’t limited to the demonstration UI. Any compatible S3 client can be configured to interact with the deployment using the appropriate endpoint and credentials.
Upload Your First File
Now, let’s make sure our storage actually works. Choose a test file, an image works nicely, and upload it through the interface.
Once the upload finishes, the file appears in the bucket. From there, we can retrieve its URL, share it, download it, or delete it. It’s a simple demonstration, but that’s also the point. From the client’s perspective, we’re interacting with familiar S3-compatible object storage. The unusual part is where that storage is running.
Instead of deploying the service to a traditional cloud instance, Garage is now running on an Acurast processor.
One Processor Is Not a Backup Strategy
There’s an important limitation to understand before treating this setup as production storage.
In this example, your data lives on a single processor. If that processor becomes unavailable, is wiped, or the Acurast deployment expires, the data stored on there can disappear permanently. For experimentation, development, and testing, that’s perfectly useful. For production storage, it isn’t enough. A production architecture needs redundancy. One approach would be to deploy multiple Garage instances across different processors and configure replication between them. Then, if one processor goes offline, another copy of the data remains available. This distinction matters because running an S3-compatible API and providing durable object storage are two different problems.
The example solves the first. A production architecture must also solve the second.
For the future, we’re exploring solutions where dependence on one processor would not be needed anymore.
More Than an S3-Compatible Server
Garage demonstrates something broader about what Cargo brings to Acurast. We aren’t creating a new storage system specifically for decentralized compute. We’re taking existing Linux software and giving it somewhere new to run. That’s an important distinction.
S3 compatibility also means applications don’t necessarily need to understand what’s happening underneath. They can continue interacting with a familiar API while the underlying infrastructure changes.
And Garage is only one example. The same approach can extend to databases, backend services, APIs, developer infrastructure, game servers, AI agents, and other Linux workloads.
The question isn’t only:
“What can we build for decentralized infrastructure?”
It’s increasingly:
“What existing infrastructure can we run there?”
With Cargo, that list gets much longer.
Watch the Full Video Tutorial
This guide covers the main steps required to deploy Garage on Acurast, but the accompanying video walkthrough shows the process from start to finish.
You’ll see how to configure the Garage example application, launch it with the Acurast CLI, follow the deployment logs, retrieve the generated credentials, connect an S3-compatible client, and upload a file.
It’s also a useful demonstration of the larger idea behind Cargo: existing Linux applications don’t necessarily need traditional cloud infrastructure to run.
Start with an S3-compatible bucket. Then see what else you can move.
