Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ohemilyy/universe/llms.txt

Use this file to discover all available pages before exploring further.

The storage-s3 extension adds an S3-backed template storage provider to Universe. Once loaded, templates can be pushed to and pulled from any AWS S3 bucket — or any S3-compatible store such as MinIO or Cloudflare R2 — without modifying the core orchestrator. Template references in instance configurations can then declare "storage": "s3" to have templates fetched from S3 at deploy time.

​
Installation

1

Place the JAR

Copy storage-s3.jar into the ./extensions/ directory.
cp storage-s3.jar ./extensions/
2

Create the config file

The extension reads ./extensions/storage-s3/config.json. Create the directory and write your credentials before starting Universe.
mkdir -p ./extensions/storage-s3
3

Write the config

Create ./extensions/storage-s3/config.json with your bucket details:
{
  "bucket": "my-universe-templates",
  "region": "us-east-1",
  "endpoint": null,
  "accessKey": "AKIAIOSFODNN7EXAMPLE",
  "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "prefix": "templates/"
}
4

Start Universe

Launch Universe. The extension registers itself under the "s3" storage key.
[SUCCESS] S3 template storage extension loaded (bucket=my-universe-templates)

​
Configuration

All fields in ./extensions/storage-s3/config.json:
FieldTypeDefaultDescription
bucketstring"universe-templates"S3 bucket name where template zips are stored.
regionstring"us-east-1"AWS region for the bucket.
endpointstring | nullnullCustom endpoint URL for S3-compatible stores (e.g., MinIO, R2). Leave null for AWS.
accessKeystring | nullnullAWS access key ID. Falls back to the default AWS credential chain if null.
secretKeystring | nullnullAWS secret access key. Falls back to the default AWS credential chain if null.
prefixstring"templates/"Key prefix prepended to all objects stored in the bucket.
When accessKey and secretKey are both null, the AWS SDK uses the standard credential chain: environment variables, ~/.aws/credentials, and instance profile. This is the recommended approach for production deployments running on EC2 or ECS.

​
S3-compatible stores

Set endpoint to your store’s URL to use a non-AWS backend: 
{
  "bucket": "universe-templates",
  "region": "auto",
  "endpoint": "https://my-account.r2.cloudflarestorage.com",
  "accessKey": "...",
  "secretKey": "..."
}

​
S3 commands

The extension registers two console commands that are available both in the interactive console and via POST /api/commands/execute.

​
s3 upload <pattern>

Uploads one or more local templates to S3. The pattern is resolved against the local ./templates/ directory. 
s3 upload server/base          # upload a single template
s3 upload server/*             # upload all templates in the "server" group
s3 upload *                    # upload all templates in all groups

​
s3 download <pattern>

Downloads one or more templates from S3 into the local ./templates/ directory. 
s3 download server/base        # download a single template
s3 download server/*           # download all templates in the "server" group
s3 download *                  # download all templates in all groups
Both commands print per-template success or failure, then a final summary line: 
Uploading template server/base to S3...
Uploaded server/base successfully
S3 upload complete: 1 succeeded, 0 failed

​
Integration with template installation

Add "storage": "s3" to any entry in a templateInstallationConfig to have Universe fetch that template from S3 when creating an instance: 
{
  "templateInstallationConfig": {
    "allOf": [
      {
        "name": "base",
        "group": "server",
        "storage": "s3",
        "priority": 0
      }
    ]
  }
}
When the instance is deployed, the template manager calls S3TemplateStorage.downloadTemplate("server", "base"), which retrieves the zip from <prefix>server/base.zip in the configured bucket, extracts it into the instance working directory, and then applies variable replacement as usual.
Templates must be uploaded to S3 before any instance that references them is created. Run s3 upload server/base (or the equivalent pattern) from any node that has the template locally.

Build docs developers (and LLMs) love

Get started for freeTalk to us